Command-line tool and library to interact with an aria2c daemon process with JSON-RPC.
Project description
aria2p
Command-line tool and Python library to interact with an aria2c
daemon process through JSON-RPC.
To avoid confusion:
- aria2 is a lightweight multi-protocol & multi-source, cross platform download utility operated in command-line. It supports HTTP/HTTPS, FTP, SFTP, BitTorrent and Metalink.
aria2c
is the name of the command-line executable provided by aria2. It can act as a daemon.aria2p
(p
for Python) is a command-line client that can interact with anaria2c
daemon. It is not an official client. There are other Python packages allowing you to interact with anaria2c
daemon. These other packages do not offer enough usability (in my opinion), this is why I'm developingaria2p
.
Purpose: aria2c
can run in the foreground, for one-time downloads, or in the background, as a daemon.
This is where aria2p
intervenes: when an instance of aria2c
is running in the background,
aria2p
will be able to communicate with it to add downloads to the queue, remove, pause or resume them, etc.
In order for aria2p
to be able to communicate with the aria2c
process, RPC mode must be enabled
with the --enable-rpc
option of aria2c
. RPC stands for Remote Procedure Call.
Although aria2c
supports both JSON-RPC and XML-RPC protocols, aria2p
works with JSON only (not XML).
More information about how to configure aria2c
to run as a daemon with RPC mode enabled
can be found in the Configuration section of the documentation.
Requirements
aria2p
requires Python 3.6 or above.
To install Python 3.6, I recommend using pyenv
.
# install pyenv
git clone https://github.com/pyenv/pyenv ~/.pyenv
# setup pyenv (you should also put these three lines in .bashrc or similar)
export PATH="${HOME}/.pyenv/bin:${PATH}"
export PYENV_ROOT="${HOME}/.pyenv"
eval "$(pyenv init -)"
# install Python 3.6
pyenv install 3.6.8
# make it available globally
pyenv global system 3.6.8
You must also install aria2. On systems with apt-get
:
sudo apt-get install aria2
Installation
With pip
:
python3.6 -m pip install aria2p
With pipx
:
python3.6 -m pip install --user pipx
pipx install --python python3.6 aria2p
Usage (as a library)
This library is still a work in progress. More examples will be added later. In the meantime, you can read the Reference section on the official documentation.
import aria2p
# initialization, these are the default values
aria2 = aria2p.API(
aria2p.Client(
host="http://localhost",
port=6800,
secret=""
)
)
# list downloads
downloads = aria2.get_downloads()
for download in downloads:
print(download.name, download.download_speed)
# add downloads
magnet_uri = "magnet:?xt=urn:..."
download = aria2.add_magnet(magnet_uri)
Usage (command-line)
usage: aria2p [GLOBAL_OPTS...] COMMAND [COMMAND_OPTS...]
Command-line tool and Python library to interact with an `aria2c` daemon
process through JSON-RPC.
Global options:
-h, --help Show this help message and exit. Commands also accept
the -h/--help option.
-p PORT, --port PORT Port to use to connect to the remote server.
-H HOST, --host HOST Host address for the remote server.
-s SECRET, --secret SECRET
Secret token to use to connect to the remote server.
-L {TRACE,DEBUG,INFO,SUCCESS,WARNING,ERROR,CRITICAL}, --log-level {TRACE,DEBUG,INFO,SUCCESS,WARNING,ERROR,CRITICAL}
Log level to use
Commands:
add-magnet Add a download with a Magnet URI.
add-metalink Add a download with a Metalink file.
add-torrent Add a download with a torrent file.
autopurge (autoclear)
Automatically purge completed/removed/failed
downloads.
call Call a remote method through the JSON-RPC client.
pause (stop) Pause downloads.
pause-all Pause all downloads.
purge (clear) Purge downloads.
remove (rm, del, delete)
Remove downloads.
remove-all Remove all downloads.
resume (start) Resume downloads.
resume-all Resume all downloads.
show Show the download progression.
Calling aria2p
without any arguments will by default call the show
command,
which displays the list of current downloads:
GID STATUS PROGRESS DOWN_SPEED UP_SPEED ETA NAME
There is no interactive mode yet,
but you can use watch
combined with the show
subcommand
to see how the downloads progress:
watch -t -n1 aria2p show
Commands:
add-magnet
add-metalink
add-torrent
autopurge
call
pause
pause-all
purge
remove
remove-all
resume
resume-all
show
Warning: commands ending with -all
are deprecated. Please use their equivalent with the -a
or --all
option
(e.g. instead of pause-all
, use pause -a
). These commands will be removed in version 0.5.0.
add-magnet
usage: aria2p add-magnet [-h] uri
Add a download with a Magnet URI.
positional arguments:
uri The magnet URI to use.
optional arguments:
-h, --help Show this help message and exit.
add-metalink
usage: aria2p add-metalink [-h] metalink_file
Add a download with a Metalink file.
positional arguments:
metalink_file The path to the metalink file.
optional arguments:
-h, --help Show this help message and exit.
add-torrent
usage: aria2p add-torrent [-h] torrent_file
Add a download with a torrent file.
positional arguments:
torrent_file The path to the torrent file.
optional arguments:
-h, --help Show this help message and exit.
autopurge
usage: aria2p autopurge [-h]
Automatically purge completed/removed/failed downloads.
optional arguments:
-h, --help Show this help message and exit.
call
usage: aria2p call [-h] [-P PARAMS [PARAMS ...] | -J PARAMS] method
Call a remote method through the JSON-RPC client.
positional arguments:
method The method to call (case insensitive). Dashes and
underscores will be removed so you can use as many as
you want, or none. Prefixes like 'aria2.' or 'system.'
are also optional.
optional arguments:
-h, --help Show this help message and exit.
-P PARAMS [PARAMS ...], --params-list PARAMS [PARAMS ...]
Parameters as a list of strings.
-J PARAMS, --json-params PARAMS
Parameters as a JSON string. You should always wrap it
at least once in an array '[]'.
As explained in the help text,
the method
can be the exact method name,
or just the name without the prefix.
It is case-insensitive, and dashes and underscores will be removed.
The following are all equivalent:
aria2.addUri
aria2.adduri
addUri
ADDURI
aria2.ADD-URI
add_uri
A-d_D-u_R-i
(yes it's valid)A---R---I---A---2.a__d__d__u__r__i
(I think you got it)- and even more ugly forms...
Examples
List all available methods.
This example uses jq
.
$ aria2p call listmethods | jq
[
"aria2.addUri",
"aria2.addTorrent",
"aria2.getPeers",
"aria2.addMetalink",
"aria2.remove",
"aria2.pause",
"aria2.forcePause",
"aria2.pauseAll",
"aria2.forcePauseAll",
"aria2.unpause",
"aria2.unpauseAll",
"aria2.forceRemove",
"aria2.changePosition",
"aria2.tellStatus",
"aria2.getUris",
"aria2.getFiles",
"aria2.getServers",
"aria2.tellActive",
"aria2.tellWaiting",
"aria2.tellStopped",
"aria2.getOption",
"aria2.changeUri",
"aria2.changeOption",
"aria2.getGlobalOption",
"aria2.changeGlobalOption",
"aria2.purgeDownloadResult",
"aria2.removeDownloadResult",
"aria2.getVersion",
"aria2.getSessionInfo",
"aria2.shutdown",
"aria2.forceShutdown",
"aria2.getGlobalStat",
"aria2.saveSession",
"system.multicall",
"system.listMethods",
"system.listNotifications"
]
List the GIDs (identifiers) of all active downloads. Note that we must give the parameters as a JSON string.
$ aria2p call tellactive -J '[["gid"]]'
[{"gid": "b686cad55029d4df"}, {"gid": "4b39a1ad8fd94e26"}, {"gid": "9d331cc4b287e5df"}, {"gid": "8c9de0df753a5195"}]
Pause a download using its GID.
Note that when a single string argument is required, it can be passed directly with -P
.
$ aria2p call pause -P b686cad55029d4df
"b686cad55029d4df"
Add a download using magnet URIs.
This example uses jq -r
to remove the quotation marks around the result.
$ aria2p call adduri -J '[["magnet:?xt=urn:..."]]' | jq -r
4b39a1ad8fd94e26f
Purge download results (remove completed downloads from the list).
$ aria2p call purge_download_result
"OK"
pause
usage: aria2p pause [-h] [-a] [-f] [gids [gids ...]]
Pause downloads.
positional arguments:
gids The GIDs of the downloads to pause.
optional arguments:
-h, --help Show this help message and exit.
-a, --all Pause all the downloads.
-f, --force Pause without contacting servers first.
pause-all
usage: aria2p pause-all [-h] [-f]
Pause all downloads.
optional arguments:
-h, --help Show this help message and exit.
-f, --force Pause without contacting servers first.
purge
usage: aria2p purge [-h] [-a] [gids [gids ...]]
Purge downloads.
positional arguments:
gids The GIDs of the downloads to purge.
optional arguments:
-h, --help Show this help message and exit.
-a, --all Purge all the downloads.
remove
usage: aria2p remove [-h] [-a] [-f] [gids [gids ...]]
Remove downloads.
positional arguments:
gids The GIDs of the downloads to remove.
optional arguments:
-h, --help Show this help message and exit.
-a, --all Remove all the downloads.
-f, --force Remove without contacting servers first.
remove-all
usage: aria2p remove-all [-h] [-f]
Remove all downloads.
optional arguments:
-h, --help Show this help message and exit.
-f, --force Remove without contacting servers first.
resume
usage: aria2p resume [-h] [-a] [gids [gids ...]]
Resume downloads.
positional arguments:
gids The GIDs of the downloads to resume.
optional arguments:
-h, --help Show this help message and exit.
-a, --all Resume all the downloads.
resume-all
usage: aria2p resume-all [-h]
Resume all downloads.
optional arguments:
-h, --help Show this help message and exit.
show
usage: aria2p show [-h]
Show the download progression.
optional arguments:
-h, --help Show this help message and exit.
Troubleshoot
-
Error outputs like below when using
aria2p
as a Python library:requests.exceptions.ConnectionError: HTTPConnectionPool(host='localhost', port=6800): Max retries exceeded with url: /jsonrpc (Caused by NewConnectionError('<urllib3.connection.HTTPConnection object at 0x1115b1908>: Failed to establish a new connection: [Errno 61] Connection refused',))
Solution:
aria2c
needs to be up and running first.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.