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(*, protocol: typing_extensions.Literal[http, https] = 'http', username: str = None, password: str = None, host: str = '127.0.0.1', port: int = 9091, path: str = '/transmission/', timeout: Union[int, float] = 30.0, logger: logging.Logger = <Logger transmission-rpc (ERROR)>)

add_torrent(torrent: Union[BinaryIO, str], timeout: Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]] = None, **kwargs: Any) → str

Add torrent to transfers list. Takes a uri to a torrent or base64 encoded torrent data in torrent. You can find examples in test code tests/test_client.py

Note

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

Additional arguments are:

Argument	RPC	Replaced by	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.

blocklist_update(timeout: Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]] = None) → Optional[int]

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

change_torrent(ids: Optional[Union[str, int, List[Union[int, str]]]], timeout: Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]] = None, **kwargs: Any) → None

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.

Note

transmission_rpc will try to automatically fix argument errors.

free_space(path: Union[str, pathlib.Path], timeout: Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]] = None) → Optional[int]

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

get_files(ids: Optional[Union[str, int, List[Union[int, str]]]] = None, timeout: Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]] = None) → Dict[int, List[transmission_rpc.lib_types.File]]

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>,
        ...
    ],
    ...
}

get_session(timeout: Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]] = None) → transmission_rpc.session.Session

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

get_torrent(torrent_id: Union[int, str], arguments: Sequence[str] = None, timeout: Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]] = None) → transmission_rpc.torrent.Torrent

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.

get_torrents(ids: Optional[Union[str, int, List[Union[int, str]]]] = None, arguments: Sequence[str] = None, timeout: Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]] = None) → List[transmission_rpc.torrent.Torrent]

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

Returns a list of Torrent object.

locate_torrent_data(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]]]] = None) → None

Locate torrent data at the provided location.

move_torrent_data(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]]]] = None) → None

Move torrent data to the new location.

port_test(timeout: Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]] = None) → Optional[bool]

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

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

Move transfer to the bottom of the queue.

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

Move transfer down in the queue.

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

Move transfer to the top of the queue:_Timeout.

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

Move transfer up in the queue.

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

Reannounce torrent(s) with provided id(s)

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

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

rename_torrent_path(torrent_id: Union[int, str], location: Union[str, pathlib.Path], name: str, timeout: Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]] = None) → Tuple[str, str]

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

property rpc_version

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

session_stats(timeout: Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]] = None) → transmission_rpc.session.Session

Get session statistics

set_files(items: Dict[str, Dict[str, Dict[str, Any]]], timeout: Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]] = None) → None

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)>
        },
        ...
    },
    ...
}

set_session(timeout: Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]] = None, **kwargs: Any) → None

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.

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

Start all torrents respecting the queue order

start_torrent(ids: Optional[Union[str, int, List[Union[int, str]]]], bypass_queue: bool = False, timeout: Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]] = None) → None

Start torrent(s) with provided id(s)

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

stop torrent(s) with provided id(s)

property timeout

Get current timeout for HTTP queries.

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

verify torrent(s) with provided id(s)