xy-utilities-oss 1.0.1

小阳工具库Oss模块

阿里云OSS工具库

一个简洁易用的阿里云对象存储服务(OSS) Python SDK封装库，提供常用OSS操作的便捷接口。

功能特性

• ✅ 文件上传/下载
• ✅ 字符串内容上传
• ✅ 范围下载（Range GET）- 支持增量下载
• ✅ 分页列举对象
• ✅ 批量删除对象
• ✅ 完整的类型提示支持
• ✅ 详细的中文文档

安装

pip install xy_utilities_oss

快速开始

初始化客户端

from xy_utilities_oss import OssHelper
from pathlib import Path

# 配置OSS连接信息
oss_config = {
    'auth': {
        'access_key_id': 'your_access_key_id',
        'access_key_secret': 'your_access_key_secret'
    },
    'bucket': {
        'name': 'your-bucket-name',
        'endpoint': 'https://oss-cn-shanghai.aliyuncs.com',
        'region': 'cn-shanghai'
    }
}

# 创建OSS客户端实例
oss = OssHelper(**oss_config)

上传文件

# 上传本地文件
oss.upload_file('remote/path/file.txt', Path('local_file.txt'))

# 上传字符串内容
oss.put_object('remote/path/data.json', '{"key": "value"}')

下载文件

# 下载到内存
content = oss.download('remote/path/file.txt')

# 下载到本地文件
oss.download_file('remote/path/file.txt', Path('local_file.txt'))

# 下载到本地文件（覆盖已存在的文件）
oss.download_file('remote/path/file.txt', Path('local_file.txt'), overwrite=True)

# 范围下载（从指定字节位置开始）
data = oss.download_range('remote/path/large_file.bin', start_byte=1024)

对象管理

# 检查对象是否存在
exists = oss.is_object_exist('remote/path/file.txt')

# 获取对象大小
size = oss.get_object_size('remote/path/file.txt')

# 删除单个对象
oss.delete('remote/path/file.txt')

# 批量删除对象
oss.delete('remote/path/file1.txt', 'remote/path/file2.txt', 'remote/path/file3.txt')

列举对象

# 分页列举对象
pages = oss.list_objects_paginator(prefix='remote/path/', max_keys=100)

for page in pages:
    for obj in page.contents:
        print(f'Object: {obj.key}, Size: {obj.size}, Last Modified: {obj.last_modified}')

API文档

OssHelper

主要操作类，提供所有OSS操作接口。

方法列表

• upload_file(key, filename, **kwargs) - 上传本地文件
• put_object(key, string, **kwargs) - 上传字符串内容
• download(key, **kwargs) - 下载对象到内存
• download_file(key, filename, overwrite=False, **kwargs) - 下载对象到文件
• download_range(key, start_byte, **kwargs) - 范围下载
• is_object_exist(key, **kwargs) - 判断对象是否存在
• get_object_size(key, **kwargs) - 获取对象大小
• list_objects_paginator(**kwargs) - 分页列举对象
• delete(*keys, **kwargs) - 删除对象

更多详细说明请查看代码中的文档字符串。

开发环境设置

Conda

conda create --name xy_utilities_oss -y python=3.10 && \
conda activate xy_utilities_oss && \
pip install build toml twine && \
pip install -r <(python -c "import toml; print('\n'.join(toml.load('pyproject.toml')['project']['dependencies']))")

发布

# 清理旧构建
sudo rm -rf dist *.egg-info && \
python -m build

# 发布到阿里云PyPI
twine upload -r packages-pypi dist/*

# 发布到官方PyPI
python -m twine upload dist/*

作者

Colin Chang - [e-mail]