Aria2 XML-RPC Client for Python 3

A clean, type-annotated Python client for Aria2 XML-RPC interface.

Features

• 🚀 Clean, modern Python code with type hints
• 📝 Full PEP 8 compliance
• 🛡️ Robust error handling
• 📖 Comprehensive documentation
• 🔧 Easy to use and extend

Installation

Copy aria2_client.py to your project directory:

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

Or use as a package:

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

Quick Start

Start Aria2 RPC Server

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

Basic Usage

from aria2_client import Aria2Client

# Initialize client
client = Aria2Client(
    host="http://127.0.0.1",
    port=6800,
    token="your_token_here"
)

# Check connection
status = client.check_connection()
print(status)  # "Authorized" or "Unauthorized"

# Add a download
gid = client.add_uri("https://example.com/file.zip")
print(f"GID: {gid}")

# Add multiple downloads
gids = client.add_uri([
    "https://example.com/file1.zip",
    "https://example.com/file2.zip"
], save_dir="/tmp/downloads")

# Get download status
status = client.tell_status(gid, ["gid", "status", "totalLength"])
print(status)

# Pause/Resume
client.pause(gid)
client.unpause(gid)

# Get global statistics
stats = client.get_global_status()
print(stats)

API Reference

Configuration

Method	Description
__init__(host, port, token)	Initialize client with server settings
set_server(host, port, token)	Update server connection settings
check_connection()	Check if connection is authorized

Downloads

Method	Description
add_uri(uri, save_dir)	Add HTTP/FTP/SFTP download
add_torrent(path, save_dir)	Add torrent download
remove(gid)	Remove a download
force_remove(gid)	Force remove without cleanup
pause(gid)	Pause download (empty gid = all)
unpause(gid)	Resume download (empty gid = all)

Status & Information

Method	Description
get_version()	Get Aria2 version
tell_status(gid, keys)	Get download status
tell_active(keys)	List active downloads
tell_waiting(offset, num, keys)	List waiting downloads
tell_stopped(offset, num, keys)	List stopped downloads
get_global_status()	Get global statistics
get_files(gid)	Get file list of download
get_session_info()	Get session information

Options

Method	Description
get_option(gid)	Get download options
change_option(gid, options)	Change download options
get_global_option()	Get global options
change_global_option(options)	Change global options

Other

Method	Description
remove_stopped(gid)	Remove stopped downloads
save_session()	Save session to file
multicall()	Create MultiCall object for batching
list_methods()	List available RPC methods
list_notifications()	List available notifications

Examples

Download with Custom Directory

client = Aria2Client()

# Save to specific directory
gid = client.add_uri(
    "https://example.com/large_file.zip",
    save_dir="/tmp/downloads"
)

Monitor Active Downloads

client = Aria2Client()

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

Set Speed Limits

client = Aria2Client()

# Set global download limit to 1 MB/s
client.change_global_option({"max-download-limit": "1M"})

# Set limit for specific download
client.change_option(gid, {"max-download-limit": "500K"})

Batch Operations with MultiCall

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)  # List of GIDs

For More Information

See Aria2 RPC Documentation for complete API details.

License

MIT License - See LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.