Client

Client is the class handling the Transmission JSON-RPC client protocol.

Torrent ids

Many functions in Client takes torrent id. You can find torrent-ids spec in official docs

Note

It’s recommended that you use torrent’s info_hash as torrent id. The torrent’s info_hash will never change.

transmission_rpc.from_url(url: str, timeout: float = 30.0, logger: ~logging.Logger = <Logger transmission-rpc (ERROR)>) → Client[source]
from_url("http://127.0.0.1/transmission/rpc")  # http://127.0.0.1:80/transmission/rpc
from_url("https://127.0.0.1/transmission/rpc")  # https://127.0.0.1:443/transmission/rpc
from_url("http://127.0.0.1")  # http://127.0.0.1:80/transmission/rpc
from_url("http://127.0.0.1/")  # http://127.0.0.1:80/

Warning

you can’t ignore scheme, 127.0.0.1:9091 is not valid url, please use http://127.0.0.1:9091

And from_url("http://127.0.0.1") is not same as from_url("http://127.0.0.1/"), path of http://127.0.0.1/ is /

class transmission_rpc.Client[source]
__init__(*, protocol: ~typing.Literal['http', 'https'] = 'http', username: str | None = None, password: str | None = None, host: str = '127.0.0.1', port: int = 9091, path: str = '/transmission/rpc', timeout: float = 30.0, logger: ~logging.Logger = <Logger transmission-rpc (ERROR)>)[source]
Parameters:

  • protocol

  • username

  • password

  • host

  • port

  • path – rpc request target path, default /transmission/rpc

  • timeout

  • logger

property timeout: int | float | Tuple[int | float, int | float] | None[source]

Get current timeout for HTTP queries.

property semver_version: str | None[source]

Get the Transmission daemon RPC version.

Deprecated since version 7.0.5: Use .get_session().rpc_version_semver instead

property rpc_version: int[source]

Get the Transmission daemon RPC version.

Deprecated since version 7.0.5: Use .get_session().rpc_version instead

add_torrent(torrent: BinaryIO | str | bytes | Path, timeout: int | float | Tuple[int | float, int | float] | None = None, *, download_dir: str | None = None, files_unwanted: list[int] | None = None, files_wanted: list[int] | None = None, paused: bool | None = None, peer_limit: int | None = None, priority_high: list[int] | None = None, priority_low: list[int] | None = None, priority_normal: list[int] | None = None, cookies: str | None = None, labels: Iterable[str] | None = None, bandwidth_priority: int | None = None, bandwidthPriority: int | None = None) → Torrent[source]

Add torrent to transfers list. torrent can be:

  • http://, https:// or magnet: URL

  • torrent file-like object in binary mode

  • bytes of torrent content

  • pathlib.Path for local torrent file, will be read and encoded as base64.

Warning

base64 string or file:// protocol URL are not supported in v4.

Parameters:

  • torrent – torrent to add

  • timeout – request timeout

  • bandwidth_priority – Priority for this transfer.

  • bandwidthPriority – Deprecated. Use bandwidth_priority instead.

  • cookies – One or more HTTP cookie(s).

  • download_dir – The directory where the downloaded contents will be saved in.

  • files_unwanted – A list of file id’s that shouldn’t be downloaded.

  • files_wanted – A list of file id’s that should be downloaded.

  • paused – If True, does not start the transfer when added. Magnet url will always start to downloading torrents.

  • peer_limit – Maximum number of peers allowed.

  • priority_high – A list of file id’s that should have high priority.

  • priority_low – A list of file id’s that should have low priority.

  • priority_normal – A list of file id’s that should have normal priority.

  • labels – Array of string labels. Add in rpc 17.

remove_torrent(ids: int | str | List[str | int] | None, delete_data: bool = False, timeout: int | float | Tuple[int | float, int | float] | None = None) → None[source]

remove torrent(s) with provided id(s).

Local data will be removed by transmission daemon if delete_data is set to True.

start_torrent(ids: int | str | List[str | int] | None = None, bypass_queue: bool | None = None, timeout: int | float | Tuple[int | float, int | float] | None = None) → None[source]

Start torrent(s), or all torrents if ids is omitted.

start_torrent_now(ids: int | str | List[str | int] | None = None, timeout: int | float | Tuple[int | float, int | float] | None = None) → None[source]

Start torrent(s), or all torrents if ids is omitted, bypassing the queue.

start_all(bypass_queue: bool = False, timeout: int | float | Tuple[int | float, int | float] | None = None) → None[source]

Start all torrents respecting the queue order

stop_torrent(ids: int | str | List[str | int] | None, timeout: int | float | Tuple[int | float, int | float] | None = None) → None[source]

