Search¶

class SearchAPIMixIn(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: AppAPIMixIn

Implementation for all Search API methods.

Usage:

>>> from qbittorrentapi import Client
>>> client = Client(host="localhost:8080", username="admin", password="adminadmin")
>>> search_job = client.search_start(pattern="Ubuntu", plugins="all", category="all")
>>> client.search_stop(search_id=search_job.id)
>>> # or
>>> search_job.stop()

search_categories(plugin_name=None, **kwargs) → SearchCategoriesList¶

Retrieve categories for search.

This method was introduced with qBittorrent v4.1.4 (Web API v2.1.1) and removed with qBittorrent v4.3.0 (Web API v2.6).

Parameters:: plugin_name (str | None) – Limit categories returned by plugin(s) (supports all and enabled)
Return type:: SearchCategoriesList

search_delete(search_id=None, **kwargs) → None¶

Delete a search job.

This method was introduced with qBittorrent v4.1.4 (Web API v2.1.1).

Raises:: NotFound404Error –
Parameters:: search_id (str | int | None) – ID of search to delete
Return type:: None

search_download_torrent(url=None, plugin=None, **kwargs) → None¶

Download a .torrent file or magnet for a search plugin.

This method was introduced with qBittorrent v5.0.0 (Web API v2.11).

Parameters:

url (str | None) – URL for .torrent file or magnet
plugin (str | None) – Name of the plugin

Return type:

None

search_enable_plugin(plugins=None, enable=None, **kwargs) → None¶

Enable or disable search plugin(s).

This method was introduced with qBittorrent v4.1.4 (Web API v2.1.1).

Parameters:

plugins (str | Iterable[str] | None) – list of plugin names
enable (bool | None) – Defaults to True if None or unset; use False to disable

Return type:

None

search_install_plugin(sources=None, **kwargs) → None¶

Install search plugins from either URL or file.

This method was introduced with qBittorrent v4.1.4 (Web API v2.1.1).

Parameters:: sources (str | Iterable[str] | None) – list of URLs or filepaths
Return type:: None

search_plugins(**kwargs) → SearchPluginsList¶

Retrieve details of search plugins.

This method was introduced with qBittorrent v4.1.4 (Web API v2.1.1).

Return type:: SearchPluginsList

search_results(search_id=None, limit=None, offset=None, **kwargs) → SearchResultsDictionary¶

Retrieve the results for the search.

This method was introduced with qBittorrent v4.1.4 (Web API v2.1.1).

Raises:

NotFound404Error –
Conflict409Error –

Parameters:

search_id (str | int | None) – ID of search job
limit (str | int | None) – number of results to return
offset (str | int | None) – where to start returning results

Return type:

SearchResultsDictionary

search_start(pattern=None, plugins=None, category=None, **kwargs) → SearchJobDictionary¶

Start a search. Python must be installed. Host may limit number of concurrent searches.

This method was introduced with qBittorrent v4.1.4 (Web API v2.1.1).

Raises:

Conflict409Error –

Parameters:

pattern (str | None) – term to search for
plugins (str | Iterable[str] | None) – list of plugins to use for searching (supports ‘all’ and ‘enabled’)
category (str | None) – categories to limit search; dependent on plugins. (supports ‘all’)

Return type:

SearchJobDictionary

search_status(search_id=None, **kwargs) → SearchStatusesList¶

Retrieve status of one or all searches.

This method was introduced with qBittorrent v4.1.4 (Web API v2.1.1).

Raises:: NotFound404Error –
Parameters:: search_id (str | int | None) – ID of search to get status; leave empty for status of all jobs
Return type:: SearchStatusesList

search_stop(search_id=None, **kwargs) → None¶

Stop a running search.

This method was introduced with qBittorrent v4.1.4 (Web API v2.1.1).

Raises:: NotFound404Error –
Parameters:: search_id (str | int | None) – ID of search job to stop
Return type:: None

search_uninstall_plugin(names=None, **kwargs) → None¶

Uninstall search plugins.

This method was introduced with qBittorrent v4.1.4 (Web API v2.1.1).

Parameters:: names (str | Iterable[str] | None) – names of plugins to uninstall
Return type:: None

search_update_plugins(**kwargs) → None¶

Auto update search plugins.

This method was introduced with qBittorrent v4.1.4 (Web API v2.1.1).

Return type:: None

class Search(*args, client, **kwargs)¶

Allows interaction with Search API endpoints.

Usage:

>>> from qbittorrentapi import Client
>>> client = Client(host="localhost:8080", username="admin", password="adminadmin")
>>> # this is all the same attributes that are available as named in the
>>> #  endpoints or the more pythonic names in Client (with or without 'search_' prepended)
>>> # initiate searches and retrieve results
>>> search_job = client.search.start(pattern="Ubuntu", plugins="all", category="all")
>>> status = search_job.status()
>>> results = search_job.result()
>>> search_job.delete()
>>> # inspect and manage plugins
>>> plugins = client.search.plugins
>>> cats = client.search.categories(plugin_name="...")
>>> client.search.install_plugin(sources="...")
>>> client.search.update_plugins()