Reference

Client

Create client

Create APIClient.

When both username and password are given, the returned client will have been successfully authenticated and automatically configured. Otherwise, LoginError is raised.

If they are omitted, client.auth.login() need to be called manually.

Parameters:

url (str) – URL to WebUI API, for example, https://localhost:8080/api/v2/
username (str) – login name
password (str) – login password
logout_when_close – whether logout during close().
http – aiohttp.ClientSession object
ssl – ssl.SSLContext for custom TLS connections

Raises:

LoginError – if authentication is failed.

Client

class aioqbt.client.APIClient[source]

Represent a remote qBittorrent client.

property app: AppAPI: Application API methods.

property auth: AuthAPI: Authentication API methods.

property log: LogAPI: Log API methods.

property rss: RSSAPI: RSS API methods.

property search: SearchAPI: Search API methods.

property sync: SyncAPI: Sync API methods.

property torrents: TorrentsAPI: Torrents API methods.

property transfer: TransferAPI: Transfer API methods.

property client_version: ClientVersion | None: qBittorrent client version

property api_version: APIVersion | None: qBittorrent API version

is_closed() → bool[source]: Tell whether client is closed

async close() → None[source]

Close client.

Release/detach resources acquired by client.

async request(method: str, endpoint: str, *, params: Any = None, data: Any = None, max_attempts: int = 3, retry_delay: float = 5, ssl: SSLContext | None = None, **kwargs: object) → ClientResponse[source]

Send an HTTP request and return a response object.

Argument method specifies the HTTP method (e.g. GET) while endpoint the API endpoint (e.g. torrents/info).

params forms the query string of the request URL. data is the payload in the request body. See the underlying ClientSession.request for their allowed values.

max_attempts is the maximum number of attempts. Retry is performed if two additional conditions are satisfied:

GET or HEAD requets
Remote disconnection, or repsonse status 429 (Too many requests), 503 (Service unavailable), or 502 (Bad gateway).

The result is aiohttp.ClientResponse, and should be used in async with.

Parameters:

method (str) – HTTP method.
endpoint (str) – API endpoint.
params – parameters in query string
data – data in request body
max_attempts (int) – maximum number of attempts
retry_delay (float) – maximum delay between attempts
ssl – SSLContext, optional

Raises:

APIError – API errors (non-200 status).
aiohttp.ClientError – connection errors

Returns:

ClientResponse

async request_text(method: str, endpoint: str, **kwargs: Any) → str[source]: Send a request and return a str.

async request_json(method: str, endpoint: str, **kwargs: Any) → Any[source]: Send a request and return a JSON-decoded object.

class aioqbt.client.APIGroup[source]: API group of methods.

APIs

API methods by group.

See also the WebUI API reference on qBittorrent wiki.

Torrents

class aioqbt.api.TorrentsAPI[source]

API methods under torrents.

async count() → int[source]: Get the number of torrents

Get a list of TorrentInfo.

To obtain a list of completed torrents sorted by name:

torrents = await client.torrents.info(
    filter=InfoFilter.COMPLETED,
    sort="name",
)

See also torrents/info for filter and result meanings.

Parameters:

filter – State filter: InfoFilter or str.
category – category filter.
sort – Sort results by an attribute/field.
reverse – Reverse the results.
limit – Maximum number of returned results.
offset – Results starting from the offset-th torrents.
hashes – A list of info hashes, or a str all.
tag – Tag filter.

async properties(hash: InfoHash) → TorrentProperties[source]: Get properties of a torrent.

async trackers(hash: InfoHash) → List[Tracker][source]: Trackers in a torrent.

async webseeds(hash: InfoHash) → List[WebSeed][source]: Web seeds in a torrent.

async files(hash: InfoHash, indexes: Iterable[int] | None = None) → List[FileEntry][source]: Files in a torrent.

async piece_states(hash: InfoHash) → List[int][source]

A list of piece states in a torrent.

To compare results, use following constants from PieceState enum:

PieceState.UNAVAILABLE
PieceState.DOWNLOADING
PieceState.DOWNLOADED

async piece_hashes(hash: InfoHash) → List[str][source]: A list of piece hashes in a torrent.

async pause(hashes: Iterable[InfoHash] | Literal['all']) → None[source]

Pause torrents.

Torrents can be specified by their info hashes. Passing all pauses all torrents.

async resume(hashes: Iterable[InfoHash] | Literal['all']) → None[source]

Resume torrents.

Torrents can be specified by their info hashes. Passing all resumes all torrents.

async delete(hashes: Iterable[InfoHash] | Literal['all'], delete_files: bool) → None[source]

Delete torrents.

Torrents can be specified by their info hashes. Passing all deletes all torrents.

Pass True to delete_files to remove downloaded content.