stop torrent(s) with provided id(s)

verify_torrent(ids: int | str | List[str | int] | None, timeout: int | float | Tuple[int | float, int | float] | None = None) → None[source]

verify torrent(s) with provided id(s)

reannounce_torrent(ids: int | str | List[str | int] | None, timeout: int | float | Tuple[int | float, int | float] | None = None) → None[source]

Reannounce torrent(s) with provided id(s)

get_torrent(torrent_id: int | str, arguments: Iterable[str] | None = None, timeout: int | float | Tuple[int | float, int | float] | None = None) → Torrent[source]

Get information for torrent with provided id. arguments contains a list of field names to be returned, when arguments=None (default), all fields are requested. See the Torrent class for more information.

new argument format in rpc_version 16 is unnecessarily and this lib can’t handle table response, So it’s unsupported.

Returns a Torrent object with the requested fields.

Note

It’s recommended that you only fetch arguments you need, this could improve response speed.

For example, fetch all fields from transmission daemon with 1500 torrents would take ~5s, but is only ~0.2s if to fetch 6 fields.

Parameters:

  • torrent_id – torrent id can be an int or a torrent info_hash (hashString property of the Torrent object).

  • arguments – fetched torrent arguments, in most cases you don’t need to set this, transmission-rpc will fetch all torrent fields it supported.

  • timeout – requests timeout

Raises:

KeyError – torrent with given torrent_id not found

get_torrents(ids: int | str | List[str | int] | None = None, arguments: Iterable[str] | None = None, timeout: int | float | Tuple[int | float, int | float] | None = None) → list[Torrent][source]

Get information for torrents with provided ids. For more information see Client.get_torrent().

Returns a list of Torrent object.

get_recently_active_torrents(arguments: Iterable[str] | None = None, timeout: int | float | Tuple[int | float, int | float] | None = None) → tuple[list[Torrent], list[int]][source]

Get information for torrents for recently active torrent. If you want to get recently-removed torrents. you should use this method.

Returns:

active_torrents, removed_torrents

list of recently active torrents and list of torrent-id of recently-removed torrents.

change_torrent(ids: int | str | List[str | int] | None, timeout: int | float | Tuple[int | float, int | float] | None = None, *, bandwidth_priority: int | None = None, download_limit: int | None = None, download_limited: bool | None = None, upload_limit: int | None = None, upload_limited: bool | None = None, files_unwanted: Iterable[int] | None = None, files_wanted: Iterable[int] | None = None, honors_session_limits: bool | None = None, location: str | None = None, peer_limit: int | None = None, priority_high: Iterable[int] | None = None, priority_low: Iterable[int] | None = None, priority_normal: Iterable[int] | None = None, queue_position: int | None = None, seed_idle_limit: int | None = None, seed_idle_mode: int | None = None, seed_ratio_limit: float | None = None, seed_ratio_mode: int | None = None, tracker_add: Iterable[str] | None = None, labels: Iterable[str] | None = None, group: str | None = None, tracker_list: Iterable[Iterable[str]] | None = None, tracker_replace: Iterable[tuple[int, str]] | None = None, tracker_remove: Iterable[int] | None = None, **kwargs: Any) → None[source]

Change torrent parameters for the torrent(s) with the supplied id’s.

Parameters:

  • ids – torrent(s) to change.

  • timeout – requesst timeout.

  • honors_session_limits – true if session upload limits are honored.

  • location – new location of the torrent’s content

  • peer_limit – maximum number of peers

  • queue_position – position of this torrent in its queue [0…n)

  • files_wanted – Array of file id to download.

  • files_unwanted – Array of file id to not download.

  • download_limit – maximum download speed (KBps)

  • download_limited – true if download_limit is honored

  • upload_limit – maximum upload speed (KBps)

  • upload_limited – true if upload_limit is honored

  • bandwidth_priority – Priority for this transfer.

  • priority_high – list of file id to set high download priority

  • priority_low – list of file id to set low download priority

  • priority_normal – list of file id to set normal download priority

  • seed_ratio_limit – Seed inactivity limit in minutes.

  • seed_ratio_mode – Torrent seed ratio mode Valid options are transmission_rpc.RatioLimitMode

  • seed_idle_limit – torrent-level seeding ratio

  • seed_idle_mode – Seed inactivity mode. Valid options are transmission_rpc.IdleMode

  • labels – Array of string labels. Add in rpc 16.

  • group – The name of this torrent’s bandwidth group. Add in rpc 17.

  • tracker_list –

    A Iterable[Iterable[str]], each Iterable[str] for a tracker tier.

    Add in rpc 17.

    Example: [['https://tracker1/announce', 'https://tracker2/announce'], ['https://backup1.example.com/announce'], ['https://backup2.example.com/announce']].

  • tracker_add –

    Array of string with announce URLs to add.

    Warning

    since transmission daemon 4.0.0, this argument is deprecated, use tracker_list instead.

  • tracker_remove –

    Array of ids of trackers to remove.

    Warning

    since transmission daemon 4.0.0, this argument is deprecated, use tracker_list instead.

  • tracker_replace –

    Array of (id, url) tuples where the announcement URL should be replaced.

    Warning

    since transmission daemon 4.0.0, this argument is deprecated, use tracker_list instead.

