Welcome to transmission-rpc’s documentation!

transmission-rpc is a python3 library to help your control your transmission daemon remotely.

quick start

import requests

from transmission_rpc import Client

torrent_url = "https://github.com/trim21/transmission-rpc/raw/v4.1.0/tests/fixtures/iso.torrent"
c = Client(host="localhost", port=9091, username="transmission", password="password")
c.add_torrent(torrent_url)

########


c = Client(username="transmission", password="password")

torrent_url = "magnet:?xt=urn:btih:e84213a794f3ccd890382a54a64ca68b7e925433&dn=ubuntu-18.04.1-desktop-amd64.iso"
c.add_torrent(torrent_url)

########


c = Client(username="trim21", password="123456")

torrent_url = "https://github.com/trim21/transmission-rpc/raw/v4.1.0/tests/fixtures/iso.torrent"
r = requests.get(torrent_url)

# client will base64 the torrent content for you.
c.add_torrent(r.content)

# or use a file-like object
with open("a", "wb") as f:
    f.write(r.content)
with open("a", "rb") as f:
    c.add_torrent(f)

See also

transmission_rpc.client.Client.add_torrent()

Example

Filter files

from transmission_rpc import Client

client = Client()

t = client.get_torrent(0)

client.change_torrent(
    t.hashString,
    files_unwanted=[f.id for f in t.get_files() if f.name.endswith(".txt")],
    priority_high=[f.id for f in t.get_files() if f.name.endswith(".mp4")],
    priority_low=[f.id for f in t.get_files() if f.name.endswith(".txt")],
)

Move Torrent Data

from transmission_rpc import Client

client = Client()

t = client.get_torrent(0)

client.move_torrent_data(t.hashString, location="/home/trim21/downloads/completed/")

Set Upload/Download Speed Limit

from transmission_rpc import Client

client = Client()

client.change_torrent(
    0,
    upload_limited=True,  # don't forget this
    upload_limit=100,
    download_limited=True,
    download_limit=100,
)

Arguments

Each method has it own arguments. You can pass arguments as kwargs when you call methods.

But in python, - can’t be used in a variable name, so you need to replace - with _.

For example, torrent-add method support arguments download-dir, you should call method like this.

from transmission_rpc import Client

Client().add_torrent(torrent_url, download_dir='/path/to/download/dir')

transmission-rpc will put {"download-dir": "/path/to/download/dir"} in arguments.

you can find rpc version by transmission version from transmission rpc docs

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 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 (int | float) –

  • logger (Logger) –

Return type:

Client

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) –

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

  • labels (Iterable[str] | None) – Array of string labels. Add in rpc 17.

  • 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.

Return type:

Torrent

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

Return type:

Torrent

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 (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 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) –

    Which ratio to use.

    0 = Use session limit

    1 = Use transfer limit

    2 = Disable limit.

  • seed_idle_limit (int | None) – torrent-level seeding ratio

  • seed_idle_mode (int | None) –

    Seed inactivity mode.

    0 = Use session limit

    1 = Use transfer limit

    2 = Disable limit.

  • tracker_add (Iterable[str] | None) – Array of string with announce URLs to add.

  • tracker_remove (Iterable[int] | None) – Array of ids of trackers to remove.

  • tracker_replace (Iterable[Tuple[int, str]] | None) – Array of (id, url) tuples where the announce URL should be replaced.

  • 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.

  • 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 (int | str | List[str | int] | None) –

  • location (str | Path) –

  • timeout (int | float | Tuple[int | float, int | float] | None) –

Return type:

None

locate_torrent_data(ids, location, timeout=None)[source]

Locate torrent data at the provided location.

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]

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 (int | str) –

  • location (str | Path) –

  • 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:_Timeout.

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.

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:

Session

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

session_stats(timeout=None)[source]

Get session statistics

Parameters:

timeout (int | float | Tuple[int | float, int | float] | None) –

Return type:

SessionStats

Timeouts

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

Torrent

class transmission_rpc.torrent.Torrent[source]

Torrent is a class holding the data received from Transmission regarding a bittorrent transfer.

