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://
ormagnet:
URLtorrent 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
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.
torrent (Union[BinaryIO, str, bytes, Path]) –
timeout (Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]]) –
- Return type
- 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[Iterable[str]]) –
timeout (Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]]) –
- Return type
- 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[Iterable[str]]) –
timeout (Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]]) –
- Return type
List[Torrent]
- 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[str, int, 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 honoredupload_limit (Optional[int]) – maximum upload speed (KBps)
upload_limited (Optional[bool]) – true if
upload_limit
is honoredbandwidth_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]]
, eachIterable[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[str, int, 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[str, int, 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[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
- 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
ortolerated
.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
scriptscript_torrent_done_seeding_enabled (Optional[bool]) – whether or not to call the
seeding-done
scriptscript_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]
Timeouts
Since most methods results in HTTP requests against Transmission, it is
possible to provide a argument called timeout
. Default timeout is 30 seconds.