aio123pan 0.1.1

123Pan async API client

aio123pan

123云盘异步API客户端，支持文件管理、上传下载等完整功能。

系统要求

• Python 3.10+

安装

pip install aio123pan

快速开始

基本用法

import asyncio
from aio123pan import Pan123Client

async def main():
    async with Pan123Client(
        client_id="your_client_id",
        client_secret="your_client_secret"
    ) as client:
        # 获取用户信息
        user_info = await client.user.get_user_info()
        print(f"用户: {user_info.nickname}")
        print(f"空间使用: {user_info.space_used / (1024**3):.2f}GB / {user_info.space_permanent / (1024**3):.2f}GB")

        # 列出根目录文件
        file_list = await client.file.list_files(parent_file_id=0)
        for file in file_list.file_list:
            print(f"{'[文件夹]' if file.is_folder else '[文件]'} {file.filename}")

asyncio.run(main())

配置方式

支持三种配置方式，优先级：显式参数 > 环境变量 > .env文件

# 方式1: 显式传参
client = Pan123Client(client_id="xxx", client_secret="xxx")

# 方式2: 环境变量
# export PAN123_CLIENT_ID=xxx
# export PAN123_CLIENT_SECRET=xxx
client = Pan123Client()

# 方式3: .env文件
# PAN123_CLIENT_ID=xxx
# PAN123_CLIENT_SECRET=xxx
client = Pan123Client()

文件操作

# 上传文件
file_id = await client.upload.upload_file(
    file_path="local_file.txt",
    parent_file_id=0,
    progress_callback=lambda current, total: print(f"上传进度: {current}/{total}")
)

# 创建文件夹
folder_id = await client.folder.create_folder(name="新文件夹", parent_id=0)

# 移动文件
await client.file.move_file(file_id, target_parent_id=folder_id)

# 重命名文件
await client.file.rename_file(file_id, "新文件名.txt")

# 删除文件
await client.file.delete_file(file_id)

# 批量操作（最多100个）
await client.file.delete_file([file_id1, file_id2, file_id3])

Token自动管理

Token会自动缓存到.env文件，无需手动管理：

# 首次使用会获取token并缓存到.env
async with Pan123Client(client_id="xxx", client_secret="xxx") as client:
    # Token自动存储到.env
    # 如果.env文件不存在，会自动创建
    await client.user.get_info()

# 后续使用自动读取缓存的token
async with Pan123Client(client_id="xxx", client_secret="xxx") as client:
    # 自动从.env读取token，过期时自动刷新
    await client.user.get_info()

重要提示：

• Token会保存到 .env 文件中的 AIO123PAN_CACHED_ACCESS_TOKEN 和 AIO123PAN_CACHED_TOKEN_EXPIRY 字段
• 这些字段由 aio123pan 自动管理，请勿手动编辑
• 请勿将这两个键名用于其他用途，以避免冲突
• 如果不存在 .env 文件，首次认证成功后会自动创建

禁用Token持久化：

# 方式1: 通过参数
client = Pan123Client(enable_token_storage=False)

# 方式2: 通过环境变量
# PAN123_ENABLE_TOKEN_STORAGE=false
client = Pan123Client()

参数说明

客户端初始化

• client_id: 123云盘应用ID
• client_secret: 123云盘应用密钥
• access_token: 访问令牌（可选，自动管理）
• expired_at: Token过期时间（可选，自动管理）
• timeout: 请求超时时间（秒）
• base_url: API基础URL（默认：https://open-api.123pan.com）
• enable_token_storage: 是否启用token持久化（默认：True）
• env_file: .env文件路径（默认：当前目录）

环境变量

所有配置项都支持通过环境变量设置，优先级：显式参数 > 环境变量 > .env文件

• PAN123_CLIENT_ID: 应用ID
• PAN123_CLIENT_SECRET: 应用密钥
• PAN123_TIMEOUT: 请求超时时间（默认：30.0）
• PAN123_BASE_URL: API基础URL
• PAN123_ENABLE_TOKEN_STORAGE: 是否启用token持久化（默认：true）

自动生成字段（请勿手动设置）：

• AIO123PAN_CACHED_ACCESS_TOKEN: 缓存的访问令牌
• AIO123PAN_CACHED_TOKEN_EXPIRY: Token过期时间

文件限制

• 文件名最大长度：255字符
• 禁止字符："\/:*?|><
• 单文件最大：10GB
• 批量操作最大：100个项目

API功能

认证模块

• 获取访问令牌
• 自动刷新过期token

用户模块

• 获取用户信息
• 查看空间使用情况

文件模块

• 列出文件/文件夹
• 移动文件
• 重命名文件
• 删除文件（支持批量）
• 复制文件
• 搜索文件

文件夹模块

• 创建文件夹

上传模块

• 小文件直接上传
• 大文件分片上传
• 上传进度回调
• 秒传支持

回收站模块

• 查看回收站文件
• 恢复文件
• 彻底删除

示例代码

项目提供了两种类型的示例代码：

只读示例（安全运行）

examples/read_only_examples.py - 只读取数据，不会修改你的123云盘内容

• 获取用户信息
• 列出文件
• 搜索文件
• 查看回收站
• 查看存储空间使用情况

python examples/read_only_examples.py

写操作示例（需要谨慎）

examples/write_examples.py - 会创建、修改或删除数据

⚠️ 警告：这些示例默认全部注释，需要手动取消注释才能运行

• 创建文件夹
• 上传文件
• 重命名/移动/复制文件
• 删除文件
• 批量操作

打开文件，取消注释你想运行的示例：

# 取消注释你想运行的示例
# asyncio.run(example_create_folder())
# asyncio.run(example_upload_file())

开发环境

环境准备

# 安装uv包管理器
curl -LsSf https://astral.sh/uv/install.sh | sh

# 克隆项目
git clone https://github.com/Cloxl/aio123pan
cd aio123pan

# 安装依赖
uv sync --dev

开发流程

# 运行测试
uv run pytest tests/ -v

# 代码检查
uv run ruff check src/ tests/

# 代码格式化
uv run ruff format src/ tests/

# 查看测试覆盖率
uv run pytest tests/ --cov=aio123pan --cov-report=html

# 构建包
uv build

Git工作流

# 创建功能分支
git checkout -b feat/your-feature

# 提交代码（遵循conventional commits规范）
git commit -m "feat(client): 添加新功能描述"

# 推送到远程
git push origin feat/your-feature

相关链接

• 123云盘开放平台
• 官方API文档

License

MIT