Request (internal)

class QbittorrentSession → None

Bases: Session

Wrapper to augment Requests Session.

Requests doesn’t allow Session to default certain configuration globally. This gets around that by setting defaults for each request.

request(method, url, **kwargs) → Response

Constructs a Request, prepares it and sends it. Returns Response object.

Parameters:

• method (str) – method for the new Request object.

• url (str) – URL for the new Request object.

• params – (optional) Dictionary or bytes to be sent in the query string for the Request.

• data – (optional) Dictionary, list of tuples, bytes, or file-like object to send in the body of the Request.

• json – (optional) json to send in the body of the Request.

• headers – (optional) Dictionary of HTTP Headers to send with the Request.

• cookies – (optional) Dict or CookieJar object to send with the Request.

• files – (optional) Dictionary of 'filename': file-like-objects for multipart encoding upload.

• auth – (optional) Auth tuple or callable to enable Basic/Digest/Custom HTTP Auth.

• timeout (float or tuple) – (optional) How many seconds to wait for the server to send data before giving up, as a float, or a (connect timeout, read timeout) tuple.

• allow_redirects (bool) – (optional) Set to True by default.

• proxies – (optional) Dictionary mapping protocol or protocol and hostname to the URL of the proxy.

• hooks – (optional) Dictionary mapping hook name to one event or list of events, event must be callable.

• stream – (optional) whether to immediately download the response content. Defaults to False.

• verify – (optional) Either a boolean, in which case it controls whether we verify the server’s TLS certificate, or a string, in which case it must be a path to a CA bundle to use. Defaults to True. When set to False, requests will accept any TLS certificate presented by the server, and will ignore hostname mismatches and/or expired certificates, which will make your application vulnerable to man-in-the-middle (MitM) attacks. Setting verify to False may be useful during local development or testing.

• cert – (optional) if String, path to ssl client cert file (.pem). If Tuple, (‘cert’, ‘key’) pair.

Return type:

Response

class QbittorrentURL(client)

Bases: object

Management for the qBittorrent Web API URL.

build(api_namespace, api_method, headers=None, requests_kwargs=None, base_path='api/v2') → str

Create a fully qualified URL for the API endpoint.

Parameters:

• api_namespace (APINames | str) – the namespace for the API endpoint (e.g. torrents)

• api_method (str) – the specific method for the API endpoint (e.g. info)

• base_path (str) – base path for URL (e.g. api/v2)

• headers (Mapping[str, str] | None) – HTTP headers for request

• requests_kwargs (Mapping[str, Any] | None) – kwargs for any calls to Requests

Return type:

str

Returns:

fully qualified URL string for endpoint

build_base_url(headers, requests_kwargs) → str

Determine the Base URL for the Web API endpoints.

A URL is only actually built here if it’s the first time here or the context was re-initialized. Otherwise, the most recently built URL is used.

If the user doesn’t provide a scheme for the URL, it will try HTTP first and fall back to HTTPS if that doesn’t work. While this is probably backwards, qBittorrent or an intervening proxy can simply redirect to HTTPS and that’ll be respected.

Additionally, if users want to augment the path to the API endpoints, any path provided here will be preserved in the returned Base URL and prefixed to all subsequent API calls.

Parameters:

• headers (Mapping[str, str]) – HTTP headers for request

• requests_kwargs (Mapping[str, Any]) – arguments from user for HTTP HEAD request

Return type:

str

Returns:

base URL as a string for Web API endpoint

detect_scheme(base_url, default_scheme, alt_scheme, headers, requests_kwargs) → str

Determine if the URL endpoint is using HTTP or HTTPS.

Parameters:

• base_url (ParseResult) – urllib ParseResult URL object

• default_scheme (str) – default scheme to use for URL

• alt_scheme (str) – alternative scheme to use for URL if default doesn’t work

• headers (Mapping[str, str]) – HTTP headers for request

• requests_kwargs (Mapping[str, Any]) – kwargs for calls to Requests

Return type:

str

Returns:

scheme (i.e. HTTP or HTTPS)

