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

Timeouts

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

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 (typing_extensions.Literal[http, https]) –
username (Optional[str]) –
password (Optional[str]) –
host (str) –
port (int) –
path (str) –
timeout (Union[int, float]) –
logger (logging.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, 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
str of base64 encoded torrent file content
file:// URL, deprecated

Note

url starts with file:// will be load by this package instead of transmission daemon

Additional arguments are:

Argument	RPC	Description
`bandwidthPriority`	8 -	Priority for this transfer.
`cookies`	13 -	One or more HTTP cookie(s).
`download_dir`	1 -	The directory where the downloaded contents will be saved in.
`files_unwanted`	1 -	A list of file id’s that shouldn’t be downloaded.
`files_wanted`	1 -	A list of file id’s that should be downloaded.
`paused`	1 -	If True, does not start the transfer when added.
`peer_limit`	1 -	Maximum number of peers allowed.
`priority_high`	1 -	A list of file id’s that should have high priority.
`priority_low`	1 -	A list of file id’s that should have low priority.
`priority_normal`	1 -	A list of file id’s that should have normal priority.

Returns a Torrent object with the fields.

Parameters

torrent (Union[BinaryIO, str, bytes]) –
timeout (Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]]) –
download_dir (Optional[str]) –
files_unwanted (Optional[List[int]]) –
files_wanted (Optional[List[int]]) –
paused (Optional[bool]) –
peer_limit (Optional[int]) –
priority_high (Optional[List[int]]) –
priority_low (Optional[List[int]]) –
priority_normal (Optional[List[int]]) –
cookies (Optional[str]) –
bandwidthPriority (Optional[int]) –

Return type

transmission_rpc.torrent.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[str, int, 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[str, int, 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[str, int, 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[str, int, 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[str, int, 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.

Parameters

torrent_id (Union[int, str]) –
arguments (Optional[Sequence[str]]) –
timeout (Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]]) –

Return type

transmission_rpc.torrent.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[str, int, List[Union[int, str]]]]) –
arguments (Optional[Sequence[str]]) –
timeout (Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]]) –

Return type

List[transmission_rpc.torrent.Torrent]

get_files(ids=None, timeout=None)[source]

Get list of files for provided torrent id(s). If ids is empty, information for all torrents are fetched. This function returns a dictionary for each requested torrent id holding the information about the files.

See more detail in transmission_rpc.torrent.Torrent.files()

{
    <torrent id>: [
        <File 0>,
        <File 1>,
        ...
    ],
    ...
}

Parameters

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

Return type

Dict[int, List[transmission_rpc.lib_types.File]]

set_files(items, timeout=None)[source]

Set file properties. Takes a dictionary with similar contents as the result of transmission_rpc.client.Client.get_files().

{
    <torrent id>: {
        <file id>: {
            'priority': <priority ('high'|'normal'|'low')>,
            'selected': <selected for download (True|False)>
        },
        ...
    },
    ...
}

Parameters

items (Dict[str, Dict[str, Dict[str, Any]]]) –
timeout (Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]]) –

Return type

None

change_torrent(ids, timeout=None, **kwargs)[source]

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

Argument	RPC	Replaced by	Description
`bandwidthPriority`	5 -		Priority for this transfer.
`downloadLimit`	5 -		Set the speed limit for download in Kib/s.
`downloadLimited`	5 -		Enable download speed limiter.
`files_unwanted`	1 -		A list of file id’s that shouldn’t be downloaded.
`files_wanted`	1 -		A list of file id’s that should be downloaded.
`honorsSessionLimits`	5 -		Enables or disables the transfer to honour the upload limit set in the session.
`location`	1 -		Local download location.
`peer_limit`	1 -		The peer limit for the torrents.
`priority_high`	1 -		A list of file id’s that should have high priority.
`priority_low`	1 -		A list of file id’s that should have normal priority.
`priority_normal`	1 -		A list of file id’s that should have low priority.
`queuePosition`	14 -		Position of this transfer in its queue.
`seedIdleLimit`	10 -		Seed inactivity limit in minutes.
`seedIdleMode`	10 -		Seed inactivity mode. 0 = Use session limit, 1 = Use transfer limit, 2 = Disable limit.
`seedRatioLimit`	5 -		Seeding ratio.
`seedRatioMode`	5 -		Which ratio to use. 0 = Use session limit, 1 = Use transfer limit, 2 = Disable limit.
`speed_limit_down`	1 - 5	downloadLimit	Set the speed limit for download in Kib/s.
`speed_limit_down_enabled`	1 - 5	downloadLimited	Enable download speed limiter.
`speed_limit_up`	1 - 5	uploadLimit	Set the speed limit for upload in Kib/s.
`speed_limit_up_enabled`	1 - 5	uploadLimited	Enable upload speed limiter.
`trackerAdd`	10 -		Array of string with announce URLs to add.
`trackerRemove`	10 -		Array of ids of trackers to remove.
`trackerReplace`	10 -		Array of (id, url) tuples where the announce URL should be replaced.
`uploadLimit`	5 -		Set the speed limit for upload in Kib/s.
`uploadLimited`	5 -		Enable upload speed limiter.
`labels`	16 -		Array of string labels.

