Welcome to transmission-rpc’s documentation!¶

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

quick start¶

from transmission_rpc import Client

torrent_url = 'http://releases.ubuntu.com/' + \
              '18.04/ubuntu-18.04.1-desktop-amd64.iso.torrent'
c = Client(host='localhost', port=9091, username='transmission', password='password')
c.add_torrent(torrent_url)

########

from transmission_rpc import Client

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

torrent_url = 'magnet:?xt=urn:btih:e84213a794f3ccd890382a54' + \
              'a64ca68b7e925433&dn=ubuntu-18.04.1-desktop-amd64.iso'
c.add_torrent(torrent_url)

########

from transmission_rpc import Client
import requests

torrent_url = 'http://releases.ubuntu.com/' + \
              '18.04/ubuntu-18.04.1-desktop-amd64.iso.torrent'
r = requests.get(torrent_url)
with open('a', 'wb') as f:
    f.write(r.content)
c = Client(username='trim21', password='123456')
with open('a', 'rb') as f:
    c.add_torrent(f)

client.add_torrent support a url string(could start with file:), file-like object(object with read() method) or base64 encoded torrent file content.

if torrent starts with file, transmission-rpc will read it from disk and base64 encode it.

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.

helper¶

If you want to know what kwargs you can use for a method, you can use transmission_rpc.utils.get_arguments() to get support arguments. For example, transmission 2.94 is rpc version 15, so just call print(get_arguments('torrent-add', 15))

rpc method and class method are not same, but reversed

you can find rpc version by transmission version from transmission wiki

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

Timeouts¶

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

class transmission_rpc.client.Client(*, protocol: typing_extensions.Literal[http, https] = 'http', username: Optional[str] = None, password: Optional[str] = None, host: str = '127.0.0.1', port: int = 9091, path: str = '/transmission/', timeout: Union[int, float] = 30.0, logger: logging.Logger = <Logger transmission-rpc (ERROR)>)[source]¶

property timeout¶: Get current timeout for HTTP queries.

property rpc_version¶: Get the Transmission RPC version. Trying to deduct if the server don’t have a version value.

add_torrent(torrent: Union[BinaryIO, str], timeout: Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]] = None, **kwargs: Any) → transmission_rpc.torrent.Torrent [source]¶

Add torrent to transfers list. Takes a uri to a torrent or base64 encoded torrent data in torrent. You can find examples in test code tests/test_client.py

Note

url starts with file:// will be load by this package instead of transmission daemon

Additional arguments are:

Argument	RPC	Description
`bandwidthPriority`	8 -	Priority for this transfer.
`cookies`	13 -	One or more HTTP cookie(s).
`download_dir`	1 -	The directory where the downloaded contents will be saved in.
`files_unwanted`	1 -	A list of file id’s that shouldn’t be downloaded.
`files_wanted`	1 -	A list of file id’s that should be downloaded.
`paused`	1 -	If True, does not start the transfer when added.
`peer_limit`	1 -	Maximum number of peers allowed.
`priority_high`	1 -	A list of file id’s that should have high priority.
`priority_low`	1 -	A list of file id’s that should have low priority.
`priority_normal`	1 -	A list of file id’s that should have normal priority.

Returns a Torrent object with the fields.

remove_torrent(ids: Optional[Union[str, int, List[Union[int, str]]]], delete_data: bool = False, timeout: Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]] = None) → None[source]¶: remove torrent(s) with provided id(s). Local data is removed if delete_data is True, otherwise not.

start_torrent(ids: Optional[Union[str, int, List[Union[int, str]]]], bypass_queue: bool = False, timeout: Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]] = None) → None[source]¶: Start torrent(s) with provided id(s)

start_all(bypass_queue: bool = False, timeout: Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]] = None) → None[source]¶: Start all torrents respecting the queue order

stop_torrent(ids: Optional[Union[str, int, List[Union[int, str]]]], timeout: Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]] = None) → None[source]¶: stop torrent(s) with provided id(s)

verify_torrent(ids: Optional[Union[str, int, List[Union[int, str]]]], timeout: Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]] = None) → None[source]¶: verify torrent(s) with provided id(s)

reannounce_torrent(ids: Optional[Union[str, int, List[Union[int, str]]]], timeout: Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]] = None) → None[source]¶: Reannounce torrent(s) with provided id(s)

get_torrent(torrent_id: Union[int, str], arguments: Optional[Sequence[str]] = None, timeout: Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]] = None) → transmission_rpc.torrent.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.

get_torrents(ids: Optional[Union[str, int, List[Union[int, str]]]] = None, arguments: Optional[Sequence[str]] = None, timeout: Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]] = None) → List[transmission_rpc.torrent.Torrent][source]¶

