Request (internal)#

class QbittorrentSession#

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, params=None, data=None, headers=None, cookies=None, files=None, auth=None, timeout=None, allow_redirects=True, proxies=None, hooks=None, stream=None, verify=None, cert=None, json=None)#

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

Parameters:

method – method for the new Request object.
url – 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 long 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.
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 (Optional[Mapping[str, str]]) – HTTP headers for request
requests_kwargs (Optional[Mapping[str, Any]]) – 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, 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: object

Facilitates HTTP requests to qBittorrent’s Web API.

_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 (Optional[Mapping[str, Any]]) – key value pairs to send with GET calls
data (Optional[Mapping[str, Any]]) – key value pairs to send with POST calls
files (Optional[Mapping[str, Union[bytes, Tuple[str, bytes]]]]) – dictionary of files to send with request

Return type:

tuple[dict[str, Any], dict[str, Any], Mapping[str, Union[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, 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:

Union[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 (Optional[Mapping[str, Any]]) – default location for Requests kwargs
requests_params (Optional[Mapping[str, Any]]) – alternative location for Requests kwargs
headers (Optional[Mapping[str, str]]) – HTTP headers to send with the request
params (Optional[Mapping[str, Any]]) – key/value pairs to send with a GET request
data (Optional[Mapping[str, Any]]) – key/value pairs to send with a POST request
files (Optional[Mapping[str, Union[bytes, Tuple[str, bytes]]]]) – 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

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