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

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

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

  • username (Optional[str]) –

  • password (Optional[str]) –

  • host (str) –

  • port (int) –

  • path (str) –

  • timeout (Union[int, float]) –

  • logger (Logger) –

property timeout: Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]]

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 (Union[BinaryIO, str, bytes, Path]) – torrent to add

  • timeout (Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]]) – request timeout

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

  • bandwidthPriority (Optional[int]) – Priority for this transfer.

  • cookies (Optional[str]) – One or more HTTP cookie(s).

  • download_dir (Optional[str]) – The directory where the downloaded contents will be saved in.

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

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

  • paused (Optional[bool]) – If True, does not start the transfer when added.

  • peer_limit (Optional[int]) – Maximum number of peers allowed.

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

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

  • priority_normal (Optional[List[int]]) – 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 (Optional[Union[int, str, List[Union[int, str]]]]) –

  • delete_data (bool) –

  • timeout (Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]]) –

Return type

None

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

Start torrent(s) with provided id(s)

Parameters

  • ids (Optional[Union[int, str, List[Union[int, str]]]]) –

  • bypass_queue (bool) –

  • timeout (Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]]) –

Return type

None

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

Start all torrents respecting the queue order

Parameters

  • bypass_queue (bool) –

  • timeout (Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]]) –

Return type

None

stop_torrent(ids, timeout=None)[source]

stop torrent(s) with provided id(s)

Parameters

  • ids (Optional[Union[int, str, List[Union[int, str]]]]) –

  • timeout (Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]]) –

Return type

None

verify_torrent(ids, timeout=None)[source]

verify torrent(s) with provided id(s)

Parameters

  • ids (Optional[Union[int, str, List[Union[int, str]]]]) –

  • timeout (Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]]) –

Return type

None

reannounce_torrent(ids, timeout=None)[source]

Reannounce torrent(s) with provided id(s)

Parameters

  • ids (Optional[Union[int, str, List[Union[int, str]]]]) –

  • timeout (Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]]) –

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 (Union[int, str]) – torrent id can be an int or a torrent info_hash (hash_string of torrent object).

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

  • timeout (Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]]) – 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 (Optional[Union[int, str, List[Union[int, str]]]]) –

  • arguments (Optional[Iterable[str]]) –

  • timeout (Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]]) –

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 (Optional[Iterable[str]]) –

  • timeout (Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]]) –

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 (Optional[Union[int, str, List[Union[int, str]]]]) – torrent(s) to change.

  • timeout (Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]]) – requesst timeout.

  • honors_session_limits (Optional[bool]) – true if session upload limits are honored.

  • location (Optional[str]) – new location of the torrent’s content

  • peer_limit (Optional[int]) – maximum number of peers

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

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

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

  • download_limit (Optional[int]) – maximum download speed (KBps)

  • download_limited (Optional[bool]) – true if download_limit is honored

  • upload_limit (Optional[int]) – maximum upload speed (KBps)

  • upload_limited (Optional[bool]) – true if upload_limit is honored

  • bandwidth_priority (Optional[int]) – Priority for this transfer.

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

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

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

  • seed_ratio_limit (Optional[float]) – Seed inactivity limit in minutes.

  • seed_ratio_mode (Optional[int]) –

    Which ratio to use.

    0 = Use session limit

    1 = Use transfer limit

    2 = Disable limit.

  • seed_idle_limit (Optional[int]) – torrent-level seeding ratio

  • seed_idle_mode (Optional[int]) –

    Seed inactivity mode.

    0 = Use session limit

    1 = Use transfer limit

    2 = Disable limit.

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

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

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

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

  • group (Optional[str]) – The name of this torrent’s bandwidth group. Add in rpc 17.

  • tracker_list (Optional[Iterable[Iterable[str]]]) – 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 (Optional[Union[int, str, List[Union[int, str]]]]) –

  • location (Union[str, Path]) –

  • timeout (Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]]) –

Return type

None

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

Locate torrent data at the provided location.

Parameters

  • ids (Optional[Union[int, str, List[Union[int, str]]]]) –

  • location (Union[str, Path]) –

  • timeout (Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]]) –

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 (Union[int, str]) –

  • location (Union[str, Path]) –

  • name (str) –

  • timeout (Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]]) –

Return type

Tuple[str, str]

queue_top(ids, timeout=None)[source]

Move transfer to the top of the queue:_Timeout.

Parameters

  • ids (Optional[Union[int, str, List[Union[int, str]]]]) –

  • timeout (Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]]) –

Return type

None

queue_bottom(ids, timeout=None)[source]

Move transfer to the bottom of the queue.

Parameters

  • ids (Optional[Union[int, str, List[Union[int, str]]]]) –

  • timeout (Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]]) –

Return type

None