Get information for torrents with provided ids. For more information see get_torrent.

Returns a list of Torrent object.

get_files(ids: Optional[Union[str, int, List[Union[int, str]]]] = None, timeout: Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]] = None) → Dict[int, List[transmission_rpc.lib_types.File]][source]¶

Get list of files for provided torrent id(s). If ids is empty, information for all torrents are fetched. This function returns a dictionary for each requested torrent id holding the information about the files.

See more detail in transmission_rpc.torrent.Torrent.files()

{
    <torrent id>: [
        <File 0>,
        <File 1>,
        ...
    ],
    ...
}

set_files(items: Dict[str, Dict[str, Dict[str, Any]]], timeout: Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]] = None) → None[source]¶

Set file properties. Takes a dictionary with similar contents as the result of transmission_rpc.client.Client.get_files().

{
    <torrent id>: {
        <file id>: {
            'priority': <priority ('high'|'normal'|'low')>,
            'selected': <selected for download (True|False)>
        },
        ...
    },
    ...
}

change_torrent(ids: Optional[Union[str, int, List[Union[int, str]]]], timeout: Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]] = None, **kwargs: Any) → None[source]¶

Change torrent parameters for the torrent(s) with the supplied id’s. The parameters are:

Argument	RPC	Replaced by	Description
`bandwidthPriority`	5 -		Priority for this transfer.
`downloadLimit`	5 -		Set the speed limit for download in Kib/s.
`downloadLimited`	5 -		Enable download speed limiter.
`files_unwanted`	1 -		A list of file id’s that shouldn’t be downloaded.
`files_wanted`	1 -		A list of file id’s that should be downloaded.
`honorsSessionLimits`	5 -		Enables or disables the transfer to honour the upload limit set in the session.
`location`	1 -		Local download location.
`peer_limit`	1 -		The peer limit for the torrents.
`priority_high`	1 -		A list of file id’s that should have high priority.
`priority_low`	1 -		A list of file id’s that should have normal priority.
`priority_normal`	1 -		A list of file id’s that should have low priority.
`queuePosition`	14 -		Position of this transfer in its queue.
`seedIdleLimit`	10 -		Seed inactivity limit in minutes.
`seedIdleMode`	10 -		Seed inactivity mode. 0 = Use session limit, 1 = Use transfer limit, 2 = Disable limit.
`seedRatioLimit`	5 -		Seeding ratio.
`seedRatioMode`	5 -		Which ratio to use. 0 = Use session limit, 1 = Use transfer limit, 2 = Disable limit.
`speed_limit_down`	1 - 5	downloadLimit	Set the speed limit for download in Kib/s.
`speed_limit_down_enabled`	1 - 5	downloadLimited	Enable download speed limiter.
`speed_limit_up`	1 - 5	uploadLimit	Set the speed limit for upload in Kib/s.
`speed_limit_up_enabled`	1 - 5	uploadLimited	Enable upload speed limiter.
`trackerAdd`	10 -		Array of string with announce URLs to add.
`trackerRemove`	10 -		Array of ids of trackers to remove.
`trackerReplace`	10 -		Array of (id, url) tuples where the announce URL should be replaced.
`uploadLimit`	5 -		Set the speed limit for upload in Kib/s.
`uploadLimited`	5 -		Enable upload speed limiter.
`labels`	16 -		Array of string labels.

Note

transmission_rpc will try to automatically fix argument errors.

move_torrent_data(ids: Optional[Union[str, int, List[Union[int, str]]]], location: Union[str, pathlib.Path], timeout: Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]] = None) → None[source]¶: Move torrent data to the new location.

locate_torrent_data(ids: Optional[Union[str, int, List[Union[int, str]]]], location: Union[str, pathlib.Path], timeout: Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]] = None) → None[source]¶: Locate torrent data at the provided location.

rename_torrent_path(torrent_id: Union[int, str], location: Union[str, pathlib.Path], name: str, timeout: Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]] = None) → Tuple[str, str][source]¶: Rename directory and/or files for torrent. Remember to use get_torrent or get_torrents to update your file information.

queue_top(ids: Optional[Union[str, int, List[Union[int, str]]]], timeout: Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]] = None) → None[source]¶: Move transfer to the top of the queue:_Timeout.

queue_bottom(ids: Optional[Union[str, int, List[Union[int, str]]]], timeout: Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]] = None) → None[source]¶: Move transfer to the bottom of the queue.

queue_up(ids: Optional[Union[str, int, List[Union[int, str]]]], timeout: Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]] = None) → None[source]¶: Move transfer up in the queue.

queue_down(ids: Optional[Union[str, int, List[Union[int, str]]]], timeout: Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]] = None) → None[source]¶: Move transfer down in the queue.

