fundrive-ossutil

阿里云OSS命令行工具ossutil的Python包装器，提供更加友好的Python接口。本项目将ossutil的安装和使用包装成一个Python包，当用户安装Python包的时候，会按照ossutil的安装流程，自动下载ossutil的安装包并安装。

功能特性

• 🚀 简单易用的Python API
• 📁 支持文件上传、下载、删除等基本操作
• 📋 支持对象列表查询
• 🔧 自动安装和配置ossutil命令行工具
• 📝 完整的日志记录和错误处理
• 🔒 支持多种认证方式
• 🌐 兼容所有阿里云OSS区域

快速开始

安装

pip install fundrive-ossutil

🎉 智能自动安装: 当您首次使用 OSSUtil 类时，程序会自动检测并安装 ossutil 命令行工具！

安装流程说明

第一步：安装 Python 包

pip install fundrive-ossutil

第二步：自动安装 ossutil（推荐）

# 首次使用时会自动检测并安装ossutil
from fundrives.ossutil import OSSUtil

# 如果ossutil未安装，会看到以下提示：
# 🔧 fundrive-ossutil: 检测到ossutil未安装，正在自动安装...
# 💡 如需禁用自动安装，请设置环境变量: FUNDRIVE_OSSUTIL_NO_AUTO_INSTALL=1
# ✅ fundrive-ossutil: ossutil安装成功！

oss = OSSUtil()  # 现在可以正常使用了

手动安装方式

如果您希望手动控制安装过程：

方式1：使用命令行工具

pip install fundrive-ossutil
install-ossutil

方式2：使用Python代码

from fundrives.ossutil import install_ossutil
success = install_ossutil()
if success:
    print("ossutil安装成功！")

方式3：确保安装函数

from fundrives.ossutil import ensure_ossutil_installed
if ensure_ossutil_installed():
    print("ossutil可用")
else:
    print("ossutil不可用，请检查安装")

禁用自动安装

如果您不希望自动安装ossutil：

export FUNDRIVE_OSSUTIL_NO_AUTO_INSTALL=1

设置此环境变量后，程序不会自动安装ossutil，您需要手动安装。

基本配置

1. 使用配置文件（推荐）

创建配置文件 ~/.ossutilconfig：

[Credentials]
language=CH
endpoint=https://oss-cn-hangzhou.aliyuncs.com
accessKeyID=your_access_key_id
accessKeySecret=your_access_key_secret

2. 使用环境变量

export OSS_ENDPOINT="https://oss-cn-hangzhou.aliyuncs.com"
export OSS_ACCESS_KEY_ID="your_access_key_id"
export OSS_ACCESS_KEY_SECRET="your_access_key_secret"

基本使用

from fundrives.ossutil import OSSUtil

# 初始化（使用配置文件）
oss = OSSUtil()

# 或者直接传入参数
oss = OSSUtil(
    endpoint="https://oss-cn-hangzhou.aliyuncs.com",
    access_key_id="your_access_key_id",
    access_key_secret="your_access_key_secret"
)

# 上传文件
success = oss.upload_file("./local_file.txt", "remote/path/file.txt", "my-bucket")
if success:
    print("上传成功")

# 下载文件
success = oss.download_file("remote/path/file.txt", "./downloaded_file.txt", "my-bucket")
if success:
    print("下载成功")

# 列出对象
objects = oss.list_objects(prefix="images/", bucket="my-bucket")
for obj in objects:
    print(obj)

# 删除对象
success = oss.delete_object("remote/path/file.txt", "my-bucket")
if success:
    print("删除成功")

使用说明

基本用法

文件操作

from fundrives.ossutil import OSSUtil

oss = OSSUtil()

# 上传单个文件
oss.upload_file("local.txt", "remote/file.txt", "bucket-name")

# 批量上传
files = [
    ("local1.txt", "remote/file1.txt"),
    ("local2.txt", "remote/file2.txt")
]
for local, remote in files:
    oss.upload_file(local, remote, "bucket-name")

# 下载文件
oss.download_file("remote/file.txt", "local_copy.txt", "bucket-name")

对象管理

# 列出所有对象
all_objects = oss.list_objects(bucket="bucket-name")

# 按前缀过滤
image_objects = oss.list_objects(prefix="images/", bucket="bucket-name")

# 删除对象
oss.delete_object("remote/unwanted_file.txt", "bucket-name")

高级功能

自动安装ossutil

from fundrives.ossutil import install_ossutil

# 自动检测并安装ossutil命令行工具
install_ossutil()

错误处理

from fundrives.ossutil import OSSUtil

oss = OSSUtil()

try:
    success = oss.upload_file("nonexistent.txt", "remote/file.txt", "bucket")
    if not success:
        print("上传失败，请检查日志")
except Exception as e:
    print(f"发生异常: {e}")

API文档

详细的API文档请参考：docs/API.md

开发指南

环境搭建

1. 克隆项目

git clone https://github.com/farfarfun/fundrive-ossutil.git
cd fundrive-ossutil

2. 安装开发依赖

pip install -e .
pip install pytest pytest-cov black flake8 mypy

3. 运行测试

pytest --cov=src/fundrives/ossutil

代码规范

• 遵循PEP8规范
• 使用中文注释
• 函数和类必须有文档字符串
• 使用 funutil.getLogger 进行日志记录

详细的开发规范请参考：docs/DEVELOPMENT_GUIDE.md

测试

# 运行所有测试
pytest

# 生成覆盖率报告
pytest --cov=src/fundrives/ossutil --cov-report=html

# 运行特定测试
pytest tests/test_ossutil.py

变更日志

详细的版本变更记录请参考：docs/CHANGELOG.md

许可证

本项目采用 MIT 许可证。详情请参阅 LICENSE 文件。

贡献指南

我们欢迎所有形式的贡献！请遵循以下步骤：

1. Fork 本项目
2. 创建您的功能分支 (git checkout -b feature/AmazingFeature)
3. 提交您的更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启一个 Pull Request

贡献要求

• 代码必须通过所有测试
• 新功能需要添加相应的测试
• 遵循项目的代码规范
• 更新相关文档

联系方式

• 项目主页: https://github.com/farfarfun/fundrive-ossutil
• PyPI: https://pypi.org/project/fundrive-ossutil/
• 组织: https://github.com/farfarfun
• 问题反馈: https://github.com/farfarfun/fundrive-ossutil/issues

相关项目

fundrive-ossutil 是 farfarfun 生态系统的一部分：

• fundrive: https://github.com/farfarfun/fundrive - 统一的云存储驱动器
• funutil: https://pypi.org/project/funutil/ - 通用工具库
• 更多项目: https://github.com/farfarfun

参考资料

• 阿里云OSS官方文档
• ossutil命令行工具
• Python OSS SDK