xy-utilities-oss 1.0.2

小阳工具库Oss模块 — 阿里云OSS便捷操作封装

xy-utilities-oss

阿里云 OSS Python SDK 封装库，提供简洁易用的对象存储操作接口。

功能特性

• 文件上传 / 字符串内容上传
• 下载到内存、本地文件，或范围下载（Range GET）
• 检查对象是否存在，获取对象大小
• 分页列举对象
• 单个 / 批量删除对象
• 完整类型提示

安装

pip install xy_utilities_oss

快速开始

初始化

from xy_utilities_oss import OssHelper
from pathlib import Path

oss = OssHelper(
    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.upload_file("remote/path/file.txt", Path("local_file.txt"))

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

下载

# 下载到内存（返回 bytes）
content: bytes = 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)

# 范围下载（从指定字节偏移开始，适用于 AppendObject 增量读取）
data: bytes = oss.download_range("remote/path/large_file.bin", start_byte=1024)

对象管理

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

# 获取对象大小（字节），不存在时返回 None
size: int | None = oss.get_object_size("remote/path/file.txt")

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

# 批量删除
oss.delete("remote/path/file1.txt", "remote/path/file2.txt")

列举对象

pages = oss.list_objects_paginator(prefix="remote/path/", max_keys=100)

for page in pages:
    for obj in page.contents:
        print(f"{obj.key}  size={obj.size}  modified={obj.last_modified}")

API 参考

OssHelper(auth, bucket)

方法	说明
upload_file(key, filename, **kwargs)	上传本地文件
put_object(key, content, **kwargs)	上传字符串内容
download(key, **kwargs) → bytes	下载到内存
download_file(key, filename, overwrite, **kwargs)	下载到本地文件
download_range(key, start_byte, **kwargs) → bytes	范围下载
is_object_exist(key, **kwargs) → bool	判断对象是否存在
get_object_size(key, **kwargs) → int | None	获取对象大小
list_objects_paginator(**kwargs) → Iterator	分页列举对象
delete(*keys, **kwargs)	删除一个或多个对象

详细参数说明请参阅各方法的 docstring。

开发环境

conda create -n xy_utilities_oss python=3.11 -y
conda activate xy_utilities_oss
pip install build twine
pip install "alibabacloud-oss-v2>=1.1.3"

发布

# 构建
rm -rf dist *.egg-info
python -m build

# 发布到私有 PyPI
twine upload -r packages-pypi dist/*

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