zuadoss 1.0.1

ZUAD OSS Python SDK - 兼容OSS接口的对象存储Python客户端SDK

ZUAD OSS Python SDK

🚀 ZUAD OSS Python SDK 是一个兼容OSS接口的对象存储Python客户端SDK，为ZUAD OSS服务提供完整的Python API支持。

🔗 PyPI项目页面

📦 https://pypi.org/project/zuadoss/

✨ 特性

• 🔄 完全兼容OSS SDK接口 - 无缝迁移，零学习成本
• 📦 完整的对象存储功能 - 支持上传、下载、删除、列举等所有基本操作
• 🔧 分片上传支持 - 支持大文件的分片上传和断点续传
• 🔐 安全认证 - 支持访问密钥认证和预签名URL
• 📊 丰富的元数据支持 - 支持自定义HTTP头部和对象元数据
• 🌐 HTTP范围请求 - 支持部分内容下载
• 🛡️ 完善的异常处理 - 详细的错误信息和异常类型
• 📝 类型提示支持 - 完整的类型注解，IDE友好

📦 安装

从PyPI安装（推荐）

pip install zuadoss

从源码安装

# 从源码安装
git clone <repository-url>
cd zuadoss
pip install -e .

# 或者直接安装依赖
pip install requests

🚀 发布到PyPI

🎯 使用自动化发布脚本（推荐）

项目提供了专门的publish.py发布脚本，可以自动化整个发布流程：

可用命令

# 检查发布环境
python publish.py check

# 清理构建文件
python publish.py clean

# 构建包
python publish.py build

# 构建并上传到测试PyPI
python publish.py test

# 构建并上传到正式PyPI
python publish.py release

# 完整测试流程（推荐首次发布使用）
python publish.py full

推荐发布流程

1. 首次发布或重大更新：

# 完整测试流程
python publish.py full

# 验证测试PyPI安装
pip install --index-url https://test.pypi.org/simple/ zuadoss

# 测试通过后发布到正式PyPI
python publish.py release

2. 快速发布（已验证的更新）：

# 直接发布到正式PyPI
python publish.py release

3. 仅测试构建：

# 检查环境和构建
python publish.py check
python publish.py build

发布脚本特性

• ✅ 自动环境检查 - 验证twine和build工具是否安装
• 🧹 自动清理 - 清理旧的构建文件
• 📦 自动构建 - 构建wheel和源码包
• 🔍 质量检查 - 使用twine验证包质量
• 🚀 一键发布 - 支持测试PyPI和正式PyPI
• 🔒 安全确认 - 正式发布前需要确认
• 📝 详细日志 - 显示每个步骤的执行状态

手动发布步骤

开发者发布步骤

如果你想将SDK发布到PyPI，请遵循以下步骤：

1. 安装发布工具

pip install build twine

2. 构建分发包

# 构建wheel和源码包
python -m build

# 检查生成的文件
ls dist/
# zuadoss-1.0.0-py3-none-any.whl
# zuadoss-1.0.0.tar.gz

3. 测试发布（推荐）

先发布到TestPyPI进行测试：

