oplist-sdk 0.5.1

A powerful, type-safe Python SDK for OpenList API

OpenList Python SDK

一个功能强大、类型安全、开发者友好的 Python SDK，用于与 OpenList（AList Fork）API 进行交互。

---

📑 目录

• ✨ 核心特性
• 🚀 快速开始
• 📚 完整 API 参考手册
  • 1. 初始化
  • 2. Auth (认证)
  • 3. Public (公共)
  • 4. FS (文件系统)
  • 5. Share (分享)
  • 6. Task (任务管理)
  • 7. Storage (存储管理)
  • 8. Admin (管理员)
• 🔧 数据结构详情
• 🛡️ 响应处理
• 🗓️ 路线图与改进计划

---

✨ 核心特性

特性	描述
🎯 命名空间设计	清晰的 API 组织结构 (client.fs, client.storage, client.auth)
⚡ HTTP/2 支持	使用 httpx 作为底层引擎，支持 HTTP/2 协议
🛡️ 纯粹字典响应	所有 API 返回标准 JSON 字典，无自定义对象，方便直接处理和序列化
🔧 零配置自动登录	支持初始化时自动完成认证
📋 任务监控	内置异步任务管理器 (client.task)，支持进度追踪

---

🚀 快速开始

安装依赖

# 使用 uv (推荐)
uv pip install httpx[http2]

# 或使用 pip
pip install httpx[http2]

基础用法

🎯 极简模式 (推荐用于脚本)

from openlist_sdk import OpenListClient

# 一行代码初始化 + 自动登录
client = OpenListClient("http://nas:5244", username="admin", password="pwd")

# 直接调用 API (返回字典)
resp = client.fs.list("/my_drive")

if resp["code"] == 200:
    # 成功 (data 也是纯字典/列表，直接操作)
    for f in resp["data"]["content"]:
        print(f"{f['name']} ({'📁' if f['is_dir'] else '📄'} {f['size']} bytes)")
else:
    # 失败
    print(f"Error: {resp['message']}")

🔒 严谨模式 (推荐用于 Web 服务)

from openlist_sdk import OpenListClient

with OpenListClient("http://nas:5244") as client:
    # 登录并检查结果
    resp = client.login("admin", "pwd")
    if resp["code"] != 200:
        print("登录失败:", resp["message"])
        exit(1)
    
    # 创建文件夹
    client.fs.mkdir("/local/new_folder")
    
    # 监控任务 (返回任务信息字典)
    task = client.task.copy.wait_for_path(src_path="/src/file.txt")
    if task and task["state"] == 2: # 2 = SUCCEEDED
        print("复制成功")

---

📚 完整 API 参考手册

1. 初始化客户端

使用 OpenListClient 作为 SDK 的主要入口。

client = OpenListClient(
    host="http://alist.example.com:5244",
    username="admin",    # 可选
    password="password", # 可选
    otp_code="123456",   # 可选 (2FA) 
    token="xxx",         # 可选
    timeout=30.0,        # 可选
    verify_token=True    # 可选 (初始化时验证 Token)
)

2. Auth (认证)

命名空间：client.auth

方法	描述	参数
login(...)	用户登录	username, password, otp_code
logout()	用户登出	无
get_me()	获取当前用户信息	无
update_me(...)	更新用户信息	base_path, sso_id
generate_2fa()	生成 2FA	无
verify_2fa(...)	验证 2FA	code
list_ssh_keys()	列出 SSH 密钥	无
add_ssh_key(...)	添加 SSH 密钥	title, content

3. Public (公共)

命名空间：client.public (无需认证)

方法	描述
settings()	获取公共设置
offline_download_tools()	获取离线下载工具列表
archive_extensions()	获取支持的压缩包格式

4. FS (文件系统)

命名空间：client.fs

基础操作

方法	描述	参数
list(...)	列出目录	path, password, page, per_page, refresh
get(...)	获取详情	path, password
mkdir(...)	创建目录	path
rename(...)	重命名	path, name
remove(...)	删除	path
search(...)	搜索	parent, keyword, scope

移动与复制

方法	描述	参数
move(...)	移动	src_dir, dst_dir, names (若空则全移)
copy(...)	复制	src_dir, dst_dir, names (若空则全复制)
recursive_move(...)	递归移动	src_dir, dst_dir

