Metadata-Version: 2.4
Name: fundrive-ossutil
Version: 0.1.2
Summary: 阿里云OSS命令行工具ossutil的Python包装器，提供更加友好的Python接口
Project-URL: Organization, https://github.com/farfarfun
Project-URL: Repository, https://github.com/farfarfun/fundrive-ossutil
Project-URL: Releases, https://github.com/farfarfun/fundrive-ossutil/releases
Author-email: 牛哥 <niuliangtao@qq.com>, farfarfun <farfarfun@qq.com>
Maintainer-email: 牛哥 <niuliangtao@qq.com>, farfarfun <farfarfun@qq.com>
License: MIT
License-File: LICENSE
Keywords: aliyun,cloud,oss,ossutil,storage
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: File Transfer Protocol (FTP)
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Archiving
Requires-Python: >=3.8
Requires-Dist: funutil>=0.1.0
Requires-Dist: requests>=2.25.0
Provides-Extra: dev
Requires-Dist: black>=22.0.0; extra == 'dev'
Requires-Dist: flake8>=5.0.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pre-commit>=2.20.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Provides-Extra: test
Requires-Dist: pytest-cov>=4.0.0; extra == 'test'
Requires-Dist: pytest-mock>=3.10.0; extra == 'test'
Requires-Dist: pytest>=7.0.0; extra == 'test'
Description-Content-Type: text/markdown

# fundrive-ossutil

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


## 功能特性

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

## 快速开始

### 安装

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

**注意**: 安装完成后，当您首次导入模块时，系统会自动检测并安装ossutil命令行工具。如果您希望禁用自动安装，可以设置环境变量：

```bash
export FUNDRIVE_OSSUTIL_NO_AUTO_INSTALL=1
pip install fundrive-ossutil
```

或者在Python代码中：

```python
import os
os.environ['FUNDRIVE_OSSUTIL_NO_AUTO_INSTALL'] = '1'
from fundrives.ossutil import install_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/)