rtorrent#

class platypush.plugins.rtorrent.RtorrentPlugin(url: str, poll_seconds: float = 5.0, download_dir: str = '~/.rtorrent/watch', **kwargs)[source]#

Bases: TorrentPlugin

Plugin to interact search, download and manage torrents through RTorrent. The usage of this plugin is advised over platypush.plugins.torrent.TorrentPlugin, as RTorrent is a more flexible and optimized solution for downloading and managing torrents compared to the Platypush native plugin.

Configuration:

  • Install rtorrent on your system - on Debian/Ubuntu/Raspbian:

    apt-get install rtorrent

  • Configure the rtorrent XML/RPC interface, usually by adding the following lines to your ~/.rtorrent.rc:

    # Enable XML/RPC
scgi_local = /home/user/.rpc.socket

  • Use a web server to bridge the RPC interface exposed by RTorrent over HTTP. Some configuration examples are available here. I usually use lighttpd because it’s easy to configure and it comes with a built-in SCGI module. Install the server e.g. using apt:

    apt-get install lighttpd

  • Create a base configuration file like this under e.g. ~/.config/rtorrent/lighttpd.conf:

    ### Base configuration
server.modules = (
    "mod_indexfile",
    "mod_access",
    "mod_alias",
    "mod_redirect",
)

# Make sure that all the directories exist.

# server.document-root isn't really needed, but lighttpd
# won't start if it doesn't find a document root.
server.document-root        = "/home/user/.local/share/rtorrent/html"
server.upload-dirs          = ( "/home/user/.cache/uploads" )
server.errorlog             = "/home/user/.local/log/rtorrent/error.log"
server.pid-file             = "/home/user/.local/run/lighttpd.pid"
server.username             = "your-user"
server.groupname            = "your-group"
server.port                 = 5000

index-file.names            = ( "index.html" )

### Configure the RTorrent XML/RPC endpoint
server.modules += ( "mod_scgi" )
scgi.server = (
    # Bind an endpoint called /RPC2 to your local interface
    "/RPC2" =>
      ( "127.0.0.1" =>
        (
          # Read from the RTorrent XML/RPC socket
          "socket" => "/home/user/.rpc.socket",
          "check-local" => "disable",
          "disable-time" => 0,  # don't disable scgi if connection fails
        )
      )
  )

  • Start the HTTP service, and optionally enable it as a system/user service:

    lighttpd -f ~/.config/rtorrent/lighttpd.conf

  • Start RTorrent and check that the XML/RPC interface works:

    $ xmlrpc localhost:8000 system.listMethods
# Should return a list with all the methods exposed by RTorrent.
$ xmlrpc localhost:5000 download_list
Result:
Array of 0 items:

  • It is advised to let the RTorrent instance run in e.g. screen or tmux on the server machine - it is more reliable than letting the plugin start/stop the instance, and you have an easy CLI interface to attach to manage/monitor your torrents.

  • In this example, the URL to configure in the plugin would be http://localhost:5000/RPC2.

Triggers:

__init__(url: str, poll_seconds: float = 5.0, download_dir: str = '~/.rtorrent/watch', **kwargs)[source]#
Parameters:

  • url – HTTP URL that exposes the XML/RPC interface of RTorrent (e.g. http://localhost:5000/RPC2).

  • poll_seconds – How often the plugin will monitor for changes in the torrent state (default: 5 seconds).

  • download_dir – Directory where torrents and metadata files will be downloaded (default: ~/.rtorrent/watch).

download(torrent: str, is_media: bool = False, *_, **__)[source]#

Download a torrent.

Parameters:

  • torrent –

    Torrent to download. Supported formats:

    • Magnet URLs

    • Torrent URLs

    • Local torrent files

  • is_media – Set it to true if you’re downloading a media file that you’d like to stream as soon as the first chunks are available. If so, then the events and the status method will only include media files

Returns:

The status of the torrent.

download_torrent_file(torrent: str) → str[source]#

Download a torrent link to torrent_files_dir.

Parameters:

torrent – Torrent URL, magnet link or local file.

Returns:

Path to the locally downloaded .torrent file.

execute(method: str, *args, **kwargs)[source]#

Execute a raw command over the RTorrent RPC interface.

Parameters:

  • method – Method name.

  • args – Method arguments.

  • kwargs – Method keyword-arguments.

Returns:

Anything returned by the RPC method.

list_methods() → List[str][source]#
Returns:

The list of methods exposed by the RTorrent instance

open(torrent: str) → dict[source]#

Open a loaded torrent transfer.

Parameters:

torrent – Torrent hash.

Returns:

The status of the torrent.

pause(torrent: str) → dict[source]#

Pause a torrent transfer.

Parameters:

torrent – Torrent hash.

Returns:

The status of the torrent.

quit()[source]#

Terminate all the active transfers and quit the monitor.

remove(torrent)[source]#

Stop and remove a torrent transfer (without removing the downloaded files).

Parameters:

torrent – Torrent hash.

resume(torrent) → dict[source]#

Resume a torrent transfer.

Parameters:

torrent – Torrent hash.

Returns:

The status of the torrent.

start_monitor()[source]#

Start monitoring the status of the RTorrent instance.

status(torrent: str = None) → dict[source]#

Get the status of the current transfers.

Parameters:

torrent – Torrent hash.

Returns:

A dictionary:

{
  "HASH1234567890": {
    "hash": "HASH1234567890",
    "name": "Your torrent name",
    "save_path": "/home/user/Downloads/Your torrent name",
    "is_active": true,
    "is_open": true,
    "completed_bytes": 666894336,
    "download_rate": 451345,
    "is_multi_file": true,
    "remaining_bytes": 1482827011,
    "size_bytes": 2149721347,
    "load_date": "2020-09-02T18:42:19",
    "peers": 0,
    "state": "paused",
    "start_date": "2020-09-02T18:42:19",
    "finish_date": null,
    "upload_rate": 143967,
    "progress": 31.0,
    "files": ["list", "of", "downloaded", "files"]
  }
}

stop(torrent) → dict[source]#

Stop a torrent transfer.

Parameters:

torrent – Torrent hash.

Returns:

The status of the torrent.

stop_monitor()[source]#

Stop monitoring the status of the RTorrent instance.