上传与下载

方法	描述	参数
upload(...)	流式上传	local_path, remote_path
upload_form(...)	表单上传	local_path, remote_path
offline_download(...)	离线下载	urls, path, tool

5. Share (分享)

命名空间：client.share

方法	描述	参数
list(...)	列出分享	page, per_page
create(...)	创建分享	path, password, expire_days
delete(...)	删除分享	share_id

6. Task (任务管理)

SDK 提供了统一的任务监控接口，支持 6 种任务类型：copy, move, upload, decompress, decompress_upload, offline_download。

访问方式：client.task.{type}.{method} (例如 client.task.copy.done())

通用管理方法

方法	描述	参数
done() / undone()	获取 已完成/进行中 任务	无
cancel(...)	取消任务	task_id
retry(...)	重试任务	task_id
clear_done()	清除记录	无
wait_all(...)	等待所有完成	timeout, interval

智能查找方法

方法	描述	参数
find_by_path(...)	按 src_path/dst_path 查找任务	src_path, dst_path, include_done
find_exact(...)	按路径精确查获取任务	src_path, dst_path
wait_for_path(...)	等待特定路径的任务完成	src_path, dst_path, timeout
has_pending_for_path(...)	检查是否有进行中的任务	src_path, dst_path

7. Storage (存储管理)

命名空间：client.storage (原 client.admin.storage)

方法	描述	参数
list(...)	列出所有挂载的存储	page, per_page
get(...)	获取指定存储详情	storage_id
create(...)	挂载新存储 (支持详细驱动配置)	mount_path, driver, cache, remark, **config
update(...)	更新存储配置	storage_id, **kwargs
delete(...)	删除/卸载存储	storage_id
enable(...)	启用存储	storage_id
disable(...)	禁用存储	storage_id
reload()	重新加载所有存储	无

8. Admin (管理员)

命名空间：client.admin

用户管理 (.user)

方法	描述	参数
list(...)	列出用户	page, per_page
create(...)	创建用户	username, password, role, base_path
update(...)	更新用户	user_id, **kwargs
delete(...)	删除用户	user_id

设置与元数据 (.setting / .meta)

命名空间	方法	描述	参数
setting	list(...)	列出设置	page, per_page
setting	get(...)	获取设置	key
setting	save(...)	保存设置	items (List)
meta	list(...)	列出元数据	page, per_page
meta	create(...)	创建元数据	path, password, hide, readme
meta	delete(...)	删除元数据	meta_id

其他管理 (.index / .driver)

命名空间	方法	描述	参数
index	build(...)	重建搜索索引	path
index	stop()	停止构建	无
index	progress()	获取构建进度	无
driver	list()	列出可用驱动	无
driver	info(...)	获取驱动参数	driver_name

---

🔧 数据结构详情

SDK 完全返回 Python 原生字典类型，data 字段的结构完全对应 API JSON 响应。

• fs.list / fs.get: {"name": "foo", "is_dir": true, "size": 1024, ...}
• task.*: {"id": "...", "state": 2, "name": "...", ...}

---

🛡️ 响应处理

所有 API 方法都返回一个标准的 Python 字典（dict）。

统一响应结构：

{
    "code": 200,      # HTTP 状态码或业务状态码 (200=成功)
    "message": "success", # 状态描述或错误信息
    "data": ...       # 业务数据 (可能是对象、列表或 None)
}

示例：

resp = client.fs.list("/")

if resp["code"] == 200:
    files = resp["data"]["content"] # 直接像操作 JSON 一样操作
    print(files[0]["name"])
else:
    # 失败
    print(f"Error: {resp.get('message')}")

---

🗓️ 路线图与改进计划

🛠️ 近期计划 (Coming Soon)

• 完善测试套件: 增加单元测试，移除测试代码中的硬编码凭据，改用 .env 配置。
• 日志系统: 添加基于 logging 模块的日志记录，方便调试。
• CLI 工具: 开发基于 Typer 的命令行工具，支持 oplist ls, oplist cp 等命令。

🔮 远期规划

• 异步支持: 提供 AsyncOpenListClient，基于 httpx 的异步能力支持高并发操作。
• 重试机制: 对网络请求添加自动重试策略。

---

Made with ❤️ for OpenList Community