torrent

torrent#

Description#

Plugin to search and download torrents.

Configuration#

torrent:
  # [Optional]
  # Directory where the videos/torrents will be
  # downloaded (default: ``~/Downloads``).
  # download_dir:   # type=Optional[str]

  # [Optional]
  # Torrent ports to listen on (default: 6881 and 6891)
  # torrent_ports: (6881, 6891)  # type=Iterable[int]

  # [Optional]
  # List of search providers to use.
  # search_providers:   # type=Union[Dict[str, dict], Iterable[platypush.plugins.torrent._search._base.TorrentSearchProvider], NoneType]

Dependencies#

pip

pip install libtorrent

Alpine

apk add py3-libtorrent-rasterbar sqlite3

Debian

apt install sqlite3 python3-libtorrent

Fedora

yum install sqlite3 rb_libtorrent-python3

Arch Linux

pacman -S libtorrent-rasterbar sqlite3

Actions#

Module reference#

class platypush.plugins.torrent.TorrentPlugin(download_dir: str | None = None, torrent_ports: Iterable[int] = (6881, 6891), search_providers: Dict[str, dict] | Iterable[TorrentSearchProvider] | None = None, **kwargs)[source]#

Bases: Plugin

Plugin to search and download torrents.

Search#

You can search for torrents using the search() method. The method will use the search providers configured in the search_providers attribute of the plugin configuration. Currently supported search providers:

  • popcorntime:

    platypush.plugins.torrent._search.PopcornTimeSearchProvider

  • torrents.csv:

    platypush.plugins.torrent._search.TorrentsCsvSearchProvider

torrents.csv will be enabled by default unless you explicitly disable it. torrents.csv also supports both:

  • A remote API via the api_url attribute (default:

    https://torrents-csv.com/service`). You can also run your own API server by following the instructions at heretic/torrents-csv-server.

  • A local checkout of the torrents.csv file. Clone the heretic/torrents-csv-data and provide the path to the torrents.csv file in the csv_file attribute.

  • A local checkout of the torrents.db file built from the torrents.csv file. Follow the instructions at heretic/torrents-csv-data on how to build the torrents.db file from the torrents.csv file.

If you opt for a local checkout of the torrents.csv file, then Platypush will build the SQLite database from the CSV file for you - no need to use external services. This however means that the first search will be slower as the database is being built. Subsequent searches will be faster, unless you modify the CSV file - in this case, an updated database will be built from the latest CSV file.

You can also specify the download_csv property in the configuration. In this case, Platypush will automatically download the latest torrents.csv file locally and build the SQLite database from it. On startup, Platypush will check if either the local or remote CSV file has been updated, and rebuild the database if necessary.

popcorntime will be disabled by default unless you explicitly enable it. That’s because, at the time of writing (June 2024), there are no publicly available PopcornTime API servers. You can run your own PopcornTime API server by following the instructions at popcorn-time-ru/popcorn-ru.

Configuration example:

torrent:
  # ...

  search_providers:
    torrents.csv:
      # Default: True
      # enabled: true
      # Base URL of the torrents.csv API.
      api_url: https://torrents-csv.com/service

      # Alternatively, you can also use a local checkout of the
      # torrents.csv file.
      # csv_file: /path/to/torrents.csv

      # Or a manually built SQLite database from the torrents.csv file.
      # db_file: /path/to/torrents.db

      # Or automatically download the latest torrents.csv file.
      # download_csv: true
    popcorn_time:
      # Default: false
      # enabled: false
      # Required: PopcornTime API base URL.
      api_url: https://popcorntime.app
__init__(download_dir: str | None = None, torrent_ports: Iterable[int] = (6881, 6891), search_providers: Dict[str, dict] | Iterable[TorrentSearchProvider] | None = None, **kwargs)[source]#
Parameters:

  • download_dir – Directory where the videos/torrents will be downloaded (default: ~/Downloads).

  • torrent_ports – Torrent ports to listen on (default: 6881 and 6891)

  • search_providers – List of search providers to use.

download(torrent, download_dir=None, _async=False, event_hndl=None, is_media=False)[source]#

Download a torrent.

Parameters:

  • torrent (str) –

    Torrent to download. Supported formats:

    • Magnet URLs

    • Torrent URLs

    • Local torrent file

  • download_dir (str) – Directory to download, overrides the default download_dir attribute (default: None)

  • _async (bool) – If true then the method will add the torrent to the transfer and then return. Updates on the download status should be retrieved either by listening to torrent events or registering the event handler. If false (default) then the method will exit only when the torrent download is complete.

  • event_hndl (function) – A function that takes an event object as argument and is invoked upon a new torrent event (download started, progressing, completed etc.)

  • is_media (bool) – 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

pause(torrent)[source]#

Pause/resume a torrent transfer.

Parameters:

torrent (str) – Torrent URL as returned from get_status()

quit()[source]#

Quits all the transfers and the active session

remove(torrent)[source]#

Stops and removes a torrent transfer.

Parameters:

torrent (str) – Torrent URL as returned from get_status()

resume(torrent)[source]#

Resume a torrent transfer.

Parameters:

torrent (str) – Torrent URL as returned from get_status()

search(query: str, *args, providers: str | Iterable[str] | None = None, limit: int = 25, page: int = 1, **filters)[source]#

Perform a search of video torrents.

Parameters:

  • query – Query string, video name or partial name

  • providers – Override the default search providers by specifying the provider names to use for this search.

  • filters – Additional filters to apply to the search, depending on what the configured search providers support. For example, category and language are supported by the PopcornTime.

  • limit – Maximum number of results to return (default: 25).

  • page – Page number (default: 1).

Returns:

[
  {
    "community_rating": 86.0,
    "country": "USA",
    "created_at": "2021-01-01T00:00:00",
    "critic_rating": 86.0,
    "description": "A description of the torrent",
    "duration": 123.45,
    "episode": 1,
    "file": "/home/user/downloads/2001_a_space_odyssey.torrent",
    "genres": [
      "Sci-Fi",
      "Adventure"
    ],
    "image": "https://example.com/image.jpg",
    "imdb_id": "tt0062622",
    "is_media": true,
    "language": "en",
    "network": "AMC",
    "num_seasons": 5,
    "overview": "Overview of the torrent, if it is a TV show",
    "peers": 123,
    "provider": "popcorntime",
    "quality": "1080p",
    "rating": 86.0,
    "season": 1,
    "seeds": 123,
    "series": "Breaking Bad",
    "series_status": "Ended",
    "size": 123456789,
    "title": "2001: A Space Odyssey",
    "trailer": "https://example.com/trailer.mp4",
    "tvdb_id": "76283",
    "type": "movies",
    "url": "magnet:?xt=urn:btih:...",
    "votes": 123,
    "year": 1968
  }
]

status(torrent=None)[source]#

Get the status of the current transfers.

Parameters:

torrent (str) – Torrent path, URL or magnet URI whose status will be retrieve (default: None, retrieve all current transfers)

Returns:

A dictionary in the format torrent_url -> status