README.md
1 <!-- 2 IMPORTANT: This file is generated from the template at 'scripts/templates/README.md'. 3 Please update the template instead of this file. 4 --> 5 6 # aria2p 7 [](https://github.com/pawamoy/aria2p/actions?query=workflow%3Aci) 8 [](https://pawamoy.github.io/aria2p/) 9 [](https://pypi.org/project/aria2p/) 10 [](https://gitter.im/aria2p/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge) 11 [](#support) 12 13 Command-line tool and Python library to interact with an [`aria2c`][1] daemon process through JSON-RPC. 14 15  16 17 To avoid confusion: 18 19 - [*aria2*][1] is a lightweight multi-protocol & multi-source, cross platform download utility operated in command-line. 20 It supports HTTP/HTTPS, FTP, SFTP, BitTorrent and Metalink. 21 - `aria2c` is the name of the command-line executable provided by *aria2*. It can act as a daemon. 22 - `aria2p` (`p` for Python) is a command-line client that can interact with an `aria2c` daemon. 23 It is not an official client. There are other Python packages allowing you to interact with an `aria2c` daemon. 24 These other packages do not offer enough usability (in my opinion), this is why I'm developing `aria2p`. 25 26 **Purpose**: `aria2c` can run in the foreground, for one-time downloads, or in the background, as a daemon. 27 This is where `aria2p` intervenes: when an instance of `aria2c` is running in the background, 28 `aria2p` will be able to communicate with it to add downloads to the queue, remove, pause or resume them, etc. 29 30 In order for `aria2p` to be able to communicate with the `aria2c` process, RPC mode must be enabled 31 with the `--enable-rpc` option of `aria2c`. RPC stands for [Remote Procedure Call][2]. 32 Although `aria2c` supports both JSON-RPC and XML-RPC protocols, `aria2p` **works with JSON only** (not XML). 33 More information about how to configure `aria2c` to run as a daemon with RPC mode enabled 34 can be found in the [Configuration section][conf doc] of the documentation. 35 36 [conf doc]: https://aria2p.readthedocs.io/en/latest/configuration.html 37 38 **Table of contents** 39 40 - [Requirements](#requirements) 41 - [Installation](#installation) 42 - [Usage as a library](#usage-as-a-library) 43 - [Usage on the command line](#usage-command-line) 44 - [Troubleshoot](#troubleshoot) 45 - [Support](#support) 46 47 48 ## Requirements 49 50 `aria2p` requires Python 3.6 or above. 51 52 <details> 53 <summary>To install Python 3.6, I recommend using <a href="https://github.com/pyenv/pyenv"><code>pyenv</code></a>.</summary> 54 55 ```bash 56 # install pyenv 57 git clone https://github.com/pyenv/pyenv ~/.pyenv 58 59 # setup pyenv (you should also put these three lines in .bashrc or similar) 60 export PATH="${HOME}/.pyenv/bin:${PATH}" 61 export PYENV_ROOT="${HOME}/.pyenv" 62 eval "$(pyenv init -)" 63 64 # install Python 3.6 65 pyenv install 3.6.8 66 67 # make it available globally 68 pyenv global system 3.6.8 69 ``` 70 </details> 71 72 You must also install [*aria2*][1]. On systems with `apt-get`: 73 74 ```bash 75 sudo apt-get install aria2 76 ``` 77 78 [1]: https://github.com/aria2/aria2 79 [2]: https://en.wikipedia.org/wiki/Remote_procedure_call 80 81 ## Installation 82 83 With `pip`: 84 85 ```bash 86 python3.6 -m pip install aria2p[tui] 87 ``` 88 89 With [`pipx`](https://github.com/pipxproject/pipx): 90 91 ```bash 92 python3.6 -m pip install --user pipx 93 94 pipx install --python python3.6 aria2p[tui] 95 ``` 96 97 The `tui` extra is needed for the interactive interface. If you don't need the interface (for example when you are 98 writing a Python package with a dependency to aria2p), simply install `aria2p` without any extra. 99 100 ## Usage (as a library) 101 102 **This library is still a work in progress. More examples will be added later. 103 In the meantime, you can read the [Reference section](https://aria2p.readthedocs.io/en/latest/reference.html) on the official documentation.** 104 105 ```python 106 import aria2p 107 108 # initialization, these are the default values 109 aria2 = aria2p.API(aria2p.Client(host="http://localhost", port=6800, secret="")) 110 111 # list downloads 112 downloads = aria2.get_downloads() 113 114 for download in downloads: 115 print(download.name, download.download_speed) 116 117 # add downloads 118 magnet_uri = "magnet:?xt=urn:..." 119 120 download = aria2.add_magnet(magnet_uri) 121 ``` 122 123 ## Usage (command-line) 124 125 ``` 126 {{ main_usage }} 127 ``` 128 129 Calling `aria2p` without any arguments will by default call the `top` command, 130 which is a console interactive interface. 131 132 Commands: 133 134 {% for command in commands %} 135 - [`{{ command.name }}`](#{{ command.name }}){% endfor %} 136 137 {% for command in commands %} 138 --- 139 140 ### `{{ command.name }}` 141 142 ``` 143 {{ command.usage }} 144 ``` 145 146 {% if command.name == "call" -%} 147 As explained in the help text, 148 the `method` can be the exact method name, 149 or just the name without the prefix. 150 It is case-insensitive, and dashes and underscores will be removed. 151 152 The following are all equivalent: 153 - `aria2.addUri` 154 - `aria2.adduri` 155 - `addUri` 156 - `ADDURI` 157 - `aria2.ADD-URI` 158 - `add_uri` 159 - `A-d_D-u_R-i` (yes it's valid) 160 - `A---R---I---A---2.a__d__d__u__r__i` (I think you got it) 161 - and even more ugly forms... 162 163 #### Examples 164 List all available methods. 165 *This example uses [`jq`](https://github.com/stedolan/jq).* 166 ```console 167 $ aria2p call listmethods | jq 168 [ 169 "aria2.addUri", 170 "aria2.addTorrent", 171 "aria2.getPeers", 172 "aria2.addMetalink", 173 "aria2.remove", 174 "aria2.pause", 175 "aria2.forcePause", 176 "aria2.pauseAll", 177 "aria2.forcePauseAll", 178 "aria2.unpause", 179 "aria2.unpauseAll", 180 "aria2.forceRemove", 181 "aria2.changePosition", 182 "aria2.tellStatus", 183 "aria2.getUris", 184 "aria2.getFiles", 185 "aria2.getServers", 186 "aria2.tellActive", 187 "aria2.tellWaiting", 188 "aria2.tellStopped", 189 "aria2.getOption", 190 "aria2.changeUri", 191 "aria2.changeOption", 192 "aria2.getGlobalOption", 193 "aria2.changeGlobalOption", 194 "aria2.purgeDownloadResult", 195 "aria2.removeDownloadResult", 196 "aria2.getVersion", 197 "aria2.getSessionInfo", 198 "aria2.shutdown", 199 "aria2.forceShutdown", 200 "aria2.getGlobalStat", 201 "aria2.saveSession", 202 "system.multicall", 203 "system.listMethods", 204 "system.listNotifications" 205 ] 206 ``` 207 208 List the GIDs (identifiers) of all active downloads. 209 *Note that we must give the parameters as a JSON string.* 210 ```console 211 $ aria2p call tellactive -J '[["gid"]]' 212 [{"gid": "b686cad55029d4df"}, {"gid": "4b39a1ad8fd94e26"}, {"gid": "9d331cc4b287e5df"}, {"gid": "8c9de0df753a5195"}] 213 ``` 214 215 Pause a download using its GID. 216 *Note that when a single string argument is required, it can be passed directly with `-P`.* 217 ```console 218 $ aria2p call pause -P b686cad55029d4df 219 "b686cad55029d4df" 220 ``` 221 222 Add a download using magnet URIs. 223 *This example uses `jq -r` to remove the quotation marks around the result.* 224 ```console 225 $ aria2p call adduri -J '[["magnet:?xt=urn:..."]]' | jq -r 226 4b39a1ad8fd94e26f 227 ``` 228 229 Purge download results (remove completed downloads from the list). 230 ```console 231 $ aria2p call purge_download_result 232 "OK" 233 ``` 234 {%- endif %} 235 {% endfor %} 236 237 ## Troubleshooting 238 239 - Error outputs like below when using `aria2p` as a Python library: 240 241 ``` 242 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',)) 243 ``` 244 245 Solution: `aria2c` needs to be up and running first. 246 247 ## Support 248 249 To support me as an open-source software author, 250 consider donating or be a supporter through one of the following platforms 251 252 - [GitHub](https://github.com/sponsors/pawamoy) 253 - [Ko-fi](https://www.ko-fi.com/pawamoy) 254 - [Liberapay](https://liberapay.com/pawamoy/) 255 - [Patreon](https://www.patreon.com/pawamoy) 256 - [Paypal](https://www.paypal.me/pawamoy) 257 258 Thank you!