Command-line tool and library to interact with an aria2c daemon process with JSON-RPC.

These details have not been verified by PyPI

Project links

Project description

aria2p

Command-line tool and Python library to interact with an aria2c daemon process through JSON-RPC.

demo

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 an aria2c daemon. It is not an official client. There are other Python packages allowing you to interact with an aria2c daemon. These other packages do not offer enough usability (in my opinion), this is why I'm developing aria2p.

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.
    top                 Launch the top-like interactive interface.
    listen              Listen to notifications.

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
top
listen

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.

`top`

usage: aria2p top [-h]

Launch the top-like interactive interface.

optional arguments:
  -h, --help  Show this help message and exit.

`listen`

usage: aria2p listen [-h] [-c CALLBACKS_MODULE] [-t TIMEOUT]
                     [event_types [event_types ...]]

Listen to notifications.

positional arguments:
  event_types           The types of notifications to process: start, pause,
                        stop, error, complete or btcomplete. Example: aria2p
                        listen error btcomplete. Useful if you want to spawn
                        multiple specialized aria2p listener, for example one
                        for each type of notification, but still want to use
                        only one callback file.

optional arguments:
  -h, --help            Show this help message and exit.
  -c CALLBACKS_MODULE, --callbacks-module CALLBACKS_MODULE
                        Path to the Python module defining your notifications
                        callbacks.
  -t TIMEOUT, --timeout TIMEOUT
                        Timeout in seconds to use when waiting for data over
                        the WebSocket at each iteration. Use small values for
                        faster reactivity when stopping to listen.

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

These details have not been verified by PyPI

Project links

Release history Release notifications | RSS feed

0.12.0

Jan 11, 2024

0.11.3

Dec 15, 2022

0.11.2

Apr 17, 2022

0.11.1

Dec 17, 2021

0.11.0

Dec 16, 2021

0.10.4

Jan 6, 2021

0.10.3

Dec 30, 2020

0.10.2

Dec 30, 2020

0.10.1

Nov 28, 2020

0.10.0

Nov 28, 2020

0.9.1

May 14, 2020

0.9.0

Apr 8, 2020

0.8.1

Mar 29, 2020

0.8.0

Mar 27, 2020

0.7.1

Jan 18, 2020

0.7.0

Dec 14, 2019

0.6.0

Oct 20, 2019

0.5.2

Oct 15, 2019

This version

0.5.1

Oct 15, 2019

0.5.0

Oct 15, 2019

0.4.0

Oct 13, 2019

0.3.0

Oct 10, 2019

0.2.5

Aug 9, 2019

0.2.4

Aug 9, 2019

0.2.3

Aug 8, 2019

0.2.2

Feb 21, 2019

0.2.1

Jan 23, 2019

0.2.0

Jan 23, 2019

0.1.7

Dec 28, 2018

0.1.6

Dec 26, 2018

0.1.5

Dec 20, 2018

0.1.4

Dec 20, 2018

0.1.3

Dec 17, 2018

0.1.2

Dec 17, 2018

0.1.1

Dec 16, 2018

0.1.0

Dec 16, 2018

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

aria2p-0.5.1.tar.gz (72.6 kB view hashes)

Uploaded Oct 15, 2019 Source

Built Distribution

aria2p-0.5.1-py3-none-any.whl (75.8 kB view hashes)

Uploaded Oct 15, 2019 Python 3

Hashes for aria2p-0.5.1.tar.gz

Hashes for aria2p-0.5.1.tar.gz
Algorithm	Hash digest
SHA256	`263a1ed3a68fe3648d8d0f7d678df71de430b0b0ce4306c97c3f409649df2bb8`
MD5	`97fafe5d3fc37470373c2e9151de1d38`
BLAKE2b-256	`71ee9846e57f91286f7bdccbcf9abd18cb37e5fc69a0d7ba3b57bee926933841`

Hashes for aria2p-0.5.1-py3-none-any.whl

Hashes for aria2p-0.5.1-py3-none-any.whl
Algorithm	Hash digest
SHA256	`56edc802c42cc71370d3a5bbe6711ad60efc2230fbf4abe50e74aa580e1e5622`
MD5	`a284961b5357448741f626d4a23b4221`
BLAKE2b-256	`1927157fbb8fa8336d25eddeb8f2929390914e7087c19f7e4f1983f7e6c0ca6e`

aria2p 0.5.1

Navigation

Verified details

Maintainers

Unverified details

Project links

Meta

Classifiers

Project description

aria2p

Requirements

Installation

Usage (as a library)

Usage (command-line)

add-magnet

add-metalink

add-torrent

autopurge

call

Examples

pause

pause-all

purge

remove

remove-all

resume

resume-all

show

top

listen

Troubleshoot

Project details

Verified details

Maintainers

Unverified details

Project links

Meta

Classifiers

Release history Release notifications | RSS feed

Download files

Source Distribution

Built Distribution

`add-magnet`

`add-metalink`

`add-torrent`

`autopurge`

`call`

`pause`

`pause-all`

`purge`

`remove`

`remove-all`

`resume`

`resume-all`

`show`

`top`

`listen`