class Request(host=None, port=None, username=None, password=None, api_key=None, EXTRA_HEADERS=None, REQUESTS_ARGS=None, HTTPADAPTER_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: object

Facilitates HTTP requests to qBittorrent’s Web API.

_SENSITIVE_HEADERS = frozenset({'authorization', 'cookie', 'set-cookie'})

HTTP headers whose values carry credentials and must be redacted from logging.

_auth_request(http_method, api_namespace, api_method, _retry_backoff_factor=0.3, requests_args=None, requests_params=None, headers=None, params=None, data=None, files=None, response_class=<class 'requests.models.Response'>, version_introduced='', version_removed='', **kwargs) → Any

Wraps API call with re-authorization if first attempt is not authorized.

Return type:

Any

_cast(response, response_class, **response_kwargs) → Any

Returns the API response casted to the requested class.

Parameters:

• response (Response) – requests Response from API

• response_class (type) – class to return response as; if none, response is returned

• response_kwargs (Any) – request-specific configuration for response

Return type:

Any

static _format_payload(http_method, params=None, data=None, files=None, **kwargs) → tuple[dict[str, Any], dict[str, Any], Mapping[str, bytes | tuple[str, bytes]]]

Determine data, params, and files for the Requests call.

Parameters:

• http_method (str) – get or post

• params (Mapping[str, Any] | None) – key value pairs to send with GET calls

• data (Mapping[str, Any] | None) – key value pairs to send with POST calls

• files (Mapping[str, bytes | tuple[str, bytes]] | None) – dictionary of files to send with request

Return type:

tuple[dict[str, Any], dict[str, Any], Mapping[str, bytes | tuple[str, bytes]]]

_get(_name, _method, requests_args=None, requests_params=None, headers=None, params=None, data=None, files=None, response_class=<class 'requests.models.Response'>, version_introduced='', version_removed='', **kwargs) → Any

Send GET request.

Parameters:

• api_namespace – the namespace for the API endpoint (e.g. APINames or torrents)

• api_method – the name for the API endpoint (e.g. add)

• kwargs (Any) – see _request()

Return type:

Any

Returns:

Requests Response

_get_cast(_name, _method, response_class, requests_args=None, requests_params=None, headers=None, params=None, data=None, files=None, version_introduced='', version_removed='', **kwargs) → ResponseT

Send GET request with casted response.

Parameters:

• api_namespace – the namespace for the API endpoint (e.g. APINames or torrents)

• api_method – the name for the API endpoint (e.g. add)

• kwargs (Any) – see _request()

Return type:

TypeVar(ResponseT)

static _handle_error_responses(data, params, response) → None

Raise proper exception if qBittorrent returns Error HTTP Status.

Return type:

None

_initialize_context() → None

Initialize and reset communications context with qBittorrent.

This is necessary on startup or when the authorization cookie needs to be replaced…perhaps because it expired, qBittorrent was restarted, significant settings changes, etc.

Return type:

None

_initialize_settings(EXTRA_HEADERS=None, REQUESTS_ARGS=None, HTTPADAPTER_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

Initialize lesser used configuration.

Return type:

None

_is_endpoint_supported_for_version(endpoint, version_introduced, version_removed) → bool

Prevent using an API methods that doesn’t exist in this version of qBittorrent.

Parameters:

• endpoint (str) – name of the removed endpoint, e.g. torrents/ban_peers

• version_introduced (str) – the Web API version the endpoint was introduced

• version_removed (str) – the Web API version the endpoint was removed

Return type:

bool

classmethod _list2string(input_list, delimiter='|') → str | T

Convert entries in a list to a concatenated string.

Parameters:

• input_list (TypeVar(T)) – list to convert

• delimiter (str) – delimiter for concatenation

Return type:

str | TypeVar(T)

_post(_name, _method, requests_args=None, requests_params=None, headers=None, params=None, data=None, files=None, response_class=<class 'requests.models.Response'>, version_introduced='', version_removed='', **kwargs) → Any

Send POST request.

Parameters:

• api_namespace – the namespace for the API endpoint (e.g. APINames or torrents)

• api_method – the name for the API endpoint (e.g. add)

• kwargs (Any) – see _request()

Return type:

Any

_post_cast(_name, _method, response_class, requests_args=None, requests_params=None, headers=None, params=None, data=None, files=None, version_introduced='', version_removed='', **kwargs) → ResponseT

Send POST request with casted response.

Parameters:

• api_namespace – the namespace for the API endpoint (e.g. APINames or torrents)

• api_method – the name for the API endpoint (e.g. add)

• kwargs (Any) – see _request()

Return type:

TypeVar(ResponseT)

_request(http_method, api_namespace, api_method, requests_args=None, requests_params=None, headers=None, params=None, data=None, files=None, response_class=<class 'requests.models.Response'>, **kwargs) → Any

Meat and potatoes of sending requests to qBittorrent.

Parameters:

• http_method (str) – get or post

• api_namespace (APINames | str) – the namespace for the API endpoint (e.g. APINames or torrents)

• api_method (str) – the name for the API endpoint (e.g. add)

• requests_args (Mapping[str, Any] | None) – default location for Requests kwargs

• requests_params (Mapping[str, Any] | None) – alternative location for Requests kwargs

• headers (Mapping[str, str] | None) – HTTP headers to send with the request

• params (Mapping[str, Any] | None) – key/value pairs to send with a GET request

• data (Mapping[str, Any] | None) – key/value pairs to send with a POST request

• files (Mapping[str, bytes | tuple[str, bytes]] | None) – files to be sent with the request

• response_class (type) – class to use to cast the API response

• kwargs (Any) – arbitrary keyword arguments to send with the request

Return type:

Any

_request_manager(http_method, api_namespace, api_method, _retries=1, _retry_backoff_factor=0.3, requests_args=None, requests_params=None, headers=None, params=None, data=None, files=None, response_class=<class 'requests.models.Response'>, version_introduced='', version_removed='', **kwargs) → Any

Wrapper to manage request retries and severe exceptions.

This should retry at least once to account for the Web API switching from HTTP to HTTPS. During the second attempt, the URL is rebuilt using HTTP or HTTPS as appropriate.

Return type:

Any

classmethod _sanitize_headers(headers) → dict[str, str]

Return a copy of headers with credential values redacted.

Prevents secrets such as the API key (Authorization header) or session cookie from being exposed in verbose logging output.

Return type:

dict[str, str]

property _session: QbittorrentSession

Create or return existing HTTP session.

_trigger_session_initialization() → None

Effectively resets the HTTP session by removing the reference to it.

During the next request, a new session will be created.

Return type:

None

_verbose_logging(url, data, params, requests_kwargs, response) → None

Log verbose information about request; can be useful during development.

Return type:

None