async recheck(hashes: Iterable[InfoHash] | Literal['all']) → None[source]: Recheck torrents.

async reannounce(hashes: Iterable[InfoHash] | Literal['all']) → None[source]: Reannounce torrents.

async add(form: FormData) → None[source]

Add torrents by URLs, info hashes, and/or file blobs.

See AddFormBuilder on how to configure and build FormData to submit.

Note

AddTorrentError may raise if no new torrents are added.

Parameters:: form – form data to submit.

async add_trackers(hash: InfoHash, trackers: Iterable[str]) → None[source]

async edit_tracker(hash: InfoHash, orig_url: str, new_url: str) → None[source]

async remove_trackers(hash: InfoHash, urls: Iterable[str]) → None[source]

async add_peers(hashes: Iterable[InfoHash], peers: Iterable[str]) → None[source]

async top_prio(hashes: Iterable[InfoHash] | Literal['all']) → None[source]

async bottom_prio(hashes: Iterable[InfoHash] | Literal['all']) → None[source]

async increase_prio(hashes: Iterable[InfoHash] | Literal['all']) → None[source]

async decrease_prio(hashes: Iterable[InfoHash] | Literal['all']) → None[source]

async file_prio(hash: InfoHash, id: Iterable[int], priority: int) → None[source]

Prioritize files in a torrent.

Parameters:

hash – Info hash
id – A list of file indices to prioritize.
priority – Priority, FilePriority.

async download_limit(hashes: Iterable[InfoHash] | Literal['all']) → Dict[str, int][source]

Get torrent download limits.

The result is a dict mapping info hash to download speed limit in bytes/second.

Parameters:: hashes – A list of info hashes or all for all torrents.

async set_download_limit(hashes: Iterable[InfoHash] | Literal['all'], limit: int) → None[source]

Update torrent download limits.

Parameters:

hashes – A list of info hashes or all for all torrents.
limit – Download limit in bytes/second.

Set share limits for torrents.

Parameters:

hashes – A list of info hashes or all for all torrents.
ratio_limit – A number or RatioLimits.UNSET.
seeding_time_limit – timedelta, or SeedingTimeLimits constants.
inactive_seeding_time_limit – timedelta, or InactiveSeedingTimeLimits constants. Required since qBittorrent v4.6.0 (API 2.9.2).

async upload_limit(hashes: Iterable[InfoHash] | Literal['all']) → Dict[str, int][source]

Get torrent upload limits.

The result is a dict mapping info hash to upload speed limit in bytes/second.

Parameters:: hashes – A list of info hashes or all for all torrents.

async set_upload_limit(hashes: Iterable[InfoHash] | Literal['all'], limit: int) → None[source]

Update torrent upload limits.

Parameters:

hashes – A list of info hashes or all for all torrents.
limit – Upload limit in bytes/second.

async set_location(hashes: Iterable[InfoHash] | Literal['all'], location: str | PathLike[str]) → None[source]

Change location (save path) for torrents.

This method also turns off auto torrent management (AutoTMM) for torrents.

AddFormBuilder

class aioqbt.api.AddFormBuilder[source]

Build aiohttp.FormData used in TorrentsAPI.add().

AddFormBuilder is designed in fluent interface. Most of its methods return a modified copy of the builder.

Here is an example to illustrate:

await client.torrent.add(
    # Create a builder with a particular client
    AddFormBuilder.with_client(client)

    # Set torrent category to "linux"
    .category("linux")

    # Set ratio limit to 10
    .ratio_limit(10)

    # Add a torrent by its info hash (debian-11.7.0-amd64-netinst.iso)
    .include_url("6f84758b0ddd8dc05840bf932a77935d8b5b8b93")

    # Add a torrent by URL/magnet link (debian-11.6.0-amd64-netinst.iso)
    .include_url("magnet:?xt=urn:btih:6d4795dee70aeb88e03e5336ca7c9fcf0a1e206d")

    # Upload a torrent with its bytes data and name
    .include_url(file_bytes, "debian-12.0.0-amd64-netinst.iso")

    # Generate FormData object
    .build()
)

App

class aioqbt.api.AppAPI[source]

API methods under app.

async version() → str[source]: qBittorrent version.

async webapi_version() → str[source]: WebUI API version.

async build_info() → BuildInfo[source]: Build information.

async shutdown() → None[source]: Shut down qBittorrent client.

async preferences() → Preferences[source]: Get application preferences.

async set_preferences(prefs: Mapping[str, object]) → None[source]

Set application preferences.

Parameters:: prefs – a mapping of preferences to update.

async default_save_path() → str[source]: Default save path for storing downloaded files

async network_interface_list() → List[NetworkInterface][source]: Network interfaces.

async network_interface_address_list(iface: str | None = None) → List[str][source]: Network addresses.

Auth

class aioqbt.api.AuthAPI[source]