get_session(timeout: Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]] = None) → transmission_rpc.session.Session[source]¶: Get session parameters. See the Session class for more information.

set_session(timeout: Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]] = None, **kwargs: Any) → None[source]¶

Set session parameters. The parameters are:

Argument	RPC	Replaced by	Description
`alt_speed_down`	5 -		Alternate session download speed limit (in Kib/s).
`alt_speed_enabled`	5 -		Enables alternate global download speed limiter.
`alt_speed_time_begin`	5 -		Time when alternate speeds should be enabled. Minutes after midnight.
`alt_speed_time_day`	5 -		Enables alternate speeds scheduling these days.
`alt_speed_time_enabled`	5 -		Enables alternate speeds scheduling.
`alt_speed_time_end`	5 -		Time when alternate speeds should be disabled. Minutes after midnight.
`alt_speed_up`	5 -		Alternate session upload speed limit (in Kib/s).
`blocklist_enabled`	5 -		Enables the block list
`blocklist_url`	11 -		Location of the block list. Updated with blocklist-update.
`cache_size_mb`	10 -		The maximum size of the disk cache in MB
`dht_enabled`	6 -		Enables DHT.
`download_dir`	1 -		Set the session download directory.
`download_queue_enabled`	14 -		Enables download queue.
`download_queue_size`	14 -		Number of slots in the download queue.
`encryption`	1 -		Set the session encryption mode, one of `required`, `preferred` or `tolerated`.
`idle_seeding_limit`	10 -		The default seed inactivity limit in minutes.
`idle_seeding_limit_enabled`	10 -		Enables the default seed inactivity limit
`incomplete_dir`	7 -		The path to the directory of incomplete transfer data.
`incomplete_dir_enabled`	7 -		Enables the incomplete transfer data directory. Otherwise data for incomplete transfers are stored in the download target.
`lpd_enabled`	9 -		Enables local peer discovery for public torrents.
`peer_limit`	1 - 5	peer-limit-global	Maximum number of peers.
`peer_limit_global`	5 -		Maximum number of peers.
`peer_limit_per_torrent`	5 -		Maximum number of peers per transfer.
`peer_port`	5 -		Peer port.
`peer_port_random_on_start`	5 -		Enables randomized peer port on start of Transmission.
`pex_allowed`	1 - 5	pex-enabled	Allowing PEX in public torrents.
`pex_enabled`	5 -		Allowing PEX in public torrents.
`port`	1 - 5	peer-port	Peer port.
`port_forwarding_enabled`	1 -		Enables port forwarding.
`queue_stalled_enabled`	14 -		Enable tracking of stalled transfers.
`queue_stalled_minutes`	14 -		Number of minutes of idle that marks a transfer as stalled.
`rename_partial_files`	8 -		Appends “.part” to incomplete files
`script_torrent_done_enabled`	9 -		Whether or not to call the “done” script.
`script_torrent_done_filename`	9 -		Filename of the script to run when the transfer is done.
`seed_queue_enabled`	14 -		Enables upload queue.
`seed_queue_size`	14 -		Number of slots in the upload queue.
`seedRatioLimit`	5 -		Seed ratio limit. 1.0 means 1:1 download and upload ratio.
`seedRatioLimited`	5 -		Enables seed ration limit.
`speed_limit_down`	1 -		Download speed limit (in Kib/s).
`speed_limit_down_enabled`	1 -		Enables download speed limiting.
`speed_limit_up`	1 -		Upload speed limit (in Kib/s).
`speed_limit_up_enabled`	1 -		Enables upload speed limiting.
`start_added_torrents`	9 -		Added torrents will be started right away.
`trash_original_torrent_files`	9 -		The .torrent file of added torrents will be deleted.
`utp_enabled`	13 -		Enables Micro Transport Protocol (UTP).

Note

transmission_rpc will try to automatically fix argument errors.

blocklist_update(timeout: Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]] = None) → Optional[int][source]¶: Update block list. Returns the size of the block list.

port_test(timeout: Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]] = None) → Optional[bool][source]¶: Tests to see if your incoming peer port is accessible from the outside world.

free_space(path: Union[str, pathlib.Path], timeout: Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]] = None) → Optional[int][source]¶: Get the amount of free space (in bytes) at the provided location.

session_stats(timeout: Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]] = None) → transmission_rpc.session.Session[source]¶: Get session statistics

Torrent¶

class transmission_rpc.torrent.Torrent(client: Client, fields: Dict[str, Any])[source]¶

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

All fetched torrent fields are accessible through this class using attributes. This class has a few convenience properties using the torrent data.

property id¶: Returns the id for this torrent

