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: 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 /

Parameters:

url (str)
timeout (float)
logger (Logger)

Return type:

Client

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 (Literal['http', 'https'])
username (str | None)
password (str | None)
host (str)
port (int)
path (str) – rpc request target path, default /transmission/rpc
timeout (float)
logger (Logger)

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
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.
labels (Iterable[str] | None) – Array of string labels. Add in rpc 17.

Return type:

Torrent

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

Parameters:: timeout (int | float | Tuple[int | float, int | float] | None)
Return type:: int | None

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) –
Torrent seed ratio mode

Valid options are transmission_rpc.constants.RatioLimitMode
seed_idle_limit (int | None) – torrent-level seeding ratio
seed_idle_mode (int | None) –
Seed inactivity mode.

Valid options are transmission_rpc.constants.IdleMode
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.

Example: [['https://tracker1/announce', 'https://tracker2/announce'], ['https://backup1.example.com/announce'], ['https://backup2.example.com/announce']].
tracker_add (Iterable[str] | None) –
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 (Iterable[int] | None) –
Array of ids of trackers to remove.

Warning

since transmission daemon 4.0.0, this argument is deprecated, use tracker_list instead.
tracker_replace (Iterable[Tuple[int, str]] | None) –
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.
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 as-is, the underline in the key will not be replaced, so you should use kwargs like {'a-argument': 'value'}

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

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]]

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

Parameters:: timeout (int | float | Tuple[int | float, int | float] | None)
Return type:: Session

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. The torrent’s info_hash will never change.

Parameters:

torrent_id (int | str) – torrent id can be an int or a torrent info_hash (hashString property of the 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

Raises:

KeyError – torrent with given torrent_id not found:

Return type:

Torrent

Get information for torrents with provided ids. For more information see Client.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]

Move torrent data to the new location.

See also

RPC Spec: renaming-a-torrents-path

Parameters:

torrent_id (int | str)
location (str)
name (str)
timeout (int | float | Tuple[int | float, int | float] | None)

Return type:

Tuple[str, str]

property rpc_version: int¶: Get the Transmission daemon RPC version.

Get session statistics

Parameters:: timeout (int | float | Tuple[int | float, int | float] | None)
Return type:: SessionStats

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 pass the arguments not supported yet future, it’s not compatibility promising.

transmission-rpc will merge kwargs in rpc arguments as-is

Start all torrents respecting the queue order

Parameters:

bypass_queue (bool)
timeout (int | float | Tuple[int | float, int | float] | None)

Return type:

None

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

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

property timeout: int | float | Tuple[int | float, int | float] | None¶: Get current timeout for HTTP queries.

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

Timeouts¶

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