# V123Pan Python SDK

专业的 123Pan Open API 异步 Python SDK，提供完整的文件管理、上传、下载功能。

## 特性

- ✨ **纯异步设计** - 基于 `asyncio` 和 `httpx`，高性能并发
- 📦 **完整功能** - 支持文件管理、上传、下载、查询等所有 API
- 🚀 **生产级** - 完善的错误处理、重试机制、类型注解
- 📝 **类型安全** - 完整的类型注解，支持 `mypy` 静态检查
- 🧪 **测试覆盖** - 完善的单元测试和集成测试
- 🔧 **工程化** - 遵循 PEP 8 规范，支持 `black`、`isort`、`flake8`

## 安装

### 使用 pip 安装

```bash
pip install v123pan
```

### 从源码安装

```bash
git clone https://github.com/v123pan/v123pan-python.git
cd v123pan-python
pip install -e .
```

## 快速开始

### 初始化客户端

```python
import asyncio
from v123pan import V123Pan

async def main():
    # 使用 access_token 初始化
    client = V123Pan(access_token="your_access_token")
    
    # 或者使用 client_id 和 client_secret
    client = V123Pan(
        client_id="your_client_id",
        client_secret="your_client_secret"
    )
    
    try:
        # 获取用户信息
        user_info = await client.user_info()
        print(f"用户信息: {user_info}")
    finally:
        await client.close()

if __name__ == "__main__":
    asyncio.run(main())
```

### 文件上传

```python
from v123pan import V123Pan
from v123pan.api.combine import FileUploader

async def upload_file():
    client = V123Pan(client_id="id", client_secret="secret")
    
    async with FileUploader(client) as uploader:
        result = await uploader.upload(
            "/path/to/file.txt",
            parent_id=0,
            progress_callback=lambda p: print(f"进度: {p.percentage:.1f}%")
        )
        
        if result["code"] == 0:
            print(f"上传成功，fileID: {result['data']['fileID']}")
    
    await client.close()
```

### 文件管理

```python
async def file_operations():
    client = V123Pan(access_token="token")
    
    # 创建目录
    dir_result = await client.directory("我的文件夹", parent_id=0)
    dir_id = dir_result["data"]["dirID"]
    
    # 列出文件
    file_list = await client.file_list(parent_file_id=0)
    
    # 获取文件详情
    file_detail = await client.file_detail(file_id=12345)
    
    await client.close()
```

## 项目结构

```
v123pan/
├── v123pan/                     # 主包目录
│   ├── __init__.py              # 包入口，导出公共 API
│   ├── client.py                # 主客户端类
│   ├── const.py                 # 常量配置
│   ├── exceptions.py            # 异常定义
│   ├── api/                     # API 模块
│   │   ├── __init__.py
│   │   ├── base.py              # 基础 Mixin 类
│   │   ├── auth.py              # 认证 API
│   │   ├── user.py              # 用户 API
│   │   ├── upload.py            # 上传 API
│   │   ├── file_management.py   # 文件管理 API
│   │   ├── file_query.py        # 文件查询 API
│   │   ├── download.py          # 下载 API
│   │   └── combine/             # 高级组合 API
│   │       └── uploader.py      # 文件上传器
│   ├── utils/                   # 工具模块
│   │   ├── __init__.py
│   │   ├── log.py               # 日志配置
│   │   └── slice/               # 分片处理
│   └── crypto/                  # 加密模块
│       └── __init__.py
├── tests/                       # 测试目录
├── examples/                    # 示例代码目录
├── doc/                         # API 文档
├── pyproject.toml               # 项目配置
├── requirements.txt             # 依赖列表
└── README.md                    # 主文档
```

## 开发指南

详细开发规范请参考 [DEVELOPMENT.md](DEVELOPMENT.md)。

### 安装开发依赖

```bash
pip install -e ".[dev]"
```

### 代码格式化

```bash
# 使用 black 格式化代码
black v123pan/ tests/

# 使用 isort 整理导入
isort v123pan/ tests/
```

### 代码检查

```bash
# flake8 检查
flake8 v123pan/ tests/

# mypy 类型检查
mypy v123pan/
```

### 运行测试

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

# 运行测试并生成覆盖率报告
pytest --cov=v123pan --cov-report=html

# 只运行单元测试
pytest -m unit

# 只运行集成测试
pytest -m integration
```

## 模块导出

### 核心类

```python
from v123pan import V123Pan  # 主客户端
```

### 常量

```python
from v123pan import API_PATHS, BASE_URL, PLATFORM, FILE_TYPE, FILE_CATEGORY
```

### 异常

```python
from v123pan import (
    V123PanError,
    APIError,
    NetworkError,
    AuthError,
    RateLimitError,
    FileUploadError,
    FileReadError,
    HashComputationError,
    ResourceClosedError,
    TimeoutError,
    ValidationError,
    CryptoError,
)
```

### 工具类

```python
from v123pan import (
    SimpleSlice,
    FileSlice,
    DataSlice,
    MixSlice,
    ChaCha20Poly1305Slice,
    LogConfig,
    get_logger,
)
```

### 加密类

```python
from v123pan import (
    AESEncryptor,
    ChaCha20Encryptor,
    Poly1305Authenticator,
    FilenameEncryptor,
    create_encryptor,
)
```

### 组合 API

```python
from v123pan import (
    FileUploader,
    FileUploadProgress,
    ProgressCallback,
    FileUploadError,
)
```

## 配置

### 环境变量

可以通过环境变量配置 SDK：

```bash
# .env 文件示例
V123PAN_CLIENT_ID=your_client_id
V123PAN_CLIENT_SECRET=your_client_secret
V123PAN_ACCESS_TOKEN=your_access_token
```

## 许可证

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request！

## 联系方式

- GitHub: https://github.com/v123pan/v123pan-python
- 文档: https://v123pan-python.readthedocs.io/