API methods under auth.

async login(username: str, password: str) → None[source]

async logout() → None[source]

Log

class aioqbt.api.LogAPI[source]

API methods under log.

async main(normal: bool | None = None, info: bool | None = None, warning: bool | None = None, critical: bool | None = None, last_known_id: int | None = None) → List[LogMessage][source]

async peers(last_known_id: int | None = None) → List[LogPeer][source]

Sync

class aioqbt.api.SyncAPI[source]

Sync APIs.

In Sync APIs, changes between requests are returned in dict-like objects. Keys may be omitted if their values are unchanged.

async maindata(rid: int | None = None) → SyncMainData[source]

Obtain sync data.

rid in the previous sync data may be passed to the rid argument to obtain a difference update.

If full_update=True in the resultant object, the data is a full update. Otherwise, the data only contains changes since the last sync request.

async torrent_peers(hash: InfoHash, rid: int | None = None) → SyncTorrentPeers[source]

Obtain peers for a torrent.

rid and full_update share similar meanings in maindata().

Transfer

class aioqbt.api.TransferAPI[source]

API methods under transfer.

async info() → TransferInfo[source]

async speed_limits_mode() → int[source]

async toggle_speed_limits_mode() → None[source]

async set_speed_limits_mode(mode: int) → None[source]

Change speed_limits_mode.

If API version is less than v2.8.14, a polyfill is used to set the mode.

async download_limit() → int[source]: Get download limit (byte/second)

async set_download_limit(limit: int) → None[source]: Set download limit (byte/second)

async upload_limit() → int[source]: Get upload limit (byte/second)

async set_upload_limit(limit: int) → None[source]: Set upload limit (byte/second)

async ban_peers(peers: Iterable[Tuple[str, int]]) → None[source]

Ban peers.

Address may be IPv4 or IPv6 but not domain name.

Parameters:: peers – (addr, port) pairs

RSS

class aioqbt.api.RSSAPI[source]

RSS APIs

Note

RSS API is experimental. Methods and results may change without notice.

async add_folder(path: str) → None[source]

Add a new folder.

Raise ConflictError if error.

async add_feed(url: str, path: str) → None[source]

Add a new feed.

Raise ConflictError if error.

async remove_item(path: str) → None[source]

Add a feed/folder.

Raise ConflictError if error.

async move_item(item_path: str, dest_path: str) → None[source]

Move a feed/folder.

Raise ConflictError if error.

async items(with_data: bool | None = None) → RSSFolder[source]

Get the root folder, which consists of all feeds and sub-folders.

If with_data=True, feed title and a list of articles will also be available. See RSSFeed.

async mark_as_read(item_path: str, article_id: str | None = None) → None[source]: Mark an article as read.

async refresh_item(item_path: str) → None[source]: Refresh a folder/feed.

async set_rule(rule_name: str, rule_def: str | RSSRule | Mapping[str, object]) → None[source]: Add/update a rule.

async rename_rule(rule_name: str, new_rule_name: str) → None[source]: Rename a rule.

Note

Before API 2.6.1, there was a bug that renaming rule would not change the result of rules().

async remove_rule(rule_name: str) → None[source]: Remove a rule.

async rules() → Dict[str, RSSRule][source]: Get all rules.

async matching_articles(rule_name: str) → Dict[str, List[str]][source]

Get articles matched by a rule.

The result is a dict mapping feed names to lists of article titles.

Search

class aioqbt.api.SearchAPI[source]

Search APIs.

Note

Search API is experimental. Methods and results may change without notice.

async start(pattern: str, plugins: List[str] | Literal['all'] | Literal['enabled'], category: str | Literal['all']) → SearchJobStart[source]

Start a search job.

The result consists of only the search job id.

Parameters:

pattern – Search pattern.
plugins – Plugins used in search. Special values: all uses all plugins while enabled uses enabled plugins only.
category – Search specific category or all.

Raises:

ConflictError – if error.

async stop(id: int) → None[source]

Stop a search job.

Raises:: NotFoundError – if the search job is not found.

async status(id: int | None = None) → List[SearchJobStatus][source]

Query search job statuses.

Raises:: NotFoundError – if the search job is specified but not found.

async results(id: int, limit: int | None = None, offset: int | None = None) → SearchJobResults[source]

Get search job results.

Raises:

NotFoundError – if the search job is not found.
ConflictError – if offset is out of range.

async delete(id: int) → None[source]

Delete a search job.

Raises:: NotFoundError – if the search job is not found.

async plugins() → List[SearchPlugin][source]: Get all plugins.

async install_plugin(sources: Iterable[str]) → None[source]: Install plugins.

async uninstall_plugin(names: Iterable[str]) → None[source]: Uninstall plugins.

async enable_plugin(names: Iterable[str], enable: bool) → None[source]

