storage-actions 0.1.0

Unified object storage helpers for Alibaba OSS and S3-compatible backends

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

pip install storage-actions

During local development:

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:

uv build
pip install dist/storage_actions-*.whl

Basic Usage

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=.