Metadata-Version: 2.4
Name: current-data-py
Version: 0.1.6
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 over TLS. Pass `address=` to configure the service,
or supply your own gRPC channel.

The examples below read deployment-specific values from environment variables.
Set `MANAGEMENT_ADDRESS` to your service address and `UPLOAD_DATA_TYPE` to a valid
integer enum value supplied by your deployment administrator. Set the bucket and
object-key variables to resources you are authorized to access. These variables
are read explicitly by the examples; they are not automatic SDK configuration.

```python
import os

from current_data_py.management import ManagementClient, Metadata, MetadataFilter

with ManagementClient(address=os.environ["MANAGEMENT_ADDRESS"]) as client:
    upload = client.get_upload_credentials(data_type=int(os.environ["UPLOAD_DATA_TYPE"]))
    read = client.get_read_credentials(bucket=os.environ["READ_BUCKET"])

    # Register an already uploaded file; replace the example file details.
    record = client.register_data(Metadata(
        name="recording",
        data_type=int(os.environ["UPLOAD_DATA_TYPE"]),
        storages=[{"bucket": os.environ["UPLOADED_BUCKET"], "object_key": os.environ["UPLOADED_OBJECT_KEY"]}],
        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.

## Remote TD reads

`DataClient.open_td()` accepts an optional `bucket` argument. Without it, reads
use the management service's `OSS_READ_BUCKET` and `OSS_READ_PREFIX` defaults.
With it, the SDK requests whole-bucket read credentials, limited by the server's
RAM role, and selects the first matching storage in the reference. An explicit
bucket does not inherit the default prefix. Default and per-bucket credentials
are cached separately and refreshed automatically.

```python
import os

from current_data_py.remote import DataClient

with DataClient(address=os.environ["MANAGEMENT_ADDRESS"]) as client:
    for reference in client.iter_data():
        # Use the service's default bucket and prefix.
        with client.open_td(reference) as reader:
            print(reader.summary())

        # Request read access to the selected bucket.
        with client.open_td(reference, bucket=os.environ["READ_BUCKET"]) as reader:
            print(reader.summary())
```

The explicit bucket must contain a storage listed in the reference. This uses
the existing bucket-aware management API; no protocol changes are required.

## OSS

```python
import os

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

with ManagementClient(address=os.environ["MANAGEMENT_ADDRESS"]) as management:
    with OSSClient(management, permission="read", bucket=os.environ["READ_BUCKET"]) as source:
        source.download_file(os.environ["SOURCE_OBJECT_KEY"], "/tmp/input.h5")

    # Convert the input into /tmp/output.td before uploading.
    with OSSClient(management, permission="upload", data_type=int(os.environ["UPLOAD_DATA_TYPE"])) 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.
  The server chooses the upload bucket and prefix based on the requested data type.
- 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/*
```