Enable/disable plugins.

Parameters:

names – a list of plugins to enable/disable.
enable – True to enable or False to disable.

async update_plugins() → None[source]: Update plugins.

Constants

class aioqbt.api.TorrentState[source]

Possible torrent states in TorrentInfo.state.

ERROR = 'error'

MISSING_FILES = 'missingFiles'

UPLOADING = 'uploading'

PAUSED_UP = 'pausedUP'

QUEUED_UP = 'queuedUP'

STALLED_UP = 'stalledUP'

CHECKING_UP = 'checkingUP'

FORCED_UP = 'forcedUP'

ALLOCATING = 'allocating'

DOWNLOADING = 'downloading'

META_DL = 'metaDL'

PAUSED_DL = 'pausedDL'

QUEUED_DL = 'queuedDL'

STALLED_DL = 'stalledDL'

CHECKING_DL = 'checkingDL'

FORCED_DL = 'forcedDL'

CHECKING_RESUME_DATA = 'checkingResumeData'

MOVING = 'moving'

UNKNOWN = 'unknown'

class aioqbt.api.InfoFilter[source]

Torrent state filter in TorrentsAPI.info().

ALL = 'all'

DOWNLOADING = 'downloading'

SEEDING = 'seeding'

COMPLETED = 'completed'

RESUMED = 'resumed'

PAUSED = 'paused'

ACTIVE = 'active'

INACTIVE = 'inactive'

STALLED = 'stalled'

STALLED_UPLOADING = 'stalled_uploading'

STALLED_DOWNLOADING = 'stalled_downloading'

ERRORED = 'errored'

class aioqbt.api.PieceState[source]

Piece state in TorrentsAPI.piece_states() results.

UNAVAILABLE = 0

DOWNLOADING = 1

DOWNLOADED = 2

class aioqbt.api.TrackerStatus[source]

Tracker status in Tracker.status.

DISABLED = 0

NOT_CONTACTED = 1

WORKING = 2

UPDATING = 3

NOT_WORKING = 4

class aioqbt.api.RatioLimits[source]

Special values of ratio limit.

UNSET = -1

class aioqbt.api.SeedingTimeLimits[source]

Special values of seeding time limit.

GLOBAL = -2

UNLIMITED = -1

class aioqbt.api.StopCondition[source]

Stopping condition to pause torrents.

NONE = 'None'

METADATA_RECEIVED = 'MetadataReceived'

FILES_CHECKED = 'FilesChecked'

class aioqbt.api.ContentLayout[source]

Content layout that downloaded files are organized.

ORIGINAL = 'Original'

SUBFOLDER = 'Subfolder'

NO_SUBFOLDER = 'NoSubfolder'

class aioqbt.api.FilePriority[source]

File priority in TorrentsAPI.file_prio() and FileEntry.priority.

NO_DOWNLOAD = 0

NORMAL = 1

HIGH = 6

MAXIMAL = 7

class aioqbt.api.ConnectionStatus[source]

Connection status in TransferInfo.connection_status.

CONNECTED = 'connected'

FIREWALLED = 'firewalled'

DISCONNECTED = 'disconnected'

Data structures

class aioqbt.api.BuildInfo[source]

See AppAPI.build_info().

qt: str

libtorrent: str

boost: str

openssl: str

zlib: str

bitness: int

class aioqbt.api.Preferences[source]

Bases: TypedDict

Dict of preferences.

Note

Preference keys may be added/changed/removed across versions. Please refer to the documentation.

locale: str

performance_warning: bool

file_log_enabled: bool

file_log_path: str

file_log_backup_enabled: bool

file_log_max_size: int

file_log_delete_old: bool

file_log_age: int

file_log_age_type: int

torrent_content_layout: str

add_to_top_of_queue: bool

create_subfolder_enabled: bool

start_paused_enabled: bool

torrent_stop_condition: str

merge_trackers: bool

auto_delete_mode: int

preallocate_all: bool

incomplete_files_ext: bool

auto_tmm_enabled: bool

torrent_changed_tmm_enabled: bool

save_path_changed_tmm_enabled: bool

category_changed_tmm_enabled: bool

use_subcategories: bool

save_path: str

temp_path_enabled: bool

temp_path: str

use_category_paths_in_manual_mode: bool

export_dir: str

export_dir_fin: str

scan_dirs: Dict[str, int | str]

excluded_file_names_enabled: bool

excluded_file_names: str

mail_notification_enabled: bool

mail_notification_sender: str

mail_notification_email: str

mail_notification_smtp: str

mail_notification_ssl_enabled: bool

mail_notification_auth_enabled: bool

mail_notification_username: str

mail_notification_password: str

autorun_on_torrent_added_enabled: bool

autorun_on_torrent_added_program: str

autorun_enabled: bool

autorun_program: str

