Metadata-Version: 2.4
Name: xy_utilities_oss
Version: 1.0.2
Summary: 小阳工具库Oss模块 — 阿里云OSS便捷操作封装
Author-email: Colin Chang <zhangcheng@xymind.cn>
Project-URL: Homepage, https://codeup.aliyun.com/xytech/xiaoyang/pythonutilities
Project-URL: Repository, https://codeup.aliyun.com/xytech/xiaoyang/pythonutilities
Keywords: oss,aliyun,alibabacloud,storage
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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 :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: alibabacloud-oss-v2>=1.1.3

# xy-utilities-oss

[![PyPI version](https://img.shields.io/pypi/v/xy_utilities_oss)](https://pypi.org/project/xy_utilities_oss/)
[![Python](https://img.shields.io/pypi/pyversions/xy_utilities_oss)](https://pypi.org/project/xy_utilities_oss/)

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

## 功能特性

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

## 安装

```bash
pip install xy_utilities_oss
```

## 快速开始

### 初始化

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

### 上传

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

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

### 下载

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

### 对象管理

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

### 列举对象

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

## 开发环境

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

## 发布

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

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

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