files() → List[transmission_rpc.lib_types.File][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_id, file in enumerate(torrent.files()):
    print(file_id, file)

property name¶

Returns the name of this torrent.

Raise AttributeError if server don’t return this field

property status¶

Return type: 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 rateDownload¶

Returns download rate in B/s

Return type: int

property rateUpload¶

Returns upload rate in B/s

Return type: int

property hashString¶

Returns the info hash of this torrent.

Raise: AttributeError – if server don’t return this field
Return type: int

property progress¶

download progress in percent.

Return type: float

property ratio¶

upload/download ratio.

Return type: float

property eta¶

the “eta” as datetime.timedelta.

Return type: datetime.timedelta

property date_active¶

the attribute activityDate.

Return type: datetime.timedelta

property date_added¶

the attribute addedDate.

Return type: datetime.timedelta

property date_started¶

the attribute startDate.

Return type: datetime.timedelta

property date_done¶: the attribute “doneDate” as datetime.datetime. returns None if “doneDate” is invalid.

format_eta() → str[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>.

property download_dir¶

The download directory.

Available: transmission version 1.5.
Available: RPC version 4.

property download_limit¶

The download limit.

Can be a number or None.

property peer_limit¶: the peer limit.

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

property seed_idle_limit¶: seed idle limit in minutes.

property is_finished¶: Returns true if the torrent is finished (available from rpc version 2.0)

property is_stalled¶: Returns true if the torrent is stalled (available from rpc version 2.4)

property size_when_done¶: Size in bytes when the torrent is done

property total_size¶: Total size in bytes

property left_until_done¶: Bytes left until done

property desired_available¶: Bytes that are left to download and available

property available¶: Availability in percent

property seed_idle_mode¶

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¶

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

Return type: float

property seed_ratio_mode¶

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.

This is a mutator.

property upload_limit¶: upload limit. Can be a number or None.

property queue_position¶: queue position for this torrent.

update(timeout: Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]] = None) → None[source]¶: Update the torrent information.

start(bypass_queue: bool = False, timeout: Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]] = None) → None[source]¶: Start the torrent.

stop(timeout: Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]] = None) → None[source]¶: Stop the torrent.

move_data(location: str, timeout: Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]] = None) → None[source]¶: Move torrent data to location.

locate_data(location: str, timeout: Optional[Union[int, float, Tuple[Union[int, float], Union[int, float]]]] = None) → None[source]¶: Locate torrent data at location.

class transmission_rpc.torrent.Status(raw: str)[source]¶

A class wrap torrent status.

returned by Torrent.status

stopped: bool¶

check_pending: bool¶

checking: bool¶

download_pending: bool¶

downloading: bool¶

seed_pending: bool¶

seeding: bool¶

Errors¶

exception raise by this package

exception transmission_rpc.error.TransmissionError(message: str = '', original: Optional[requests.models.Response] = None)[source]¶: This exception is raised when there has occurred an error related to communication with Transmission.

exception transmission_rpc.error.TransmissionAuthError(message: str = '', original: Optional[requests.models.Response] = None)[source]¶: Raised when username or password is incorrect

exception transmission_rpc.error.TransmissionConnectError(message: str = '', original: Optional[requests.models.Response] = None)[source]¶: raised when client can’t connect to transmission daemon

exception transmission_rpc.error.TransmissionTimeoutError(message: str = '', original: Optional[requests.models.Response] = None)[source]¶

Utils¶

transmission_rpc.utils.format_size(size: int) → Tuple[float, str][source]¶: Format byte size into IEC prefixes, B, KiB, MiB …

transmission_rpc.utils.format_speed(size: int) → Tuple[float, str][source]¶: Format bytes per second speed into IEC prefixes, B/s, KiB/s, MiB/s …

transmission_rpc.utils.format_timedelta(delta: datetime.timedelta) → str[source]¶: Format datetime.timedelta into <days> <hours>:<minutes>:<seconds>.

transmission_rpc.utils.rpc_bool(arg: Any) → int[source]¶: Convert between Python boolean and Transmission RPC boolean.

transmission_rpc.utils.make_python_name(name: str) → str[source]¶: Convert Transmission RPC name to python compatible name.

transmission_rpc.utils.make_rpc_name(name: str) → str[source]¶: Convert python compatible name to Transmission RPC name.

transmission_rpc.utils.argument_value_convert(method: str, argument: str, value: Any, rpc_version: int) → Tuple[str, Any][source]¶: Check and fix Transmission RPC issues with regards to methods, arguments and values.

transmission_rpc.utils.get_arguments(method: str, rpc_version: int) → List[str][source]¶: Get arguments for method in specified Transmission RPC version.

Welcome to transmission-rpc’s documentation!¶

quick start¶

Arguments¶

helper¶

Client¶

Torrent ids¶

Timeouts¶

Torrent¶

Errors¶

Utils¶

Indices and tables¶