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

transmission_rpc.from_url(url, timeout=30.0, logger=<Logger transmission-rpc (ERROR)>)[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 /

Parameters:

  • url (str) –

  • timeout (int | float) –

  • logger (Logger) –

Return type:

Client

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

  • protocol (Literal['http', 'https']) –

  • username (str | None) –

  • password (str | None) –

  • host (str) –

  • port (int) –

  • path (str) –

  • timeout (int | float) –

  • logger (Logger) –

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

Get current timeout for HTTP queries.

property rpc_version: int

Get the Transmission RPC version. Trying to deduct if the server don’t have a version value.

add_torrent(torrent, timeout=None, *, download_dir=None, files_unwanted=None, files_wanted=None, paused=None, peer_limit=None, priority_high=None, priority_low=None, priority_normal=None, cookies=None, labels=None, bandwidthPriority=None)[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 (BinaryIO | str | bytes | Path) – torrent to add

  • timeout (int | float | Tuple[int | float, int | float] | None) – request timeout

  • labels (Iterable[str] | None) – Array of string labels. Add in rpc 17.

  • bandwidthPriority (int | None) – Priority for this transfer.

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

  • download_dir (str | None) – The directory where the downloaded contents will be saved in.

  • files_unwanted (List[int] | None) – A list of file id’s that shouldn’t be downloaded.

  • files_wanted (List[int] | None) – A list of file id’s that should be downloaded.

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

  • peer_limit (int | None) – Maximum number of peers allowed.

  • priority_high (List[int] | None) – A list of file id’s that should have high priority.

  • priority_low (List[int] | None) – A list of file id’s that should have low priority.

  • priority_normal (List[int] | None) – A list of file id’s that should have normal priority.

Return type:

Torrent

remove_torrent(ids, delete_data=False, timeout=None)[source]

remove torrent(s) with provided id(s). Local data is removed if delete_data is True, otherwise not.

Parameters:

  • ids (int | str | List[str | int] | None) –

  • delete_data (bool) –

  • timeout (int | float | Tuple[int | float, int | float] | None) –

Return type:

None

start_torrent(ids, bypass_queue=False, timeout=None)[source]

Start torrent(s) with provided id(s)

Parameters:

  • ids (int | str | List[str | int] | None) –

  • bypass_queue (bool) –

  • timeout (int | float | Tuple[int | float, int | float] | None) –

Return type:

None

start_all(bypass_queue=False, timeout=None)[source]

Start all torrents respecting the queue order

Parameters:

  • bypass_queue (bool) –

  • timeout (int | float | Tuple[int | float, int | float] | None) –

Return type:

None

stop_torrent(ids, timeout=None)[source]

stop torrent(s) with provided id(s)

Parameters:

  • ids (int | str | List[str | int] | None) –

  • timeout (int | float | Tuple[int | float, int | float] | None) –

Return type:

None

verify_torrent(ids, timeout=None)[source]

verify torrent(s) with provided id(s)

Parameters:

  • ids (int | str | List[str | int] | None) –

  • timeout (int | float | Tuple[int | float, int | float] | None) –

Return type:

None

reannounce_torrent(ids, timeout=None)[source]

Reannounce torrent(s) with provided id(s)

Parameters:

  • ids (int | str | List[str | int] | None) –

  • timeout (int | float | Tuple[int | float, int | float] | None) –

Return type:

None

get_torrent(torrent_id, arguments=None, timeout=None)[source]

Get information for torrent with provided id. arguments contains a list of field names to be returned, when None 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 use torrent’s info_hash as torrent id. torrent’s info_hash will never change.

Parameters:

  • torrent_id (int | str) – torrent id can be an int or a torrent info_hash (hash_string of torrent object).

  • arguments (Iterable[str] | None) – fetched torrent arguments, in most cases you don’t need to set this, transmission-rpc will fetch all torrent fields it supported.

  • timeout (int | float | Tuple[int | float, int | float] | None) – requests timeout

Return type:

Torrent

get_torrents(ids=None, arguments=None, timeout=None)[source]

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

Returns a list of Torrent object.

Parameters:

  • ids (int | str | List[str | int] | None) –

  • arguments (Iterable[str] | None) –

  • timeout (int | float | Tuple[int | float, int | float] | None) –

Return type:

List[Torrent]

get_recently_active_torrents(arguments=None, timeout=None)[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 (List[Torrent]) – List of recently active torrents

  • removed_torrents (List[int]) – List of torrent-id of recently-removed torrents.

Parameters:

  • arguments (Iterable[str] | None) –

  • timeout (int | float | Tuple[int | float, int | float] | None) –

Return type:

Tuple[List[Torrent], List[int]]

change_torrent(ids, timeout=None, *, bandwidth_priority=None, download_limit=None, download_limited=None, upload_limit=None, upload_limited=None, files_unwanted=None, files_wanted=None, honors_session_limits=None, location=None, peer_limit=None, priority_high=None, priority_low=None, priority_normal=None, queue_position=None, seed_idle_limit=None, seed_idle_mode=None, seed_ratio_limit=None, seed_ratio_mode=None, tracker_add=None, tracker_remove=None, tracker_replace=None, labels=None, group=None, tracker_list=None, **kwargs)[source]

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

Parameters:

  • ids (int | str | List[str | int] | None) – torrent(s) to change.

  • timeout (int | float | Tuple[int | float, int | float] | None) – requesst timeout.

  • honors_session_limits (bool | None) – true if session upload limits are honored.

  • location (str | None) – new location of the torrent’s content

  • peer_limit (int | None) – maximum number of peers

  • queue_position (int | None) – position of this torrent in its queue [0…n)

  • files_wanted (Iterable[int] | None) – Array of file id to download.

  • files_unwanted (Iterable[int] | None) – Array of file id to not download.

  • download_limit (int | None) – maximum download speed (KBps)

  • download_limited (bool | None) – true if download_limit is honored

  • upload_limit (int | None) – maximum upload speed (KBps)

  • upload_limited (bool | None) – true if upload_limit is honored

  • bandwidth_priority (int | None) – Priority for this transfer.

  • priority_high (Iterable[int] | None) – list of file id to set high download priority

  • priority_low (Iterable[int] | None) – list of file id to set low download priority

  • priority_normal (Iterable[int] | None) – list of file id to set normal download priority

  • seed_ratio_limit (float | None) – Seed inactivity limit in minutes.

  • seed_ratio_mode (int | None) –

    Which ratio to use.

    0 = Use session limit

    1 = Use transfer limit

    2 = Disable limit.

  • seed_idle_limit (int | None) – torrent-level seeding ratio

  • seed_idle_mode (int | None) –

    Seed inactivity mode.

    0 = Use session limit

    1 = Use transfer limit

    2 = Disable limit.

  • tracker_add (Iterable[str] | None) – Array of string with announce URLs to add.

  • tracker_remove (Iterable[int] | None) – Array of ids of trackers to remove.

  • tracker_replace (Iterable[Tuple[int, str]] | None) – Array of (id, url) tuples where the announce URL should be replaced.

  • labels (Iterable[str] | None) – Array of string labels. Add in rpc 16.

  • group (str | None) – The name of this torrent’s bandwidth group. Add in rpc 17.

  • tracker_list (Iterable[Iterable[str]] | None) – A Iterable[Iterable[str]], each Iterable[str] for a tracker tier. Add in rpc 17.

  • kwargs (Any) –

Return type:

None

Warning

kwargs is for the future features not supported yet, it’s not compatibility promising.

it will be bypassed to request arguments.

move_torrent_data(ids, location, timeout=None)[source]

Move torrent data to the new location.

Parameters:

  • ids (int | str | List[str | int] | None) –

  • location (str | Path) –

  • timeout (int | float | Tuple[int | float, int | float] | None) –

Return type:

None

locate_torrent_data(ids, location, timeout=None)[source]

Locate torrent data at the provided location.

Parameters:

  • ids (int | str | List[str | int] | None) –

  • location (str | Path) –

  • timeout (int | float | Tuple[int | float, int | float] | None) –

Return type:

None

rename_torrent_path(torrent_id, location, name, timeout=None)[source]

https://github.com/transmission/transmission/blob/main/docs/rpc-spec.md#37-renaming-a-torrents-path

This method can only be called on single torrent.

Parameters:

  • torrent_id (int | str) –

  • location (str | Path) –

  • name (str) –

  • timeout (int | float | Tuple[int | float, int | float] | None) –

Return type:

Tuple[str, str]

queue_top(ids, timeout=None)[source]

Move transfer to the top of the queue:_Timeout.

Parameters:

  • ids (int | str | List[str | int] | None) –

  • timeout (int | float | Tuple[int | float, int | float] | None) –

Return type:

None

queue_bottom(ids, timeout=None)[source]

Move transfer to the bottom of the queue.

Parameters:

  • ids (int | str | List[str | int] | None) –

  • timeout (int | float | Tuple[int | float, int | float] | None) –

Return type:

None

queue_up(ids, timeout=None)[source]

Move transfer up in the queue.

Parameters:

  • ids (int | str | List[str | int] | None) –

  • timeout (int | float | Tuple[int | float, int | float] | None) –

Return type:

None

queue_down(ids, timeout=None)[source]

Move transfer down in the queue.

Parameters:

  • ids (int | str | List[str | int] | None) –

  • timeout (int | float | Tuple[int | float, int | float] | None) –

Return type:

None

get_session(timeout=None)[source]

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

Parameters:

timeout (int | float | Tuple[int | float, int | float] | None) –

Return type:

Session

set_session(timeout=None, *, alt_speed_down=None, alt_speed_enabled=None, alt_speed_time_begin=None, alt_speed_time_day=None, alt_speed_time_enabled=None, alt_speed_time_end=None, alt_speed_up=None, blocklist_enabled=None, blocklist_url=None, cache_size_mb=None, dht_enabled=None, default_trackers=None, download_dir=None, download_queue_enabled=None, download_queue_size=None, encryption=None, idle_seeding_limit=None, idle_seeding_limit_enabled=None, incomplete_dir=None, incomplete_dir_enabled=None, lpd_enabled=None, peer_limit_global=None, peer_limit_per_torrent=None, peer_port=None, peer_port_random_on_start=None, pex_enabled=None, port_forwarding_enabled=None, queue_stalled_enabled=None, queue_stalled_minutes=None, rename_partial_files=None, script_torrent_done_enabled=None, script_torrent_done_filename=None, seed_queue_enabled=None, seed_queue_size=None, seed_ratio_limit=None, seed_ratio_limited=None, speed_limit_down=None, speed_limit_down_enabled=None, speed_limit_up=None, speed_limit_up_enabled=None, start_added_torrents=None, trash_original_torrent_files=None, utp_enabled=None, script_torrent_done_seeding_filename=None, script_torrent_done_seeding_enabled=None, script_torrent_added_enabled=None, script_torrent_added_filename=None, **kwargs)[source]

Set session parameters.

Parameters:

  • timeout (int | float | Tuple[int | float, int | float] | None) – request timeout

  • alt_speed_down (int | None) – max global download speed (KBps)

  • alt_speed_enabled (bool | None) – true means use the alt speeds

  • alt_speed_time_begin (int | None) – Time when alternate speeds should be enabled. Minutes after midnight.

  • alt_speed_time_day (int | None) – Enables alternate speeds scheduling these days.

  • alt_speed_time_enabled (bool | None) – Enables alternate speeds scheduling.

  • alt_speed_time_end (int | None) – Time when alternate speeds should be disabled. Minutes after midnight.

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

  • blocklist_enabled (bool | None) – Enables the block list

  • blocklist_url (str | None) – Location of the block list. Updated with blocklist-update.

  • cache_size_mb (int | None) – The maximum size of the disk cache in MB

  • default_trackers (Iterable[str] | None) – List of default trackers to use on public torrents.

  • dht_enabled (bool | None) – Enables DHT.

  • download_dir (str | None) – Set the session download directory.

  • download_queue_enabled (bool | None) – Enables download queue.

  • download_queue_size (int | None) – Number of slots in the download queue.

  • encryption (Literal['required', 'preferred', 'tolerated'] | None) – Set the session encryption mode, one of required, preferred or tolerated.

  • idle_seeding_limit (int | None) – The default seed inactivity limit in minutes.

  • idle_seeding_limit_enabled (bool | None) – Enables the default seed inactivity limit

  • incomplete_dir (str | None) – The path to the directory of incomplete transfer data.

  • incomplete_dir_enabled (bool | None) – Enables the incomplete transfer data directory, Otherwise data for incomplete transfers are stored in the download target.

  • lpd_enabled (bool | None) – Enables local peer discovery for public torrents.

  • peer_limit_global (int | None) – Maximum number of peers.

  • peer_limit_per_torrent (int | None) – Maximum number of peers per transfer.

  • peer_port (int | None) – Peer port.

  • peer_port_random_on_start (bool | None) – Enables randomized peer port on start of Transmission.

  • pex_enabled (bool | None) – Allowing PEX in public torrents.

  • port_forwarding_enabled (bool | None) – Enables port forwarding.

  • queue_stalled_enabled (bool | None) – Enable tracking of stalled transfers.

  • queue_stalled_minutes (int | None) – Number of minutes of idle that marks a transfer as stalled.

  • rename_partial_files (bool | None) – Appends “.part” to incomplete files

  • seed_queue_enabled (bool | None) – Enables upload queue.

  • seed_queue_size (int | None) – Number of slots in the upload queue.

  • seed_ratio_limit (int | None) – Seed ratio limit. 1.0 means 1:1 download and upload ratio.

  • seed_ratio_limited (bool | None) – Enables seed ration limit.

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

  • speed_limit_down_enabled (bool | None) – Enables download speed limiting.

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

  • speed_limit_up_enabled (bool | None) – Enables upload speed limiting.

  • start_added_torrents (bool | None) – Added torrents will be started right away.

  • trash_original_torrent_files (bool | None) – The .torrent file of added torrents will be deleted.

  • utp_enabled (bool | None) – Enables Micro Transport Protocol (UTP).

  • script_torrent_done_enabled (bool | None) – Whether to call the “done” script.

  • script_torrent_done_filename (str | None) – Filename of the script to run when the transfer is done.

  • script_torrent_added_filename (str | None) – filename of the script to run

  • script_torrent_added_enabled (bool | None) – whether or not to call the added script

  • script_torrent_done_seeding_enabled (bool | None) – whether or not to call the seeding-done script

  • script_torrent_done_seeding_filename (str | None) – filename of the script to run

  • kwargs (Any) –

Return type:

None

Warning

kwargs is for the future features not supported yet, it’s not compatibility promising.

it will be bypassed to request arguments.

blocklist_update(timeout=None)[source]

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

Parameters:

timeout (int | float | Tuple[int | float, int | float] | None) –

Return type:

int | None

port_test(timeout=None)[source]

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

Parameters:

timeout (int | float | Tuple[int | float, int | float] | None) –

Return type:

bool | None

free_space(path, timeout=None)[source]

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

Parameters:

  • path (str | Path) –

  • timeout (int | float | Tuple[int | float, int | float] | None) –

Return type:

int | None

session_stats(timeout=None)[source]

Get session statistics

Parameters:

timeout (int | float | Tuple[int | float, int | float] | None) –

Return type:

SessionStats

Timeouts

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