torrent
#
Description#
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 thetorrents.csv
file in thecsv_file
attribute.A local checkout of the
torrents.db
file built from thetorrents.csv
file. Follow the instructions at heretic/torrents-csv-data on how to build thetorrents.db
file from thetorrents.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
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 sqlite3 py3-libtorrent-rasterbar
Debian
apt install sqlite3 python3-libtorrent
Fedora
yum install sqlite3 rb_libtorrent-python3
Arch Linux
pacman -S sqlite3 libtorrent-rasterbar
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 thesearch_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 remote API via the
A local checkout of the
torrents.csv
file. Clone the heretic/torrents-csv-data and provide the path to thetorrents.csv
file in thecsv_file
attribute.A local checkout of the
torrents.db
file built from thetorrents.csv
file. Follow the instructions at heretic/torrents-csv-data on how to build thetorrents.db
file from thetorrents.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 latesttorrents.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()
- 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
andlanguage
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 } ]