Metadata-Version: 2.4
Name: huace-aigc-oss-proxy-client
Version: 0.1.3
Summary: 华策 AIGC OSS Proxy Client - 统一 RustFS / 阿里云 OSS / 七牛云，支持下载降级与上传路由
Author-email: Huace <support@huace.com>
License: MIT
Project-URL: Homepage, https://github.com/huace/huace-aigc-oss-proxy-client
Project-URL: Repository, https://github.com/huace/huace-aigc-oss-proxy-client
Keywords: aigc,oss,huace,sdk,rustfs,aliyun,s3
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Provides-Extra: aliyun
Requires-Dist: oss2>=2.18.0; extra == "aliyun"
Provides-Extra: rustfs
Requires-Dist: boto3>=1.34.0; extra == "rustfs"
Provides-Extra: qiniu
Requires-Dist: qiniu>=7.12.0; extra == "qiniu"
Requires-Dist: requests>=2.20.0; extra == "qiniu"
Provides-Extra: all
Requires-Dist: oss2>=2.18.0; extra == "all"
Requires-Dist: boto3>=1.34.0; extra == "all"
Requires-Dist: qiniu>=7.12.0; extra == "all"
Requires-Dist: requests>=2.20.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-env>=1.0.0; extra == "dev"
Requires-Dist: moto[s3]>=5.0.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"

# AIGC OSS Proxy Python SDK

[![Python Version](https://img.shields.io/pypi/pyversions/huace-aigc-oss-proxy-client.svg)](https://pypi.org/project/huace-aigc-oss-proxy-client/)

面向华策 AIGC 插件的统一对象存储 SDK：内网 **RustFS**（S3 兼容）、**阿里云 OSS**、**七牛云**，支持下载自动降级与上传内外网路由。

详细设计见 [DESIGN.md](./DESIGN.md)。

## 安装

```bash
# 全量后端（RustFS + 阿里云 + 七牛）
pip install huace-aigc-oss-proxy-client[all]

# 仅阿里云 OSS
pip install huace-aigc-oss-proxy-client[aliyun]

# 仅 RustFS / S3 兼容内网（boto3）
pip install huace-aigc-oss-proxy-client[rustfs]

# 仅七牛云
pip install huace-aigc-oss-proxy-client[qiniu]
```

## 本地 RustFS 开发环境

```bash
docker compose -f docker-compose/rustfs/docker-compose.yml up -d
```

控制台：http://127.0.0.1:9001 （`minioadmin` / `minioadmin`）  
API：`http://127.0.0.1:9000`，默认桶 `aigc-intranet`。

## 环境变量

完整示例见 [env.example](./env.example)，复制为 `.env` 后修改。

```bash
# RustFS 内网
OSS_RUSTFS_ENABLED=true
OSS_RUSTFS_ENDPOINT=http://127.0.0.1:9000
OSS_RUSTFS_ACCESS_KEY=minioadmin
OSS_RUSTFS_SECRET_KEY=minioadmin
OSS_RUSTFS_BUCKET=aigc-intranet

# 阿里云（兼容旧变量 OSS_ACCESS_KEY_ID 等）
OSS_ALIYUN_ENABLED=true
OSS_ALIYUN_ENDPOINT=https://oss-cn-hangzhou.aliyuncs.com
OSS_ALIYUN_ACCESS_KEY_ID=***
OSS_ALIYUN_ACCESS_KEY_SECRET=***
OSS_ALIYUN_BUCKET=huace-shortmovie

# 策略
OSS_DOWNLOAD_PRIORITY=rustfs,aliyun
OSS_UPLOAD_INTRANET_BACKEND=rustfs
OSS_UPLOAD_EXTRANET_BACKEND=aliyun
OSS_KEY_PREFIX=plugin-tts-indextts
OSS_STICKY_SESSION_ENABLED=true
OSS_FALLBACK_ENABLED=true
```

## 快速开始

```python
from huace_aigc_oss import OssClient, UploadMode

client = OssClient.from_env()

# 下载：RustFS 优先，失败自动切阿里云；同进程会记住成功的后端
local = client.download("task-1/output.wav", "/tmp/output.wav")

# 上传：默认内网 RustFS，无自动降级
client.upload("task-1/output.wav", "/tmp/output.wav")

# 上传：强制外网阿里云
client.upload("task-1/output.wav", "/tmp/output.wav", mode=UploadMode.EXTRANET)

client.exists("task-1/output.wav")
```

## 插件集成示例

```python
from huace_aigc_oss import OssClient, UploadMode

_client = None

def get_client() -> OssClient:
    global _client
    if _client is None:
        _client = OssClient.from_env()
    return _client

def upload_local_file(local_path: str, oss_key: str, extranet: bool = False) -> str:
    mode = UploadMode.EXTRANET if extranet else UploadMode.INTRANET
    result = get_client().upload(oss_key, local_path, mode=mode)
    return result.url or oss_key
```

## 发布

见 [PUBLISH.md](./PUBLISH.md)。复制 `.pypirc.example` 为 `.pypirc` 并填入 PyPI Token。

```bash
python build_and_publish.py
```

## 核心行为

| 操作 | 行为 |
|------|------|
| `download` | 按优先级尝试，失败降级；进程内 sticky 记住成功后端 |
| `upload` | 确定性单后端，失败不降级 |
| `exists` | 与 download 相同优先级链 |