# 上传到TestPyPI
python -m twine upload --repository testpypi dist/*

# 从TestPyPI安装测试
pip install --index-url https://test.pypi.org/simple/ zuadoss

4. 正式发布

⚠️ 注意：发布到正式PyPI后无法撤销！

# 上传到正式PyPI
python -m twine upload dist/*

# 如果在Windows系统遇到编码问题，使用：
set PYTHONIOENCODING=utf-8 && python -m twine upload dist/*

5. 验证发布

# 安装已发布的包
pip install zuadoss

# 测试导入
python -c "import zuadoss; print(zuadoss.__version__)"

🤖 打包自动化脚本

为了简化打包流程，可以创建自动化脚本：

build.sh (Linux/macOS)

#!/bin/bash
set -e

echo "🧹 清理旧的构建文件..."
rm -rf build/ dist/ *.egg-info/

echo "🔍 检查版本一致性..."
SETUP_VERSION=$(grep version setup.py | cut -d"'" -f2)
INIT_VERSION=$(python -c "import zuadoss; print(zuadoss.__version__)")

if [ "$SETUP_VERSION" != "$INIT_VERSION" ]; then
    echo "❌ 版本号不匹配: setup.py($SETUP_VERSION) vs __init__.py($INIT_VERSION)"
    exit 1
fi

echo "📦 构建分发包..."
python -m build

echo "✅ 验证分发包..."
python -m twine check dist/*

echo "📋 分发包内容:"
ls -la dist/

echo "🎉 打包完成! 版本: $SETUP_VERSION"
echo "💡 下一步: python -m twine upload --repository testpypi dist/*"

build.bat (Windows)

@echo off
echo 🧹 清理旧的构建文件...
rmdir /s /q build 2>nul
rmdir /s /q dist 2>nul
for /d %%i in (*.egg-info) do rmdir /s /q "%%i" 2>nul

echo 📦 构建分发包...
python -m build

echo ✅ 验证分发包...
python -m twine check dist/*

echo 📋 分发包内容:
dir dist\

echo 🎉 打包完成!
echo 💡 下一步: set PYTHONIOENCODING=utf-8 ^&^& python -m twine upload --repository testpypi dist/*

Windows用户注意事项

在Windows系统上使用twine可能会遇到Unicode编码问题，解决方案：

# PowerShell中设置环境变量
$env:PYTHONIOENCODING="utf-8"
python -m twine upload dist/*

# 或者使用单行命令
set PYTHONIOENCODING=utf-8 && python -m twine upload dist/*

版本管理

更新版本号：

1. 修改 setup.py 中的 version 参数
2. 修改 zuadoss/__init__.py 中的 __version__
3. 重新构建和发布

# setup.py
setup(
    name="zuadoss",
    version="1.0.1",  # 更新版本号
    # ...
)

# zuadoss/__init__.py
__version__ = "1.0.1"  # 更新版本号

🚀 快速开始

基本使用

import zuadoss
from zuadoss import Auth, Bucket

# 初始化OSS客户端（兼容标准OSS接口）
auth = Auth('your_access_key_id', 'your_access_key_secret')
bucket = Bucket(auth, 'http://localhost:8000', 'your-bucket-name')

# 创建存储桶
bucket.create_bucket(permission='private')

# 上传对象
result = bucket.put_object('test.txt', 'Hello, ZUAD OSS!')
print(f"上传成功，ETag: {result.etag}")

# 从本地文件上传（兼容标准OSS接口）
result = bucket.put_object_from_file('upload.txt', '/path/to/local/file.txt')
print(f"文件上传成功，ETag: {result.etag}")

# 下载对象
obj = bucket.get_object('test.txt')
content = obj.content.decode('utf-8')
print(f"下载内容: {content}")

# 列举对象
objects = bucket.list_objects()
for obj in objects.object_list:
    print(f"对象: {obj.key}, 大小: {obj.size}")

# 删除对象
bucket.delete_object('test.txt')

高级功能

# 带自定义头部的上传
headers = {
    'Content-Type': 'text/plain; charset=utf-8',
    'x-oss-meta-author': 'ZUAD OSS Team',
    'x-oss-meta-description': '自定义元数据'
}
bucket.put_object('custom.txt', '内容', headers=headers)

# 范围下载
obj = bucket.get_object('large-file.txt', byte_range=(0, 1023))  # 下载前1KB

# 分片上传
upload_result = bucket.init_multipart_upload('large-file.txt')
upload_id = upload_result.upload_id

# 上传分片
parts = []
for i, chunk in enumerate(file_chunks, 1):
    part_result = bucket.upload_part('large-file.txt', upload_id, i, chunk)
    parts.append(zuadoss.PartInfo(part_number=i, etag=part_result.etag))

# 完成分片上传
bucket.complete_multipart_upload('large-file.txt', upload_id, parts)

# 生成预签名URL
import time
expires = int(time.time()) + 3600  # 1小时后过期
signed_url = bucket.sign_url('GET', 'test.txt', expires)

📚 API 参考

Auth 类

auth = Auth(access_key_id, access_key_secret)

认证类，用于生成请求签名。

Bucket 类

bucket = Bucket(auth, endpoint, bucket_name, is_cname=False)

存储桶操作类，提供所有对象存储功能。

存储桶操作

• create_bucket(permission='private') - 创建存储桶
• delete_bucket() - 删除存储桶
• bucket_exists() - 检查存储桶是否存在
• get_bucket_info() - 获取存储桶信息

对象操作

• put_object(key, data, headers=None) - 上传对象
• put_object_from_file(key, filename, headers=None) - 从本地文件上传对象
• get_object(key, byte_range=None, headers=None) - 下载对象
• delete_object(key) - 删除对象
• object_exists(key) - 检查对象是否存在
• get_object_meta(key) - 获取对象元数据
• list_objects(prefix='', delimiter='', marker='', max_keys=1000) - 列举对象

分片上传

• init_multipart_upload(key, headers=None) - 初始化分片上传
• upload_part(key, upload_id, part_number, data) - 上传分片
• complete_multipart_upload(key, upload_id, parts) - 完成分片上传
• abort_multipart_upload(key, upload_id) - 取消分片上传

其他功能

• sign_url(method, key, expires, headers=None, params=None) - 生成预签名URL

🔧 配置选项

连接配置

bucket = Bucket(
    auth=auth,
    endpoint='http://localhost:8000',
    bucket_name='my-bucket',
    is_cname=False,           # 是否使用CNAME
    connect_timeout=60,       # 连接超时时间（秒）
    read_timeout=120          # 读取超时时间（秒）
)

自定义HTTP会话

import requests

session = requests.Session()
session.proxies = {'http': 'http://proxy:8080'}

bucket = Bucket(auth, endpoint, bucket_name, session=session)

🛡️ 异常处理

SDK提供了完善的异常处理机制：

try:
    bucket.get_object('non-existent-key')
except zuadoss.NoSuchKey as e:
    print(f"对象不存在: {e.key}")
except zuadoss.AccessDenied as e:
    print(f"访问被拒绝: {e.message}")
except zuadoss.ZuadOSSError as e:
    print(f"OSS错误: {e.error_code} - {e.message}")
    print(f"状态码: {e.status_code}")
    print(f"请求ID: {e.request_id}")

异常类型

• ZuadOSSError - 基础异常类
• NoSuchBucket - 存储桶不存在
• NoSuchKey - 对象不存在
• AccessDenied - 访问被拒绝
• InvalidAccessKeyId - 无效的访问密钥ID
• SignatureDoesNotMatch - 签名不匹配
• BucketAlreadyExists - 存储桶已存在
• BucketNotEmpty - 存储桶非空
• NetworkError - 网络错误
• ServerError - 服务器错误

🔄 从阿里云OSS迁移

ZUAD OSS SDK与阿里云OSS SDK接口完全兼容，迁移只需要修改导入和初始化：

# 阿里云OSS
import oss2
auth = oss2.Auth(access_key_id, access_key_secret)
bucket = oss2.Bucket(auth, endpoint, bucket_name)

# ZUAD OSS
import zuadoss
auth = zuadoss.Auth(access_key_id, access_key_secret)
bucket = zuadoss.Bucket(auth, endpoint, bucket_name)

# 其他API调用完全相同！

📝 示例代码

查看 example.py 文件获取完整的使用示例。

🤝 贡献

欢迎提交Issue和Pull Request！

📄 许可证

MIT License

🔗 相关链接

• 📦 PyPI项目页面
• 🚀 ZUAD OSS 服务端
• 📚 阿里云OSS Python SDK

---