fundrive-ossutil 0.1.4
阿里云OSS命令行工具ossutil的Python包装器，提供更加友好的Python接口
License: MIT
Requires Python: >=3.8
Keywords: oss, aliyun, ossutil, cloud, storage

# fundrive-ossutil

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


## 功能特性

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

## 快速开始

### 安装

```bash
pip install fundrive-ossutil
```

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

### 安装流程说明

#### 第一步：安装 Python 包
```bash
pip install fundrive-ossutil
```

#### 第二步：自动安装 ossutil（推荐）
```python
# 首次使用时会自动检测并安装ossutil
from fundrives.ossutil import OSSUtil

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

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

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

**方式1：使用命令行工具**
```bash
pip install fundrive-ossutil
install-ossutil
```

**方式2：使用Python代码**
```python
from fundrives.ossutil import install_ossutil
success = install_ossutil()
if success:
    print("ossutil安装成功！")
```

**方式3：确保安装函数**
```python
from fundrives.ossutil import ensure_ossutil_installed
if ensure_ossutil_installed():
    print("ossutil可用")
else:
    print("ossutil不可用，请检查安装")
```

#### 禁用自动安装
如果您不希望自动安装ossutil：
```bash
export FUNDRIVE_OSSUTIL_NO_AUTO_INSTALL=1
```

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

### 基本配置

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

创建配置文件 `~/.ossutilconfig`：
```ini
[Credentials]
language=CH
endpoint=https://oss-cn-hangzhou.aliyuncs.com
accessKeyID=your_access_key_id
accessKeySecret=your_access_key_secret
```

2. **使用环境变量**

```bash
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"
```

### 基本使用

```python
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("删除成功")
```

## 使用说明

### 基本用法

#### 文件操作

```python
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")
```

#### 对象管理

```python
# 列出所有对象
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

```python
from fundrives.ossutil import install_ossutil

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

#### 错误处理

```python
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](docs/API.md)

## 开发指南

### 环境搭建

1. 克隆项目
```bash
git clone https://github.com/farfarfun/fundrive-ossutil.git
cd fundrive-ossutil
```

2. 安装开发依赖
```bash
pip install -e .
pip install pytest pytest-cov black flake8 mypy
```

3. 运行测试
```bash
pytest --cov=src/fundrives/ossutil
```

### 代码规范

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

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

### 测试

```bash
# 运行所有测试
pytest

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

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

## 变更日志

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

## 许可证

本项目采用 MIT 许可证。详情请参阅 [LICENSE](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官方文档](https://help.aliyun.com/zh/oss/)
- [ossutil命令行工具](https://help.aliyun.com/zh/oss/developer-reference/ossutil-overview/)
- [Python OSS SDK](https://help.aliyun.com/zh/oss/developer-reference/python/)