Metadata-Version: 2.4
Name: current-data-py
Version: 0.1.5
Summary: Current Data protobuf messages and schema metadata
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: protobuf>=3.20
Requires-Dist: turbodata==0.1.0
Requires-Dist: grpcio>=1.51.1
Requires-Dist: alibabacloud-oss-v2<2,>=1.4.0

# current-data-py

## Management

`ManagementClient()` connects to `data.current-robotics.work:443` over TLS.
Pass `address="host:443"` to override it, or supply your own gRPC channel.

```python
from current_data_py.management import ManagementClient, Metadata, MetadataFilter

with ManagementClient() as client:
    upload = client.get_upload_credentials(data_type="CURRENT_V2")
    read = client.get_read_credentials(bucket="data-infra-raw-data")

    # Register an already uploaded file; replace the example file details.
    record = client.register_data(Metadata(
        name="recording",
        data_type="DATA_TYPE_CURRENT_V2",
        storages=[{"bucket": "data-infra-202607", "object_key": "raw_converted/recording.td"}],
        file_info={"size_bytes": 1234, "checksum": "sha256:<file-hash>"},
    ))
    for item in client.stream_data_references(MetadataFilter(name_prefix="recording")):
        print(item.id, item.storages)
```

`Metadata`, `MetadataFilter`, and responses are Protobuf objects exported by the
SDK. Registration only saves metadata; it does not upload files. Credential
calls return fresh credentials without caching. Calls accept `timeout=` and
`metadata=` for gRPC headers.

## OSS

```python
from current_data_py.management import ManagementClient
from current_data_py.oss import OSSClient

with ManagementClient() as management:
    with OSSClient(management, permission="read", bucket="data-infra-raw-data") as source:
        source.download_file("collections/recording/input.h5", "/tmp/input.h5")

    # Convert the input into /tmp/output.td before uploading.
    with OSSClient(management, permission="upload", data_type="CURRENT_V2") as destination:
        key = destination.object_prefix + "recording/output.td"
        destination.upload_file(key, "/tmp/output.td")
        print(destination.bucket, key)  # Use these values when registering metadata.
```

- Read access covers the requested bucket, subject to server permissions.
  Uploads default to `data_type="RAW"`; the server chooses the bucket and prefix.
- Credentials refresh automatically. Expired tokens trigger one refresh and retry.
- Uploads reject overwrites by default; set `forbid_overwrite=False` to replace.
  Downloads replace the local file only on success; its parent directory must exist.
- Uploads use a single PutObject request ([maximum 5 GiB](https://www.alibabacloud.com/help/en/oss/developer-reference/upload-files-using-oss-sdk-for-python-v2/)); multipart upload is not supported.
- Supply `region=` for custom upload endpoints. Deploy the current management
  credential API before using the new bucket and data-type arguments.

## 打包

```bash
cd current_data_py  # 从仓库根目录执行
# 发布新版本前，更新 pyproject.toml 中的 version
python -m pip install build twine
rm -rf build dist
python -m build
```

## 测试

```bash
python -m twine check dist/*
python tests/check_distribution.py
python -m pip install --force-reinstall dist/*.whl
python -I tests/check_package.py
python -I tests/check_management.py
python -I tests/check_remote.py
python -I tests/check_oss.py
```

## 推送

```bash
# TestPyPI
python -m twine upload --repository testpypi dist/*

# PyPI
python -m twine upload dist/*
```
