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, timeout=30.0, logger=<Logger transmission-rpc (ERROR)>)[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 usehttp://127.0.0.1:9091
And
from_url("http://127.0.0.1")
is not same asfrom_url("http://127.0.0.1/")
,path
ofhttp://127.0.0.1/
is/
- Parameters:
url (str) –
timeout (int | float) –
logger (Logger) –
- Return type:
- class transmission_rpc.Client[source]
- __init__(*, protocol='http', username=None, password=None, host='127.0.0.1', port=9091, path='/transmission/rpc', timeout=30.0, 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 (int | float) –
logger (Logger) –
- property timeout: int | float | Tuple[int | float, int | float] | None
Get current timeout for HTTP queries.
- property rpc_version: int
Get the Transmission daemon RPC version.
- 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:
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:
- remove_torrent(ids, delete_data=False, timeout=None)[source]
remove torrent(s) with provided id(s).
Local data will be removed by transmission daemon if
delete_data
is set toTrue
.- Parameters:
ids (int | str | List[str | int] | None) –
delete_data (bool) –
timeout (int | float | Tuple[int | float, int | float] | None) –
- Return type:
None
- start_torrent(ids, bypass_queue=False, timeout=None)[source]
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
- start_all(bypass_queue=False, timeout=None)[source]
Start all torrents respecting the queue order
- Parameters:
bypass_queue (bool) –
timeout (int | float | Tuple[int | float, int | float] | None) –
- Return type:
None
- stop_torrent(ids, timeout=None)[source]
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
- verify_torrent(ids, timeout=None)[source]
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
- reannounce_torrent(ids, timeout=None)[source]
Reannounce 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
- 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 (int | str) – torrent id can be an int or a torrent info_hash (hash_string of 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:
- get_torrents(ids=None, arguments=None, timeout=None)[source]
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]
- 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 (Iterable[str] | None) –
timeout (int | float | Tuple[int | float, int | float] | None) –
- 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 (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 honoredupload_limit (int | None) – maximum upload speed (KBps)
upload_limited (bool | None) – true if
upload_limit
is honoredbandwidth_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
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.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]]
, 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 as-is, the underline in the key will not be replaced, so you should use kwargs like
{'a-argument': 'value'}
- move_torrent_data(ids, location, timeout=None, *, move=True)[source]
Move torrent data to the new location.
See also
- Parameters:
ids (int | str | List[str | int] | None) –
location (str | Path) –
timeout (int | float | Tuple[int | float, int | float] | None) –
move (bool) –
- Return type:
None
- locate_torrent_data(ids, location, timeout=None)[source]
Locate torrent data at the provided location.
Warning
since transmission-rpc version 4.2.1, this method is deprecated.
Use
client.move_torrent_data(ids, location, move=False)
insteadthis is same rpc call as
Client.move_torrent_data()
, but with argumentsmove=False
See also
- Parameters:
ids (int | str | List[str | int] | None) –
location (str | Path) –
timeout (int | float | Tuple[int | float, int | float] | None) –
- Return type:
None
- rename_torrent_path(torrent_id, location, name, timeout=None)[source]
Warning
This method can only be called on single torrent.
Warning
This is not the method to move torrent data directory,
See also
- Parameters:
torrent_id (int | str) –
location (str) –
name (str) –
timeout (int | float | Tuple[int | float, int | float] | None) –
- Return type:
Tuple[str, str]
- queue_top(ids, timeout=None)[source]
Move transfer to the top of the queue.
https://github.com/transmission/transmission/blob/main/docs/rpc-spec.md#46-queue-movement-requests
- Parameters:
ids (int | str | List[str | int] | None) –
timeout (int | float | Tuple[int | float, int | float] | None) –
- Return type:
None
- queue_bottom(ids, timeout=None)[source]
Move transfer to the bottom of the queue.
https://github.com/transmission/transmission/blob/main/docs/rpc-spec.md#46-queue-movement-requests
- Parameters:
ids (int | str | List[str | int] | None) –
timeout (int | float | Tuple[int | float, int | float] | None) –
- Return type:
None
- queue_up(ids, timeout=None)[source]
Move transfer up in the queue.
- Parameters:
ids (int | str | List[str | int] | None) –
timeout (int | float | Tuple[int | float, int | float] | None) –
- Return type:
None
- queue_down(ids, timeout=None)[source]
Move transfer down in the queue.
- Parameters:
ids (int | str | List[str | int] | None) –
timeout (int | float | Tuple[int | float, int | float] | None) –
- Return type:
None
- get_session(timeout=None)[source]
Get session parameters. See the Session class for more information.
- Parameters:
timeout (int | float | Tuple[int | float, int | float] | None) –
- 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, default_trackers=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 (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
ortolerated
.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
scriptscript_torrent_done_seeding_enabled (bool | None) – whether or not to call the
seeding-done
scriptscript_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
- blocklist_update(timeout=None)[source]
Update block list. Returns the size of the block list.
- Parameters:
timeout (int | float | Tuple[int | float, int | float] | None) –
- Return type:
int | None
- port_test(timeout=None)[source]
Tests to see if your incoming peer port is accessible from the outside world.
- Parameters:
timeout (int | float | Tuple[int | float, int | float] | None) –
- Return type:
bool | None
- free_space(path, timeout=None)[source]
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
Timeouts
Since most methods results in HTTP requests against Transmission, it is
possible to provide a argument called timeout
. Default timeout is 30 seconds.