listen_port: int

random_port: bool

upnp: bool

max_connec: int

max_connec_per_torrent: int

max_uploads: int

max_uploads_per_torrent: int

proxy_type: int | str

proxy_ip: str

proxy_port: int

proxy_auth_enabled: bool

proxy_username: str

proxy_password: str

proxy_hostname_lookup: bool

proxy_bittorrent: bool

proxy_torrents_only: bool

proxy_peer_connections: bool

proxy_rss: bool

proxy_misc: bool

ip_filter_enabled: bool

ip_filter_path: str

ip_filter_trackers: bool

banned_IPs: str

dl_limit: int

up_limit: int

alt_dl_limit: int

alt_up_limit: int

bittorrent_protocol: int

limit_utp_rate: bool

limit_tcp_overhead: bool

limit_lan_peers: bool

scheduler_enabled: bool

schedule_from_hour: int

schedule_from_min: int

schedule_to_hour: int

schedule_to_min: int

scheduler_days: int

dht: bool

pex: bool

lsd: bool

encryption: int

anonymous_mode: bool

max_active_checking_torrents: int

queueing_enabled: bool

max_active_downloads: int

max_active_torrents: int

max_active_uploads: int

dont_count_slow_torrents: bool

slow_torrent_dl_rate_threshold: int

slow_torrent_ul_rate_threshold: int

slow_torrent_inactive_timer: int

max_ratio_enabled: bool

max_ratio: int

max_seeding_time_enabled: bool

max_seeding_time: int

max_inactive_seeding_time_enabled: bool

max_inactive_seeding_time: int

max_ratio_act: int

add_trackers_enabled: bool

add_trackers: str

web_ui_domain_list: str

web_ui_address: str

web_ui_port: int

web_ui_upnp: bool

use_https: bool

web_ui_https_cert_path: str

web_ui_https_key_path: str

web_ui_username: str

bypass_local_auth: bool

bypass_auth_subnet_whitelist_enabled: bool

bypass_auth_subnet_whitelist: str

web_ui_max_auth_fail_count: int

web_ui_ban_duration: int

web_ui_session_timeout: int

alternative_webui_enabled: bool

alternative_webui_path: str

web_ui_clickjacking_protection_enabled: bool

web_ui_csrf_protection_enabled: bool

web_ui_secure_cookie_enabled: bool

web_ui_host_header_validation_enabled: bool

web_ui_use_custom_http_headers_enabled: bool

web_ui_custom_http_headers: str

web_ui_reverse_proxy_enabled: bool

web_ui_reverse_proxies_list: str

dyndns_enabled: bool

dyndns_service: int

dyndns_username: str

dyndns_password: str

dyndns_domain: str

rss_refresh_interval: int

rss_max_articles_per_feed: int

rss_processing_enabled: bool

rss_auto_downloading_enabled: bool

rss_download_repack_proper_episodes: bool

rss_smart_episode_filters: str

resume_data_storage_type: str

memory_working_set_limit: int

current_network_interface: str

current_interface_name: str

current_interface_address: str

save_resume_data_interval: int

torrent_file_size_limit: int

recheck_completed_torrents: bool

refresh_interval: int

resolve_peer_countries: bool

reannounce_when_address_changed: bool

bdecode_depth_limit: int

bdecode_token_limit: int

async_io_threads: int

hashing_threads: int

file_pool_size: int

checking_memory_use: int

disk_cache: int

disk_cache_ttl: int

disk_queue_size: int

disk_io_type: int

disk_io_read_mode: int

disk_io_write_mode: int

enable_os_cache: bool

enable_coalesce_read_write: bool

enable_piece_extent_affinity: bool

enable_upload_suggestions: bool

send_buffer_watermark: int

send_buffer_low_watermark: int

send_buffer_watermark_factor: int

connection_speed: int

socket_send_buffer_size: int

socket_receive_buffer_size: int

socket_backlog_size: int

outgoing_ports_min: int

outgoing_ports_max: int

upnp_lease_duration: int

peer_tos: int

utp_tcp_mixed_mode: int

idn_support_enabled: bool

enable_multi_connections_from_same_ip: bool

validate_https_tracker_certificate: bool

ssrf_mitigation: bool

block_peers_on_privileged_ports: bool

enable_embedded_tracker: bool

embedded_tracker_port: int

embedded_tracker_port_forwarding: bool

upload_slots_behavior: int

upload_choking_algorithm: int

announce_to_all_trackers: bool

announce_to_all_tiers: bool

announce_ip: str

max_concurrent_http_announces: int

stop_tracker_timeout: int

peer_turnover: int

peer_turnover_cutoff: int

peer_turnover_interval: int

request_queue_size: int

force_proxy: bool

ssl_cert: str

ssl_key: str

web_ui_password: str