Warning

kwargs is for the future features not supported yet, it’s not compatibility promising. It will be bypassed to request arguments as-is, the underline in the key will not be replaced, so you should use kwargs like {'a-argument': 'value'}

move_torrent_data(ids: int | str | List[str | int] | None, location: str | Path, timeout: int | float | Tuple[int | float, int | float] | None = None, *, move: bool = True) → None[source]

Move torrent data to the new location.

See also

RPC Spec: moving-a-torrent

rename_torrent_path(torrent_id: int | str, location: str, name: str, timeout: int | float | Tuple[int | float, int | float] | None = None) → tuple[str, str][source]

Warning

This method can only be called on single torrent.

Warning

This is not the method to move torrent data directory,

See also

RPC Spec: renaming-a-torrents-path

queue_top(ids: int | str | List[str | int] | None, timeout: int | float | Tuple[int | float, int | float] | None = None) → None[source]

Move transfer to the top of the queue.

https://github.com/transmission/transmission/blob/main/docs/rpc-spec.md#46-queue-movement-requests

queue_bottom(ids: int | str | List[str | int] | None, timeout: int | float | Tuple[int | float, int | float] | None = None) → None[source]

Move transfer to the bottom of the queue.

https://github.com/transmission/transmission/blob/main/docs/rpc-spec.md#46-queue-movement-requests

queue_up(ids: int | str | List[str | int] | None, timeout: int | float | Tuple[int | float, int | float] | None = None) → None[source]

Move transfer up in the queue.

queue_down(ids: int | str | List[str | int] | None, timeout: int | float | Tuple[int | float, int | float] | None = None) → None[source]

Move transfer down in the queue.

get_session(timeout: int | float | Tuple[int | float, int | float] | None = None) → Session[source]

Get session parameters. See the Session class for more information.

set_session(timeout: int | float | Tuple[int | float, int | float] | None = None, *, alt_speed_down: int | None = None, alt_speed_enabled: bool | None = None, alt_speed_time_begin: int | None = None, alt_speed_time_day: int | None = None, alt_speed_time_enabled: bool | None = None, alt_speed_time_end: int | None = None, alt_speed_up: int | None = None, blocklist_enabled: bool | None = None, blocklist_url: str | None = None, cache_size_mib: int | None = None, cache_size_mb: int | None = None, dht_enabled: bool | None = None, default_trackers: Iterable[str] | None = None, download_dir: str | None = None, download_queue_enabled: bool | None = None, download_queue_size: int | None = None, encryption: Literal['required', 'preferred', 'tolerated'] | None = None, idle_seeding_limit: int | None = None, idle_seeding_limit_enabled: bool | None = None, incomplete_dir: str | None = None, incomplete_dir_enabled: bool | None = None, lpd_enabled: bool | None = None, peer_limit_global: int | None = None, peer_limit_per_torrent: int | None = None, peer_port: int | None = None, peer_port_random_on_start: bool | None = None, pex_enabled: bool | None = None, port_forwarding_enabled: bool | None = None, queue_stalled_enabled: bool | None = None, queue_stalled_minutes: int | None = None, rename_partial_files: bool | None = None, script_torrent_done_enabled: bool | None = None, script_torrent_done_filename: str | None = None, seed_queue_enabled: bool | None = None, seed_queue_size: int | None = None, seed_ratio_limit: float | None = None, seed_ratio_limited: bool | None = None, speed_limit_down: int | None = None, speed_limit_down_enabled: bool | None = None, speed_limit_up: int | None = None, speed_limit_up_enabled: bool | None = None, start_added_torrents: bool | None = None, trash_original_torrent_files: bool | None = None, utp_enabled: bool | None = None, script_torrent_done_seeding_filename: str | None = None, script_torrent_done_seeding_enabled: bool | None = None, script_torrent_added_enabled: bool | None = None, script_torrent_added_filename: str | None = None, **kwargs: Any) → None[source]

Set session parameters.

