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 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 (float) –
logger (Logger) –
- Return type:
- 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(torrent: BinaryIO | str | bytes | Path, timeout: int | float | Tuple[int | float, int | float] | None = None, *, download_dir: str | None = None, files_unwanted: List[int] | None = None, files_wanted: List[int] | None = None, paused: bool | None = None, peer_limit: int | None = None, priority_high: List[int] | None = None, priority_low: List[int] | None = None, priority_normal: List[int] | None = None, cookies: str | None = None, labels: Iterable[str] | None = None, bandwidthPriority: int | None = None) Torrent [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:
- blocklist_update(timeout: int | float | Tuple[int | float, int | float] | None = None) int | 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
- change_torrent(ids: int | str | List[str | int] | None, timeout: int | float | Tuple[int | float, int | float] | None = None, *, bandwidth_priority: int | None = None, download_limit: int | None = None, download_limited: bool | None = None, upload_limit: int | None = None, upload_limited: bool | None = None, files_unwanted: Iterable[int] | None = None, files_wanted: Iterable[int] | None = None, honors_session_limits: bool | None = None, location: str | None = None, peer_limit: int | None = None, priority_high: Iterable[int] | None = None, priority_low: Iterable[int] | None = None, priority_normal: Iterable[int] | None = None, queue_position: int | None = None, seed_idle_limit: int | None = None, seed_idle_mode: int | None = None, seed_ratio_limit: float | None = None, seed_ratio_mode: int | None = None, tracker_add: Iterable[str] | None = None, labels: Iterable[str] | None = None, group: str | None = None, tracker_list: Iterable[Iterable[str]] | None = None, tracker_replace: Iterable[Tuple[int, str]] | None = None, tracker_remove: Iterable[int] | None = None, **kwargs: Any) None [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
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.
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'}
- free_space(path: str | Path, timeout: int | float | Tuple[int | float, int | float] | None = None) int | 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
- get_recently_active_torrents(arguments: Iterable[str] | None = None, timeout: int | float | Tuple[int | float, int | float] | None = None) Tuple[List[Torrent], List[int]] [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]]
- get_session(timeout: int | float | Tuple[int | float, int | float] | None = None) Session [source]#
Get session parameters. See the Session class for more information.
- Parameters:
timeout (int | float | Tuple[int | float, int | float] | None) –
- Return type:
- get_torrent(torrent_id: int | str, arguments: Iterable[str] | None = None, timeout: int | float | Tuple[int | float, int | float] | None = None) Torrent [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. The torrent’sinfo_hash
will never change.- Parameters:
torrent_id (int | str) – torrent id can be an int or a torrent
info_hash
(hashString
property of theTorrent
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: int | str | List[str | int] | None = None, arguments: Iterable[str] | None = None, timeout: int | float | Tuple[int | float, int | float] | None = None) List[Torrent] [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]
- move_torrent_data(ids: int | str | List[str | int] | None, location: str | Path, timeout: int | float | Tuple[int | float, int | float] | None = None, *, move: bool = True) None [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
- port_test(timeout: int | float | Tuple[int | float, int | float] | None = None) bool | 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
- queue_bottom(ids: int | str | List[str | int] | None, timeout: int | float | Tuple[int | float, int | float] | None = None) 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_down(ids: int | str | List[str | int] | None, timeout: int | float | Tuple[int | float, int | float] | None = None) 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
- queue_top(ids: int | str | List[str | int] | None, timeout: int | float | Tuple[int | float, int | float] | None = None) 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_up(ids: int | str | List[str | int] | None, timeout: int | float | Tuple[int | float, int | float] | None = None) 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
- reannounce_torrent(ids: int | str | List[str | int] | None, timeout: int | float | Tuple[int | float, int | float] | None = None) 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
- remove_torrent(ids: int | str | List[str | int] | None, delete_data: bool = False, timeout: int | float | Tuple[int | float, int | float] | None = None) 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
- rename_torrent_path(torrent_id: int | str, location: str, name: str, timeout: int | float | Tuple[int | float, int | float] | None = None) Tuple[str, str] [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]
- property rpc_version: int#
Get the Transmission daemon RPC version.
- session_stats(timeout: int | float | Tuple[int | float, int | float] | None = None) SessionStats [source]#
Get session statistics
- Parameters:
timeout (int | float | Tuple[int | float, int | float] | None) –
- Return type:
- set_session(timeout: int | float | Tuple[int | float, int | float] | None = None, *, alt_speed_down: int | None = None, alt_speed_enabled: bool | None = None, alt_speed_time_begin: int | None = None, alt_speed_time_day: int | None = None, alt_speed_time_enabled: bool | None = None, alt_speed_time_end: int | None = None, alt_speed_up: int | None = None, blocklist_enabled: bool | None = None, blocklist_url: str | None = None, cache_size_mb: int | None = None, dht_enabled: bool | None = None, default_trackers: Iterable[str] | None = None, download_dir: str | None = None, download_queue_enabled: bool | None = None, download_queue_size: int | None = None, encryption: Literal['required', 'preferred', 'tolerated'] | None = None, idle_seeding_limit: int | None = None, idle_seeding_limit_enabled: bool | None = None, incomplete_dir: str | None = None, incomplete_dir_enabled: bool | None = None, lpd_enabled: bool | None = None, peer_limit_global: int | None = None, peer_limit_per_torrent: int | None = None, peer_port: int | None = None, peer_port_random_on_start: bool | None = None, pex_enabled: bool | None = None, port_forwarding_enabled: bool | None = None, queue_stalled_enabled: bool | None = None, queue_stalled_minutes: int | None = None, rename_partial_files: bool | None = None, script_torrent_done_enabled: bool | None = None, script_torrent_done_filename: str | None = None, seed_queue_enabled: bool | None = None, seed_queue_size: int | None = None, seed_ratio_limit: int | None = None, seed_ratio_limited: bool | None = None, speed_limit_down: int | None = None, speed_limit_down_enabled: bool | None = None, speed_limit_up: int | None = None, speed_limit_up_enabled: bool | None = None, start_added_torrents: bool | None = None, trash_original_torrent_files: bool | None = None, utp_enabled: bool | None = None, script_torrent_done_seeding_filename: str | None = None, script_torrent_done_seeding_enabled: bool | None = None, script_torrent_added_enabled: bool | None = None, script_torrent_added_filename: str | None = None, **kwargs: Any) None [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
- start_all(bypass_queue: bool = False, timeout: int | float | Tuple[int | float, int | float] | None = None) 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
- start_torrent(ids: int | str | List[str | int] | None, bypass_queue: bool = False, timeout: int | float | Tuple[int | float, int | float] | None = None) 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
- stop_torrent(ids: int | str | List[str | int] | None, timeout: int | float | Tuple[int | float, int | float] | None = None) 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
- property timeout: int | float | Tuple[int | float, int | float] | None#
Get current timeout for HTTP queries.
- verify_torrent(ids: int | str | List[str | int] | None, timeout: int | float | Tuple[int | float, int | float] | None = None) 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
Timeouts#
Since most methods results in HTTP requests against Transmission, it is
possible to provide a argument called timeout
. Default timeout is 30 seconds.