v123pan 1.1.0

123Pan Open API SDK - 专业的异步网盘SDK

V123Pan Python SDK

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

特性

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

安装

使用 pip 安装

pip install v123pan

从源码安装

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

快速开始

初始化客户端

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())

文件上传

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()

文件管理

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。

安装开发依赖

pip install -e ".[dev]"

代码格式化

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

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

代码检查

# flake8 检查
flake8 v123pan/ tests/

# mypy 类型检查
mypy v123pan/

运行测试

# 运行所有测试
pytest

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

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

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

模块导出

核心类

from v123pan import V123Pan  # 主客户端

常量

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

异常

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

工具类

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

加密类

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

组合 API

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

配置

环境变量

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

# .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/