Parameters:

  • timeout – request timeout

  • alt_speed_down – max global download speed (KBps)

  • alt_speed_enabled – true means use the alt speeds

  • alt_speed_time_begin – Time when alternate speeds should be enabled. Minutes after midnight.

  • alt_speed_time_day – Enables alternate speeds scheduling these days.

  • alt_speed_time_enabled – Enables alternate speeds scheduling.

  • alt_speed_time_end – Time when alternate speeds should be disabled. Minutes after midnight.

  • alt_speed_up – Alternate session upload speed limit (in Kib/s).

  • blocklist_enabled – Enables the block list

  • blocklist_url – Location of the block list. Updated with blocklist-update.

  • cache_size_mib – The maximum size of the disk cache in MiB.

  • cache_size_mb – Deprecated. Use cache_size_mib instead.

  • default_trackers – list of default trackers to use on public torrents.

  • dht_enabled – Enables DHT.

  • download_dir – Set the session download directory.

  • download_queue_enabled – Enables download queue.

  • download_queue_size – Number of slots in the download queue.

  • encryption – Set the session encryption mode, one of required, preferred or tolerated.

  • idle_seeding_limit – The default seed inactivity limit in minutes.

  • idle_seeding_limit_enabled – Enables the default seed inactivity limit

  • incomplete_dir – The path to the directory of incomplete transfer data.

  • incomplete_dir_enabled – Enables the incomplete transfer data directory, Otherwise data for incomplete transfers are stored in the download target.

  • lpd_enabled – Enables local peer discovery for public torrents.

  • peer_limit_global – Maximum number of peers.

  • peer_limit_per_torrent – Maximum number of peers per transfer.

  • peer_port – Peer port.

  • peer_port_random_on_start – Enables randomized peer port on start of Transmission.

  • pex_enabled – Allowing PEX in public torrents.

  • port_forwarding_enabled – Enables port forwarding.

  • queue_stalled_enabled – Enable tracking of stalled transfers.

  • queue_stalled_minutes – Number of minutes of idle that marks a transfer as stalled.

  • rename_partial_files – Appends “.part” to incomplete files

  • seed_queue_enabled – Enables upload queue.

  • seed_queue_size – Number of slots in the upload queue.

  • seed_ratio_limit – Seed ratio limit. 1.0 means 1:1 download and upload ratio.

  • seed_ratio_limited – Enables seed ration limit.

  • speed_limit_down – Download speed limit (in Kib/s).

  • speed_limit_down_enabled – Enables download speed limiting.

  • speed_limit_up – Upload speed limit (in Kib/s).

  • speed_limit_up_enabled – Enables upload speed limiting.

  • start_added_torrents – Added torrents will be started right away.

  • trash_original_torrent_files – The .torrent file of added torrents will be deleted.

  • utp_enabled – Enables Micro Transport Protocol (UTP).

  • script_torrent_done_enabled – Whether to call the “done” script.

  • script_torrent_done_filename – Filename of the script to run when the transfer is done.

  • script_torrent_added_filename – filename of the script to run

  • script_torrent_added_enabled – whether or not to call the added script

  • script_torrent_done_seeding_enabled – whether or not to call the seeding-done script

  • script_torrent_done_seeding_filename – filename of the script to run

Warning

kwargs is pass the arguments not supported yet future, it’s not compatibility promising. transmission-rpc will merge kwargs in rpc arguments as-is

blocklist_update(timeout: int | float | Tuple[int | float, int | float] | None = None) → int | None[source]

Update block list. Returns the size of the block list.

port_test(timeout: int | float | Tuple[int | float, int | float] | None = None) → bool | None[source]

Tests to see if your incoming peer port is accessible from the outside world.

free_space(path: str | Path, timeout: int | float | Tuple[int | float, int | float] | None = None) → int | None[source]

Get the amount of free space (in bytes) at the provided location.

session_stats(timeout: int | float | Tuple[int | float, int | float] | None = None) → SessionStats[source]

Get session statistics

set_group(name: str, *, timeout: int | float | Tuple[int | float, int | float] | None = None, honors_session_limits: bool | None = None, speed_limit_down_enabled: bool | None = None, speed_limit_down: int | None = None, speed_limit_up_enabled: bool | None = None, speed_limit_up: int | None = None) → None[source]

create or update a Bandwidth group.

Parameters:

  • name – Bandwidth group name

  • honors_session_limits – true if session upload limits are honored

  • speed_limit_down_enabled – true means enabled

  • speed_limit_down – max global download speed (KBps)

  • speed_limit_up_enabled – true means enabled

  • speed_limit_up – max global upload speed (KBps)

  • timeout – request timeout

Timeouts

Since most methods results in HTTP requests against Transmission, it is possible to provide a argument called timeout. Default timeout is 30 seconds.