Torrents#

class TorrentsAPIMixIn(host=None, port=None, username=None, password=None, EXTRA_HEADERS=None, REQUESTS_ARGS=None, VERIFY_WEBUI_CERTIFICATE=True, FORCE_SCHEME_FROM_HOST=False, RAISE_NOTIMPLEMENTEDERROR_FOR_UNIMPLEMENTED_API_ENDPOINTS=False, RAISE_ERROR_FOR_UNSUPPORTED_QBITTORRENT_VERSIONS=False, VERBOSE_RESPONSE_LOGGING=False, SIMPLE_RESPONSES=False, DISABLE_LOGGING_DEBUG_OUTPUT=False) → None#

Bases: AppAPIMixIn

Implementation of all Torrents API methods.

Usage:

>>> from qbittorrentapi import Client
>>> client = Client(host="localhost:8080", username="admin", password="adminadmin")
>>> client.torrents_add(urls="...")
>>> client.torrents_reannounce()

torrents_add(urls=None, torrent_files=None, save_path=None, cookie=None, category=None, is_skip_checking=None, is_paused=None, is_root_folder=None, rename=None, upload_limit=None, download_limit=None, use_auto_torrent_management=None, is_sequential_download=None, is_first_last_piece_priority=None, tags=None, content_layout=None, ratio_limit=None, seeding_time_limit=None, download_path=None, use_download_path=None, stop_condition=None, add_to_top_of_queue=None, inactive_seeding_time_limit=None, share_limit_action=None, ssl_certificate=None, ssl_private_key=None, ssl_dh_params=None, is_stopped=None, **kwargs) → str#

Add one or more torrents by URLs and/or torrent files.

Returns Ok. for success and Fails. for failure.

Raises:

UnsupportedMediaType415Error – if file is not a valid torrent file
TorrentFileNotFoundError – if a torrent file doesn’t exist
TorrentFilePermissionError – if read permission is denied to torrent file

Parameters:

urls (Optional[Iterable[str]]) – single instance or an iterable of URLs (http://, https://, magnet:, bc://bt/)
torrent_files (Optional[TypeVar(TorrentFilesT, bytes, str, IO[bytes], Mapping[str, Union[bytes, str, IO[bytes]]], Iterable[Union[bytes, str, IO[bytes]]])]) –
several options are available to send torrent files to qBittorrent:
- single instance of bytes: useful if torrent file already read from disk or downloaded from internet.
- single instance of file handle to torrent file: use open(<filepath>, 'rb') to open the torrent file.
- single instance of a filepath to torrent file: e.g. /home/user/torrent_filename.torrent
- an iterable of the single instances above to send more than one torrent file
- dictionary with key/value pairs of torrent name and single instance of above object
Note: The torrent name in a dictionary is useful to identify which torrent file errored. qBittorrent provides back that name in the error text. If a torrent name is not provided, then the name of the file will be used. And in the case of bytes (or if filename cannot be determined), the value ‘torrent__n’ will be used.
save_path (str | None) – location to save the torrent data
cookie (str | None) – cookie(s) to retrieve torrents by URL
category (str | None) – category to assign to torrent(s)
is_skip_checking (bool | None) – True to skip hash checking
is_paused (bool | None) – Adds torrent in stopped state; alias for is_stopped
is_root_folder (bool | None) – True or False to create root folder (superseded by content_layout with v4.3.2)
rename (str | None) – new name for torrent(s)
upload_limit (str | int | None) – upload limit in bytes/second
download_limit (str | int | None) – download limit in bytes/second
use_auto_torrent_management (bool | None) – True or False to use automatic torrent management
is_sequential_download (bool | None) – True or False for sequential download
is_first_last_piece_priority (bool | None) – True or False for first and last piece download priority
tags (Optional[Iterable[str]]) – tag(s) to assign to torrent(s) (added in Web API v2.6.2)
content_layout (Optional[Literal['Original', 'Subfolder', 'NoSubFolder']]) – Original, Subfolder, or NoSubfolder to control filesystem structure for content (added in Web API v2.7)
ratio_limit (str | float | None) – share limit as ratio of upload amt over download amt; e.g. 0.5 or 2.0 (added in Web API v2.8.1)
seeding_time_limit (str | int | None) – number of minutes to seed torrent (added in Web API v2.8.1)
download_path (str | None) – location to download torrent content before moving to save_path (added in Web API v2.8.4)
use_download_path (bool | None) – True or False whether download_path should be used…defaults to True if download_path is specified (added in Web API v2.8.4)
stop_condition (Optional[Literal['MetadataReceived', 'FilesChecked']]) – MetadataReceived or FilesChecked to stop the torrent when started automatically (added in Web API v2.8.15)
add_to_top_of_queue (bool | None) – puts torrent at top to the queue (added in Web API v2.8.19)
inactive_seeding_time_limit (str | int | None) – limit for seeding while inactive (added in Web API v2.9.2)
share_limit_action (Optional[Literal['Stop', 'Remove', 'RemoveWithContent', 'EnableSuperSeeding']]) – override default action when share limit is reached (added in Web API v2.10.4)
ssl_certificate (str | None) – peer certificate (in PEM format) (added in Web API v2.10.4)
ssl_private_key (str | None) – peer private key (added in Web API v2.10.4)
ssl_dh_params (str | None) – Diffie-Hellman parameters (added in Web API v2.10.4)
is_stopped (bool | None) – Adds torrent in stopped state; alias for is_paused (added in Web API v2.11.0)

Return type:

str

torrents_add_peers(peers=None, torrent_hashes=None, **kwargs) → TorrentsAddPeersDictionary#

Add one or more peers to one or more torrents.

This method was introduced with qBittorrent v4.4.0 (Web API v2.3.0).

Raises:

InvalidRequest400Error – for invalid peers

Parameters:

peers (Optional[Iterable[str]]) – one or more peers to add. each peer should take the form ‘host:port’
torrent_hashes (Optional[Iterable[str]]) – single torrent hash or list of torrent hashes. Or all for all torrents.

Return type:

TorrentsAddPeersDictionary

torrents_add_tags(tags=None, torrent_hashes=None, **kwargs) → None#

Add one or more tags to one or more torrents.

Note: Tags that do not exist will be created on-the-fly.

This method was introduced with qBittorrent v4.2.0 (Web API v2.3.0).

Parameters:

tags (Optional[Iterable[str]]) – tag name or list of tags
torrent_hashes (Optional[Iterable[str]]) – single torrent hash or list of torrent hashes. Or all for all torrents.

Return type: