Metadata-Version: 2.4
Name: storage-actions
Version: 0.1.0
Summary: Unified object storage helpers for Alibaba OSS and S3-compatible backends
Author-email: Anderson <andersonby@163.com>
License: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: alibabacloud-oss-v2>=1.2.5
Requires-Dist: boto3>=1.40.18
Requires-Dist: httpx>=0.27.0
Description-Content-Type: text/markdown

# storage-actions

Unified object storage helpers for Alibaba OSS and S3-compatible backends such as RustFS, MinIO, and generic S3 services.

## Features

- One `StorageClient` API for Alibaba OSS and S3-compatible storage.
- Explicit `StorageConfig` / `StorageProvider` configuration with `from_env()` and `from_mapping()` helpers.
- Browser-facing public URL and presigned URL generation with separate internal and public endpoints.
- Metadata-based ACL compatibility mode for S3-compatible storage that does not support object-level ACL semantics.
- Legacy `aliyun_oss_x.Bucket`-style adapter for gradual migrations.

## Install

```bash
pip install storage-actions
```

During local development:

```bash
uv sync --dev
uv run pytest -v
uv build
```

For offline delivery, build the wheel ahead of time and install it from the artifact bundle:

```bash
uv build
pip install dist/storage_actions-*.whl
```

## Basic Usage

```python
from storage_actions import StorageClient, StorageConfig, StorageProvider

config = StorageConfig(
    provider=StorageProvider.RUSTFS,
    bucket="private-bucket",
    endpoint="http://rustfs:9000",
    public_endpoint="https://storage.example.internal",
    region="us-east-1",
    addressing_style="path",
    access_key="access-key",
    secret_key="secret-key",
    acl_compat_mode="metadata-gateway",
)

storage = StorageClient(config)
storage.put_object("reports/hello.txt", b"hello")
download_url = storage.get("reports/hello.txt", sign=True)
public_url = storage.get("reports/hello.txt", sign=False)
```

## Environment Variables

`StorageConfig.from_env()` reads these generic variables:

- `OBJECT_STORAGE_PROVIDER`: `oss`, `rustfs`, `minio`, or `s3`
- `OBJECT_STORAGE_BUCKET`
- `OBJECT_STORAGE_ENDPOINT`
- `OBJECT_STORAGE_PUBLIC_ENDPOINT`
- `OBJECT_STORAGE_CDN_PUBLIC_ENDPOINT`
- `OBJECT_STORAGE_REGION`
- `OBJECT_STORAGE_ADDRESSING_STYLE`: `path` or `virtual`
- `OBJECT_STORAGE_ACCESS_KEY`
- `OBJECT_STORAGE_SECRET_KEY`
- `OBJECT_STORAGE_ACL_COMPAT_MODE`

## ACL Compatibility

For S3-compatible backends in `metadata-gateway` mode, `put_object_acl("public-read")` writes `vv-acl=public-read` into object metadata. Setting the ACL back to `private` or `default` removes the marker.

This mode is designed for deployments where the gateway decides whether anonymous `GET/HEAD` requests may read an object by checking metadata. Signed URLs and authenticated requests should continue to go directly to the storage backend.

## Legacy Adapter

Some older code may still instantiate `aliyun_oss_x.Bucket`. `storage_actions.compat.OssBucketAdapter` implements the subset commonly used during migrations:

- `get_object`
- `get_object_to_file`
- `put_object`
- `put_object_from_file`
- `put_object_acl`
- `sign_url`
- `copy_object`
- `delete_object`
- `head_object`
- `object_exists`
- `list_objects_v2`
- `get_bucket_info`

The adapter also accepts common `aliyun_oss_x` keyword aliases such as `key=` and `filename=`.