queue_up(ids, timeout=None)[source]

Move transfer up in the queue.

Parameters

  • ids (Optional[Union[int, str, List[Union[int, str]]]]) –

  • timeout (Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]]) –

Return type

None

queue_down(ids, timeout=None)[source]

Move transfer down in the queue.

Parameters

  • ids (Optional[Union[int, str, List[Union[int, str]]]]) –

  • timeout (Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]]) –

Return type

None

get_session(timeout=None)[source]

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

Parameters

timeout (Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]]) –

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, 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 (Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]]) – request timeout

  • alt_speed_down (Optional[int]) – max global download speed (KBps)

  • alt_speed_enabled (Optional[bool]) – true means use the alt speeds

  • alt_speed_time_begin (Optional[int]) – Time when alternate speeds should be enabled. Minutes after midnight.

  • alt_speed_time_day (Optional[int]) – Enables alternate speeds scheduling these days.

  • alt_speed_time_enabled (Optional[bool]) – Enables alternate speeds scheduling.

  • alt_speed_time_end (Optional[int]) – Time when alternate speeds should be disabled. Minutes after midnight.

  • alt_speed_up (Optional[int]) – Alternate session upload speed limit (in Kib/s).

  • blocklist_enabled (Optional[bool]) – Enables the block list

  • blocklist_url (Optional[str]) – Location of the block list. Updated with blocklist-update.

  • cache_size_mb (Optional[int]) – The maximum size of the disk cache in MB

  • dht_enabled (Optional[bool]) – Enables DHT.

  • download_dir (Optional[str]) – Set the session download directory.

  • download_queue_enabled (Optional[bool]) – Enables download queue.

  • download_queue_size (Optional[int]) – Number of slots in the download queue.

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

  • idle_seeding_limit (Optional[int]) – The default seed inactivity limit in minutes.

  • idle_seeding_limit_enabled (Optional[bool]) – Enables the default seed inactivity limit

  • incomplete_dir (Optional[str]) – The path to the directory of incomplete transfer data.

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

  • lpd_enabled (Optional[bool]) – Enables local peer discovery for public torrents.

  • peer_limit_global (Optional[int]) – Maximum number of peers.

  • peer_limit_per_torrent (Optional[int]) – Maximum number of peers per transfer.

  • peer_port (Optional[int]) – Peer port.

  • peer_port_random_on_start (Optional[bool]) – Enables randomized peer port on start of Transmission.

  • pex_enabled (Optional[bool]) – Allowing PEX in public torrents.

  • port_forwarding_enabled (Optional[bool]) – Enables port forwarding.

  • queue_stalled_enabled (Optional[bool]) – Enable tracking of stalled transfers.

  • queue_stalled_minutes (Optional[int]) – Number of minutes of idle that marks a transfer as stalled.

  • rename_partial_files (Optional[bool]) – Appends “.part” to incomplete files

  • seed_queue_enabled (Optional[bool]) – Enables upload queue.

  • seed_queue_size (Optional[int]) – Number of slots in the upload queue.

  • seed_ratio_limit (Optional[int]) – Seed ratio limit. 1.0 means 1:1 download and upload ratio.

  • seed_ratio_limited (Optional[bool]) – Enables seed ration limit.

  • speed_limit_down (Optional[int]) – Download speed limit (in Kib/s).

  • speed_limit_down_enabled (Optional[bool]) – Enables download speed limiting.

  • speed_limit_up (Optional[int]) – Upload speed limit (in Kib/s).

  • speed_limit_up_enabled (Optional[bool]) – Enables upload speed limiting.

  • start_added_torrents (Optional[bool]) – Added torrents will be started right away.

  • trash_original_torrent_files (Optional[bool]) – The .torrent file of added torrents will be deleted.

  • utp_enabled (Optional[bool]) – Enables Micro Transport Protocol (UTP).

  • script_torrent_done_enabled (Optional[bool]) – Whether to call the “done” script.

  • script_torrent_done_filename (Optional[str]) – Filename of the script to run when the transfer is done.

  • script_torrent_added_filename (Optional[str]) – filename of the script to run

  • script_torrent_added_enabled (Optional[bool]) – whether or not to call the added script

  • script_torrent_done_seeding_enabled (Optional[bool]) – whether or not to call the seeding-done script

  • script_torrent_done_seeding_filename (Optional[str]) – 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 (Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]]) –

Return type

Optional[int]

port_test(timeout=None)[source]

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

Parameters

timeout (Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]]) –

Return type

Optional[bool]

free_space(path, timeout=None)[source]

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

Parameters

  • path (Union[str, Path]) –

  • timeout (Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]]) –

Return type

Optional[int]

session_stats(timeout=None)[source]

Get session statistics

Parameters

timeout (Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]]) –

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.