class aioqbt.api.NetworkInterface[source]

See AppAPI.network_interface_list().

name: str

value: str

class aioqbt.api.TorrentInfo[source]

Obtained from TorrentsAPI.info().

Also see qBittorrent Wiki for attribute meanings.

Note

Some attributes may not be available from older qBittorrent version. AttributeError may raise when accessing these attributes.

Use try-except block or getattr() to handle these cases.

hash: str: Torrent ID (info hash)

infohash_v1: str

infohash_v2: str: infohash_v1 and infohash_v2 are available since v4.4.0

name: str: Torrent name.

magnet_uri: str

size: int

progress: float

dlspeed: int

upspeed: int

priority: int

num_seeds: int

num_complete: int

num_leechs: int

num_incomplete: int

state: str | TorrentState

eta: timedelta

seq_dl: bool

f_l_piece_prio: bool

category: str

tags: List[str]

super_seeding: bool

force_start: bool

save_path: str

download_path: str

content_path: str

added_on: datetime

completion_on: datetime

tracker: str

trackers_count: int

dl_limit: int

up_limit: int

downloaded: int

uploaded: int

downloaded_session: int

uploaded_session: int

amount_left: int

completed: int

max_ratio: float

max_seeding_time: timedelta | None

max_inactive_seeding_time: timedelta | None

ratio: float

ratio_limit: float | RatioLimits

seeding_time_limit: timedelta | int | SeedingTimeLimits

inactive_seeding_time_limit: timedelta | int | InactiveSeedingTimeLimits

seen_complete: datetime

auto_tmm: bool

time_active: timedelta

seeding_time: timedelta

last_activity: datetime

availability: float

total_size: int

class aioqbt.api.TorrentProperties[source]

Obtained from TorrentsAPI.properties().

Note

Some attributes may not be available from older qBittorrent version. AttributeError may raise when accessing these attributes.

Use try-except block or getattr() to handle these cases.

infohash_v1: str

infohash_v2: str: infohash_v1 and infohash_v2 are available since v4.4.0

name: str

hash: str: name and hash are available since v4.5.2

time_elapsed: timedelta

seeding_time: timedelta

eta: timedelta

nb_connections: int

nb_connections_limit: int

total_downloaded: int

total_downloaded_session: int

total_uploaded: int

total_uploaded_session: int

dl_speed: int

dl_speed_avg: int

up_speed: int

up_speed_avg: int

dl_limit: int

up_limit: int

total_wasted: int

seeds: int

seeds_total: int

peers: int

peers_total: int

share_ratio: float

reannounce: timedelta

total_size: int

pieces_num: int

piece_size: int

pieces_have: int

created_by: str

is_private: bool

addition_date: datetime

last_seen: datetime | None

completion_date: datetime | None

creation_date: datetime | None

save_path: str

download_path: str

comment: str

class aioqbt.api.Tracker[source]

See TorrentsAPI.trackers().

url: str

status: int | TrackerStatus

tier: int

num_peers: int

num_seeds: int

num_leeches: int

num_downloaded: int

msg: str

is_special() → bool[source]

class aioqbt.api.WebSeed[source]

See TorrentsAPI.webseeds().

url: str

class aioqbt.api.FileEntry[source]

See TorrentsAPI.files().

name: str

size: int

progress: float

priority: int | FilePriority

piece_range: List[int]

is_seed: bool

availability: float

index: int

class aioqbt.api.Category[source]

See TorrentsAPI.categories().

name: str

savePath: str

class aioqbt.api.LogMessage[source]

See LogAPI.main().

id: int

message: str

timestamp: int

type: int

class aioqbt.api.LogPeer[source]

See LogAPI.peers().

id: int

ip: str

timestamp: int

blocked: bool

reason: str

class aioqbt.api.TransferInfo[source]

See TransferAPI.info().

dl_info_speed: int

dl_info_data: int

up_info_speed: int

up_info_data: int

dl_rate_limit: int

up_rate_limit: int

dht_nodes: int

connection_status: str | ConnectionStatus

class aioqbt.api.SyncMainData[source]

Sync results obtained from SyncAPI.maindata().

rid: int

full_update: bool = False

torrents: Dict[str, SyncTorrentInfo]

torrents_removed: List[str]

categories: Dict[str, SyncCategory]

categories_removed: List[str]

tags: List[str]

tags_removed: List[str]

trackers: Dict[str, List[str]]

trackers_removed: List[str]

server_state: SyncServerState

class aioqbt.api.SyncTorrentInfo[source]

Bases: TypedDict

Dict of torrent info in SyncMainData.torrents.

infohash_v1: str

infohash_v2: str

name: str

size: int

magnet_uri: str

progress: float

dlspeed: int

upspeed: int

priority: int

num_seeds: int

num_complete: int

num_leechs: int

