# 阿里云OSS工具库

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

## 功能特性

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

## 安装

```bash
pip install xy_utilities_oss
```

## 快速开始

### 初始化客户端

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

### 上传文件

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

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

### 下载文件

```python
# 下载到内存
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)
```

### 对象管理

```python
# 检查对象是否存在
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')
```

### 列举对象

```python
# 分页列举对象
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

```bash
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']))")
```

## 发布

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

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

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

## 作者

Colin Chang - zhangcheng@xymind.cn