Warning

setter on Torrent’s properties has been removed, please use Client().change_torrent() instead

__init__(*, fields)[source]
Parameters:

fields (Dict[str, Any]) –

property activity_date: datetime

The last time we uploaded or downloaded piece data on this torrent.

property added_date: datetime

When the torrent was first added.

property available: float

Availability in percent

property bandwidth_priority: int

TODO An array of pieceCount numbers representing the number of connected peers that have each piece, or -1 if we already have the piece ourselves.

property corrupt_ever: int

Byte count of all the corrupt data you’ve ever downloaded for this torrent. If you’re on a poisoned torrent, this number can grow very large.

property desired_available: int

Byte count of all the piece data we want and don’t have yet, but that a connected peer does have. [0…leftUntilDone]

property done_date: datetime

When the torrent finished downloading.

property download_dir: str | None

The download directory.

Available:

transmission version 1.5.

Available:

RPC version 4.

property downloaded_ever: int

Byte count of all the non-corrupt data you’ve ever downloaded for this torrent. If you deleted the files and downloaded a second time, this will be 2*totalSize.

property edit_date: datetime

The last time during this session that a rarely-changing field changed – e.g. any tr_torrent_metainfo field (trackers, filenames, name) or download directory. RPC clients can monitor this to know when to reload fields that rarely change.

property error: int

0 for fine task, non-zero for error torrent

property error_string: str

empty string for fine task

property eta: timedelta | None

the “eta” as datetime.timedelta.

If downloading, estimated the timedelta left until the torrent is done. If seeding, estimated the timedelta left until seed ratio is reached.

raw eta maybe negative: - -1 for ETA Not Available. - -2 for ETA Unknown.

https://github.com/transmission/transmission/blob/3.00/libtransmission/transmission.h#L1748-L1749

get_files()[source]

Get list of files for this torrent.

Note

The order of the files is guaranteed. The index of file object is the id of the file when calling transmission_rpc.client.Client.set_files().

from transmission_rpc import Client

torrent = Client().get_torrent(0)

for file in enumerate(torrent.get_files()):
    print(file.id)
Return type:

List[File]

property have_unchecked: int

Byte count of all the partial piece data we have for this torrent. As pieces become complete, this value may decrease as portions of it are moved to “corrupt” or “haveValid”.

property have_valid: int

Byte count of all the checksum-verified data we have for this torrent.

property honors_session_limits: bool

true if session upload limits are honored

property left_until_done: int

Byte count of how much data is left to be downloaded until we’ve got all the pieces that we want. [0…tr_stat.sizeWhenDone]

property metadata_percent_complete: float

How much of the metadata the torrent has. For torrents added from a torrent this will always be 1. For magnet links, this number will from from 0 to 1 as the metadata is downloaded. Range is [0..1]

property peer_limit: int

maximum number of peers

property peers_connected: int

Number of peers that we’re connected to

property peers_from: int

How many peers we found out about from the tracker, or from pex, or from incoming connections, or from our resume file.

property peers_getting_from_us: int

Number of peers that we’re sending data to

property peers_sending_to_us: int

Number of peers that are sending data to us.

property percent_complete: float

How much has been downloaded of the entire torrent. Range is [0..1]

property percent_done: float

How much has been downloaded of the files the user wants. This differs from percentComplete if the user wants only some of the torrent’s files. Range is [0..1]

property pieces: str

A bitfield holding pieceCount flags which are set to ‘true’ if we have the piece matching that position.

JSON doesn’t allow raw binary data, so this is a base64-encoded string. (Source: tr_torrent)

property queue_position: int

position of this torrent in its queue [0…n)

property rate_download: int

download rate (B/s)

property rate_upload: int

upload rate (B/s)

property tracker_list: List[str]

list of str of announce URLs

property torrent_file: str

torrent file location on transmission server

Examples

/var/lib/transmission-daemon/.config/transmission-daemon/torrents/00000000000000000000000000.torrent

property webseeds_sending_to_us: int

Number of webseeds that are sending data to us.

property status: Status