num_incomplete: int

state: str

eta: int

seq_dl: bool

f_l_piece_prio: bool

category: str

tags: str

super_seeding: bool

force_start: bool

save_path: str

download_path: str

content_path: str

added_on: int

completion_on: int

tracker: str

trackers_count: int

dl_limit: int

up_limit: int

downloaded: int

uploaded: int

downloaded_session: int

uploaded_session: int

amount_left: int

completed: int

max_ratio: float

max_seeding_time: int

max_inactive_seeding_time: int

ratio: float

ratio_limit: float

seeding_time_limit: int

inactive_seeding_time_limit: int

seen_complete: int

auto_tmm: bool

time_active: int

seeding_time: int

last_activity: int

availability: float

total_size: int

class aioqbt.api.SyncCategory[source]

Bases: TypedDict

Dict of category properties in SyncMainData.categories.

name: str

savePath: str

class aioqbt.api.SyncServerState[source]

Bases: TypedDict

Dict of qBittorrent status and statistics in SyncMainData.server_state.

connection_status: str | ConnectionStatus

dht_nodes: int

dl_info_data: int

dl_info_speed: int

dl_rate_limit: int

up_info_data: int

up_info_speed: int

up_rate_limit: int

alltime_dl: int

alltime_ul: int

total_wasted_session: int

global_ratio: str

total_peer_connections: int

queueing: bool

use_alt_speed_limits: bool

refresh_interval: int

free_space_on_disk: int

use_subcategories: bool

average_time_queue: int

read_cache_hits: str

read_cache_overload: str

write_cache_overload: str

queued_io_jobs: int

total_buffers_size: int

total_queued_size: int

class aioqbt.api.SyncTorrentPeers[source]

See SyncAPI.torrent_peers().

rid: int

full_update: bool = False

show_flags: bool | None = None

peers: Dict[str, SyncPeer]

class aioqbt.api.SyncPeer[source]

Bases: TypedDict

Dict of peer info in SyncTorrentPeers.peers.

ip: str

port: int

client: str

progress: float

dl_speed: int

up_speed: int

downloaded: int

uploaded: int

connection: str

flags: str

flags_desc: str

relevance: float

files: str

country_code: str

country: str

class aioqbt.api.RSSItem[source]: Base class of RSSFolder and RSSFeed

class aioqbt.api.RSSFeed[source]

RSS feed returned from RSSAPI.items().

Attributes url and uid are always available.

The other attributes are available if with_data=True is passed to RSSAPI.items(). Otherwise, AttributeError raises when accessed.

Use hasattr() to check if doubted.

url: str

uid: str

title: str

lastBuildDate: str

isLoading: bool

hasError: bool

articles: List[RSSArticle]

class aioqbt.api.RSSFolder[source]

RSSFolder is a container in hierarchical tree.

folder
|-- linux
|-- news
|   |-- local
|   |-- world

RSSFolder is a dict-like object that children RSSFeed and RSSFolder are accessed by their names: folder["linux"]. The number of direct children is returned by len(folder) while the names of them by folder.keys().

Further children can be accessed by joining names with backslashes. The following lines are equivalent:

folder["news"]["local"]
folder[r"news\local"]

class aioqbt.api.RSSArticle[source]

RSS article.

id: str

title: str

description: str

date: datetime

link: str

torrentURL: str

class aioqbt.api.RSSRule[source]

Bases: TypedDict

RSS rule configuration dict.

Rule dict is returned from RSSAPI.rules(). It can be passed as argument to RSSAPI.set_rule().

enabled: bool

priority: int

useRegex: bool

mustContain: str

mustNotContain: str

episodeFilter: str

affectedFeeds: List[str]

savePath: str

assignedCategory: str

lastMatch: str

ignoreDays: int

addPaused: bool | None

torrentContentLayout: str | None

smartFilter: bool

previouslyMatchedEpisodes: List[str]

torrentParams: Dict[str, Any]

class aioqbt.api.SearchResultEntry[source]

Search result entry.

fileName: str

fileUrl: str

fileSize: str

nbSeeders: int

nbLeechers: int

siteUrl: str

class aioqbt.api.SearchJobResults[source]

Search job results.

status: str | Literal['Running'] | Literal['Stopped']

results: List[SearchResultEntry]

total: int

class aioqbt.api.SearchJobStart[source]

Result of SearchAPI.start().

id: int

class aioqbt.api.SearchJobStatus[source]

Search job status.

id: int

status: str | Literal['Running'] | Literal['Stopped']

total: int

class aioqbt.api.SearchPlugin[source]

Search plugin information.

enabled: bool

fullName: str

name: str

supportedCategories: List[SearchPluginCategory] | List[str]

A list of supported categories.

In qBittorrent 4.3.x and later, this attribute is a list of SearchPluginCategory; in earlier versions, a list of localized strings.

