Skip to content

Latest commit

 

History

History
193 lines (139 loc) · 4.53 KB

README_zh.md

File metadata and controls

193 lines (139 loc) · 4.53 KB

Aria2 XML-RPC Python 3 客户端

一个简洁、类型注解完整的 Aria2 XML-RPC 接口 Python 客户端。

Python License

特性

  • 🚀 现代化 Python 代码，带完整类型注解
  • 📝 完全符合 PEP 8 规范
  • 🛡️ 健壮的错误处理
  • 📖 详尽的文档
  • 🔧 易于使用和扩展

安装

将 aria2_client.py 复制到你的项目目录：

git clone https://github.com/Masterchiefm/python3-aria2-XML-RPC.git
cp python3-aria2-XML-RPC/aria2_client.py /your/project/path/

或作为包安装：

pip install git+https://github.com/Masterchiefm/python3-aria2-XML-RPC.git

快速开始

启动 Aria2 RPC 服务

aria2c --enable-rpc --rpc-listen-all=true --rpc-allow-origin-all

基本用法

from aria2_client import Aria2Client

# 初始化客户端
client = Aria2Client(
    host="http://127.0.0.1",
    port=6800,
    token="your_token_here"
)

# 检查连接
status = client.check_connection()
print(status)  # "Authorized" 或 "Unauthorized"

# 添加下载任务
gid = client.add_uri("https://example.com/file.zip")
print(f"GID: {gid}")

# 批量添加下载
gids = client.add_uri([
    "https://example.com/file1.zip",
    "https://example.com/file2.zip"
], save_dir="/tmp/downloads")

# 获取下载状态
status = client.tell_status(gid, ["gid", "status", "totalLength"])
print(status)

# 暂停/恢复
client.pause(gid)
client.unpause(gid)

# 获取全局统计
stats = client.get_global_status()
print(stats)

API 参考

配置

方法 说明
__init__(host, port, token) 初始化客户端并设置服务器参数
set_server(host, port, token) 更新服务器连接设置
check_connection() 检查连接是否已授权

下载管理

方法 说明
add_uri(uri, save_dir) 添加 HTTP/FTP/SFTP 下载
add_torrent(path, save_dir) 添加种子下载
remove(gid) 删除下载任务
force_remove(gid) 强制删除（不清理）
pause(gid) 暂停下载（空 gid = 全部）
unpause(gid) 恢复下载（空 gid = 全部）

状态查询

方法 说明
get_version() 获取 Aria2 版本
tell_status(gid, keys) 获取下载状态
tell_active(keys) 列出正在下载的任务
tell_waiting(offset, num, keys) 列出等待中的任务
tell_stopped(offset, num, keys) 列出已停止的任务
get_global_status() 获取全局统计信息
get_files(gid) 获取下载文件列表
get_session_info() 获取会话信息

选项设置

方法 说明
get_option(gid) 获取下载选项
change_option(gid, options) 修改下载选项
get_global_option() 获取全局选项
change_global_option(options) 修改全局选项

其他

方法 说明
remove_stopped(gid) 删除已停止的任务记录
save_session() 保存会话到文件
multicall() 创建 MultiCall 对象用于批量操作
list_methods() 列出可用的 RPC 方法
list_notifications() 列出可用的通知

使用示例

指定下载目录

client = Aria2Client()

# 保存到指定目录
gid = client.add_uri(
    "https://example.com/large_file.zip",
    save_dir="/tmp/downloads"
)

监控正在下载的任务

client = Aria2Client()

active = client.tell_active(["gid", "fileName", "totalLength", "downloadSpeed"])
for task in active:
    print(f"{task['fileName']}: {task['downloadSpeed']}/s")

设置速度限制

client = Aria2Client()

# 设置全局下载限制为 1 MB/s
client.change_global_option({"max-download-limit": "1M"})

# 为特定任务设置限制
client.change_option(gid, {"max-download-limit": "500K"})

批量操作

import xmlrpc.client as xmlrpc_client

client = Aria2Client()

mc = client.multicall()
mc.aria2.addUri(["https://example.com/file1"])
mc.aria2.addUri(["https://example.com/file2"])
mc.aria2.addUri(["https://example.com/file3"])

results = tuple(mc())
print(results)  # GID 列表

更多信息

完整 API 详情请参考 Aria2 RPC 官方文档。

许可证

MIT License - 详见 LICENSE 文件。

贡献

欢迎贡献！欢迎提交 Issue 或 Pull Request。