Note

transmission_rpc will try to automatically fix argument errors.

Parameters

ids (Optional[Union[str, int, List[Union[int, str]]]]) –
timeout (Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]]) –
kwargs (Any) –

Return type

None

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

Move torrent data to the new location.

Parameters

ids (Optional[Union[str, int, List[Union[int, str]]]]) –
location (Union[str, pathlib.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[str, int, List[Union[int, str]]]]) –
location (Union[str, pathlib.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]

Rename directory and/or files for torrent. Remember to use get_torrent or get_torrents to update your file information.

Parameters

torrent_id (Union[int, str]) –
location (Union[str, pathlib.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[str, int, 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[str, int, 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[str, int, 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[str, int, 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: transmission_rpc.session.Session

set_session(timeout=None, **kwargs)[source]

Set session parameters. The parameters are:

Argument	RPC	Replaced by	Description
`alt_speed_down`	5 -		Alternate session download speed limit (in Kib/s).
`alt_speed_enabled`	5 -		Enables alternate global download speed limiter.
`alt_speed_time_begin`	5 -		Time when alternate speeds should be enabled. Minutes after midnight.
`alt_speed_time_day`	5 -		Enables alternate speeds scheduling these days.
`alt_speed_time_enabled`	5 -		Enables alternate speeds scheduling.
`alt_speed_time_end`	5 -		Time when alternate speeds should be disabled. Minutes after midnight.
`alt_speed_up`	5 -		Alternate session upload speed limit (in Kib/s).
`blocklist_enabled`	5 -		Enables the block list
`blocklist_url`	11 -		Location of the block list. Updated with blocklist-update.
`cache_size_mb`	10 -		The maximum size of the disk cache in MB
`dht_enabled`	6 -		Enables DHT.
`download_dir`	1 -		Set the session download directory.
`download_queue_enabled`	14 -		Enables download queue.
`download_queue_size`	14 -		Number of slots in the download queue.
`encryption`	1 -		Set the session encryption mode, one of `required`, `preferred` or `tolerated`.
`idle_seeding_limit`	10 -		The default seed inactivity limit in minutes.
`idle_seeding_limit_enabled`	10 -		Enables the default seed inactivity limit
`incomplete_dir`	7 -		The path to the directory of incomplete transfer data.
`incomplete_dir_enabled`	7 -		Enables the incomplete transfer data directory. Otherwise data for incomplete transfers are stored in the download target.
`lpd_enabled`	9 -		Enables local peer discovery for public torrents.
`peer_limit`	1 - 5	peer-limit-global	Maximum number of peers.
`peer_limit_global`	5 -		Maximum number of peers.
`peer_limit_per_torrent`	5 -		Maximum number of peers per transfer.
`peer_port`	5 -		Peer port.
`peer_port_random_on_start`	5 -		Enables randomized peer port on start of Transmission.
`pex_allowed`	1 - 5	pex-enabled	Allowing PEX in public torrents.
`pex_enabled`	5 -		Allowing PEX in public torrents.
`port`	1 - 5	peer-port	Peer port.
`port_forwarding_enabled`	1 -		Enables port forwarding.
`queue_stalled_enabled`	14 -		Enable tracking of stalled transfers.
`queue_stalled_minutes`	14 -		Number of minutes of idle that marks a transfer as stalled.
`rename_partial_files`	8 -		Appends “.part” to incomplete files
`script_torrent_done_enabled`	9 -		Whether or not to call the “done” script.
`script_torrent_done_filename`	9 -		Filename of the script to run when the transfer is done.
`seed_queue_enabled`	14 -		Enables upload queue.
`seed_queue_size`	14 -		Number of slots in the upload queue.
`seedRatioLimit`	5 -		Seed ratio limit. 1.0 means 1:1 download and upload ratio.
`seedRatioLimited`	5 -		Enables seed ration limit.
`speed_limit_down`	1 -		Download speed limit (in Kib/s).
`speed_limit_down_enabled`	1 -		Enables download speed limiting.
`speed_limit_up`	1 -		Upload speed limit (in Kib/s).
`speed_limit_up_enabled`	1 -		Enables upload speed limiting.
`start_added_torrents`	9 -		Added torrents will be started right away.
`trash_original_torrent_files`	9 -		The .torrent file of added torrents will be deleted.
`utp_enabled`	13 -		Enables Micro Transport Protocol (UTP).

Note

transmission_rpc will try to automatically fix argument errors.

Parameters

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

Return type

None

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, pathlib.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: transmission_rpc.session.Session