Returns the torrent status. Is either one of ‘check pending’, ‘checking’, ‘downloading’, ‘download pending’, ‘seeding’, ‘seed pending’ or ‘stopped’. The first two is related to verification.

Examples:

torrent = Torrent()
torrent.status.downloading
torrent.status == 'downloading'
property progress: float

download progress in percent.

property ratio: float

upload/download ratio.

property date_active: datetime

the attribute activityDate as datetime.datetime in UTC timezone.

Note

raw activityDate value could be 0 for never activated torrent, therefore it can’t always be converted to local timezone.

property date_added: datetime

raw field addedDate as datetime.datetime in utc timezone.

property date_started: datetime

raw field startDate as datetime.datetime in utc timezone.

property date_done: datetime | None

the attribute “doneDate” as datetime.datetime. returns None if “doneDate” is invalid.

format_eta()[source]

Returns the attribute eta formatted as a string.

  • If eta is -1 the result is ‘not available’

  • If eta is -2 the result is ‘unknown’

  • Otherwise eta is formatted as <days> <hours>:<minutes>:<seconds>.

Return type:

str

property priority: str

Bandwidth priority as string. Can be one of ‘low’, ‘normal’, ‘high’. This is a mutator.

property seed_idle_mode: str

Seed idle mode as string. Can be one of ‘global’, ‘single’ or ‘unlimited’.

  • global, use session seed idle limit.

  • single, use torrent seed idle limit. See seed_idle_limit.

  • unlimited, no seed idle limit.

property seed_ratio_limit: float

Torrent seed ratio limit as float. Also see seed_ratio_mode. This is a mutator.

property seed_ratio_mode: str

Seed ratio mode as string. Can be one of ‘global’, ‘single’ or ‘unlimited’.

  • global, use session seed ratio limit.

  • single, use torrent seed ratio limit. See seed_ratio_limit.

  • unlimited, no seed ratio limit.

fields: Dict[str, Any]

raw fields

class transmission_rpc.torrent.Status[source]

A wrapped str for torrent status.

returned by Torrent.status

stopped: bool
check_pending: bool
checking: bool
download_pending: bool
downloading: bool
seed_pending: bool
seeding: bool
static __new__(cls, raw)[source]
Parameters:

raw (str) –

Return type:

Status

__init__()

Session

class transmission_rpc.session.Session[source]

Session is a class holding the session data for a Transmission daemon.

Access the session field can be done through attributes. The attributes available are the same as the session arguments in the Transmission RPC specification, but with underscore instead of hyphen.

get 'download-dir' with session.download_dir.

session = Client().get_session()

current = session.download_dir

https://github.com/transmission/transmission/blob/main/docs/rpc-spec.md#41-session-arguments

Warning

setter on session’s properties has been removed, please use Client().set_session() instead

property alt_speed_down: int

max global download speed (KBps)

property alt_speed_enabled: bool
property alt_speed_time_begin: int

minutes after midnight)

Type:

when to turn on alt speeds (units

property alt_speed_time_day: int

what day(s) to turn on alt speeds (look at tr_sched_day)

property alt_speed_time_enabled: bool

true means the scheduled on/off times are used

property alt_speed_time_end: int

same)

Type:

when to turn off alt speeds (units

property alt_speed_up: int

max global upload speed (KBps)

property blocklist_enabled: bool

true means enabled

property blocklist_size: int

int of rules in the blocklist

property blocklist_url: str

location of the blocklist to use for blocklist-update

property cache_size_mb: int

maximum size of the disk cache (MB)

property config_dir: str

location of transmission’s configuration directory

property dht_enabled: bool

true means allow dht in public torrents

property download_dir: str

default path to download torrents

property download_dir_free_space: int

DEPRECATED Use the free-space method instead.

property download_queue_enabled: bool

if true, limit how many torrents can be downloaded at once

property download_queue_size: int

max int of torrents to download at once (see download-queue-enabled)

property encryption: Literal['required', 'preferred', 'tolerated']
property idle_seeding_limit_enabled: bool

true if the seeding inactivity limit is honored by default

property idle_seeding_limit: int

torrents we’re seeding will be stopped if they’re idle for this long

property incomplete_dir_enabled: bool

true means keep torrents in incomplete-dir until done

property incomplete_dir: str

path for incomplete torrents, when enabled

property lpd_enabled: bool

true means allow Local Peer Discovery in public torrents

property peer_limit_global: int

maximum global int of peers

property peer_limit_per_torrent: int

maximum global int of peers

property peer_port_random_on_start: bool

true means pick a random peer port on launch

property peer_port: int

port int

property pex_enabled: bool

true means allow pex in public torrents

property port_forwarding_enabled: bool

true means ask upstream router to forward the configured peer port to transmission using UPnP or NAT-PMP

property queue_stalled_enabled: bool

whether or not to consider idle torrents as stalled

property queue_stalled_minutes: int

torrents that are idle for N minutes aren’t counted toward seed-queue-size or download-queue-size

property rename_partial_files: bool

true means append .part to incomplete files

property rpc_version_minimum: int

the minimum RPC API version supported

property rpc_version: int

the current RPC API version

property script_torrent_done_enabled: bool

whether or not to call the done script

property script_torrent_done_filename: str

filename of the script to run

property seed_queue_enabled: bool

if true, limit how many torrents can be uploaded at once

property seed_queue_size: int

max int of torrents to uploaded at once (see seed-queue-enabled)

property seedRatioLimit: float

the default seed ratio for torrents to use

property seedRatioLimited: bool

true if seedRatioLimit is honored by default

property speed_limit_down_enabled: bool

true means enabled

property speed_limit_down: int

max global download speed (KBps)

property speed_limit_up_enabled: bool

true means enabled

property speed_limit_up: int

max global upload speed (KBps)

property start_added_torrents: bool

true means added torrents will be started right away

property trash_original_torrent_files: bool

true means the .torrent file of added torrents will be deleted

property units: Units
property utp_enabled: bool

true means allow utp

property version: str

long version str $version ($revision)

property default_trackers: list | None

list of default trackers to use on public torrents new at rpc-version 17

property rpc_version_semver: str | None

the current RPC API version in a semver-compatible str new at rpc-version 17

property script_torrent_added_enabled: bool | None

whether or not to call the added script new at rpc-version 17

property script_torrent_added_filename: str | None

filename of the script to run new at rpc-version 17

property script_torrent_done_seeding_enabled: bool | None

whether or not to call the seeding-done script new at rpc-version 17

property script_torrent_done_seeding_filename: str | None

filename of the script to run new at rpc-version 17

get(key, default=None)

get the raw value from files by the raw keys

Parameters:

  • key (str) –

  • default (T | None) –

Return type:

Any

fields: Dict[str, Any]

raw fields

Errors

exception raise by this package

exception transmission_rpc.error.TransmissionError[source]

This exception is raised when there has occurred an error related to communication with Transmission.

__init__(message='', original=None)[source]
Parameters:

  • message (str) –

  • original (Response | None) –

exception transmission_rpc.error.TransmissionAuthError[source]

Raised when username or password is incorrect

exception transmission_rpc.error.TransmissionConnectError[source]

raised when client can’t connect to transmission daemon

exception transmission_rpc.error.TransmissionTimeoutError[source]

Timeout

Utils

transmission_rpc.utils.format_size(size)[source]

Format byte size into IEC prefixes, B, KiB, MiB …

Parameters:

size (int) –

Return type:

Tuple[float, str]

transmission_rpc.utils.format_speed(size)[source]

Format bytes per second speed into IEC prefixes, B/s, KiB/s, MiB/s …

Parameters:

size (int) –

Return type:

Tuple[float, str]

transmission_rpc.utils.format_timedelta(delta)[source]

Format datetime.timedelta into <days> <hours>:<minutes>:<seconds>.

Parameters:

delta (timedelta) –

Return type:

str

transmission_rpc.utils.get_torrent_arguments(rpc_version)[source]

Get torrent arguments for method in specified Transmission RPC version.

Parameters:

rpc_version (int) –

Return type:

List[str]

Indices and tables