Behavior & Configuration#
Untrusted WebUI Certificate#
qBittorrent allows you to configure HTTPS with an untrusted certificate; this commonly includes self-signed certificates.
When using such a certificate, instantiate Client with
VERIFY_WEBUI_CERTIFICATE=False
or set environment variableQBITTORRENTAPI_DO_NOT_VERIFY_WEBUI_CERTIFICATE
to a non-null value.Failure to do this for will cause connections to qBittorrent to fail.
As a word of caution, doing this actually does turn off certificate verification. Therefore, for instance, potential man-in-the-middle attacks will not be detected and reported (since the error is suppressed). However, the connection will remain encrypted.
Host, Username and Password#
These can be provided when instantiating
Client
qbt_client.auth_log_in(username='...', password='...')
Alternatively, set environment variables:
QBITTORRENTAPI_HOST
QBITTORRENTAPI_USERNAME
QBITTORRENTAPI_PASSWORD
Requests Configuration#
The Requests package is used to issue HTTP requests to qBittorrent to facilitate this API.
Much of
Requests
configuration for making HTTP calls can be controlled with parameters passed along with the request payload.For instance, HTTP Basic Authorization credentials can be provided via
auth
, timeouts viatimeout
, or Cookies viacookies
. See Requests documentation for full details.These parameters are exposed here in two ways; the examples below tell
Requests
to use a connect timeout of 3.1 seconds and a read timeout of 30 seconds.When you instantiate
Client
, you can specify the parameters to use in all HTTP requests to qBittorrent:
qbt_client = Client(..., REQUESTS_ARGS={'timeout': (3.1, 30)}
Alternatively, parameters can be specified for individual requests:
qbt_client.torrents_info(..., requests_args={'timeout': (3.1, 30))
Additional HTTP Headers#
For consistency, HTTP Headers can be specified using the method above; for backwards compatability, the methods below are supported as well.
Either way, these additional headers will be incorporated (using clobbering) into the rest of the headers to be sent.
To send a custom HTTP header in all requests made from an instantiated client, declare them during instantiation:
qbt_client = Client(..., EXTRA_HEADERS={'X-My-Fav-Header': 'header value')
Alternatively, you can send custom headers in individual requests:
qbt_client.torrents.add(..., headers={'X-My-Fav-Header': 'header value')
Unimplemented API Endpoints#
Since the qBittorrent Web API has evolved over time, some endpoints may not be available from the qBittorrent host.
By default, if a call is made to endpoint that doesn’t exist for the version of the qBittorrent host (e.g., the Search endpoints were introduced in Web API v2.1.1), there’s a debug logger output and None is returned.
To raise
NotImplementedError
instead, instantiate Client with:
qbt_client = Client(..., RAISE_NOTIMPLEMENTEDERROR_FOR_UNIMPLEMENTED_API_ENDPOINTS=True)
qBittorrent Version Checking#
It is also possible to either raise an Exception for qBittorrent hosts that are not “fully” supported or manually check for support.
The most likely situation for this to occur is if the qBittorrent team publishes a new release but its changes have not been incorporated in to this client yet.
Instantiate Client like below to raise
UnsupportedQbittorrentVersion
exception for versions not fully supported:
qbt_client = Client(..., RAISE_ERROR_FOR_UNSUPPORTED_QBITTORRENT_VERSIONS=True)
Additionally, the qbittorrentapi.Version class can be used for manual introspection of the versions.
Version.is_app_version_supported(qbt_client.app.version)
Disable Logging Debug Output#
Instantiate Client with
DISABLE_LOGGING_DEBUG_OUTPUT=True
or manually disable logging for the relevant packages:
logging.getLogger('qbittorrentapi').setLevel(logging.INFO)
logging.getLogger('requests').setLevel(logging.INFO)
logging.getLogger('urllib3').setLevel(logging.INFO)