Skip to content

Latest commit

 

History

History
193 lines (139 loc) · 4.69 KB

README.md

File metadata and controls

193 lines (139 loc) · 4.69 KB

Aria2 XML-RPC Client for Python 3

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

Python License

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.