url: str

version: str

class aioqbt.api.SearchPluginCategory[source]

Category supported by plugin.

id: str

category: str

Utilities

bittorrent

aioqbt.bittorrent.InfoHash

aioqbt.bittorrent.InfoHashes

aioqbt.bittorrent.InfoHashesOrAll

Type hints related to info hash.

InfoHash represents an info hash (str or bytes).
InfoHashes is an iterable of InfoHash.
InfoHashOrAll is an extension to InfoHashes. It allow the string literal all, which specifies all torrents in some API methods.

chrono

aioqbt.chrono.Seconds

aioqbt.chrono.Minutes: Type hints (similar to int) for time durations in specific units.

class aioqbt.chrono.TimeUnit(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

TimeUnit enum.

Conversion helper between time units

NANOSECONDS: TimeUnit

MICROSECONDS: TimeUnit

MILLISECONDS: TimeUnit

SECONDS: TimeUnit

MINUTES: TimeUnit

HOURS: TimeUnit

DAYS: TimeUnit

from_duration(d: float, unit: TimeUnit) → float[source]: Convert value from the given unit to the self unit (float)

from_duration_int(d: int, unit: TimeUnit) → int[source]: Convert value from the given unit to the self unit (int)

from_nanos(d: float) → float[source]: Convert nanoseconds to self unit

from_micros(d: float) → float[source]: Convert microseconds to self unit

from_millis(d: float) → float[source]: Convert milliseconds to self unit

from_seconds(d: float) → float[source]: Convert seconds to self unit

from_minutes(d: float) → float[source]: Convert minutes to self unit

from_hours(d: float) → float[source]: Convert hours to self unit

from_days(d: float) → float[source]: Convert days to self unit

classmethod convert(d: float, src: TimeUnit, dst: TimeUnit) → float[source]: Convert a numeric duration in some unit to one in another.

version

class aioqbt.version.ClientVersion(major: int, minor: int, patch: int, build: int = 0, status: str = '')[source]

Represent client version.

property major: int: Major number.

property minor: int: Minor number.

property patch: int: Patch number.

property build: int: Build number.

property status: str: Status string.

classmethod parse(version: str) → ClientVersion[source]

Parse client version.

Format:

major.minor.patch[.build][status]

Examples:

2.5
4.0beta2
4.3.1

class aioqbt.version.APIVersion(major: int, minor: int, release: int = 0)[source]

Represent API version.

Instances can also be compared with 3-tuple of int.

major: int: Major number.

minor: int: Minor number.

release: int: Release number.

classmethod parse(version: str) → APIVersion[source]

Parse API version.

Format:

major.minor[.release]

where major, minor and release are all digits.

classmethod compare(a: Self | Tuple[int, int, int] | None, b: Self | Tuple[int, int, int] | None) → int[source]

Compare two API versions.

Return zero if a == b; a negative value if a < b; or a positive value if a > b.

None is a special value treated as the latest version.

Returns:: integer value indicating version relationship.

Exceptions

aioqbt.exc

Exceptions raised in aioqbt.

exception aioqbt.exc.AQError[source]

Bases: Exception

Generic error class.

exception aioqbt.exc.MapperError[source]

Bases: AQError

Raised when mapper operations failed.

exception aioqbt.exc.VersionError[source]

Bases: AQError

Version check failed.

exception aioqbt.exc.APIError[source]

Bases: AQError

Base class of API errors.

message: str: Error message or HTTP reason phrase

status: int: HTTP status

resp: ClientResponse | None: The closed response object

classmethod from_response(resp: ClientResponse, message: str = '') → Self[source]: Create an exception instance based on a response.

exception aioqbt.exc.LoginError[source]

Bases: APIError

Login has failed.

This is raised by AuthAPI.login() and HTTP status is 200.

exception aioqbt.exc.AddTorrentError[source]

Bases: APIError

No new torrents were added.

This is raised by TorrentsAPI.add() and HTTP status is 200.

exception aioqbt.exc.BadRequestError[source]

Bases: APIError

Bad request.

The error is usually raised because of missing or invalid parameters. This may be caused by empty value sometimes.

HTTP status is usually 400.

exception aioqbt.exc.ForbiddenError[source]

Bases: APIError

Forbidden.

The request to resources is explicitly denied due to permission.

HTTP status is usually 403.

exception aioqbt.exc.NotFoundError[source]

Bases: APIError

Not found.

It is likely that the API endpoint is misspelled or qBittorrent need an update.

HTTP status is usually 404.

exception aioqbt.exc.ConflictError[source]

Bases: APIError

Conflict.

HTTP status is usually 409.

exception aioqbt.exc.UnsupportedMediaTypeError[source]

Bases: APIError

Unsupported media type.

HTTP status is usually 415.