Welcome to transmission-rpc’s documentation!

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

python2 has be deprecated in 1.0.0

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, user='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 official rpc spec or mirror here

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: str = 'http', username: str = None, password: str = None, host: str = '127.0.0.1', port: int = 9091, path: str = '/transmission/', timeout: Union[int, float] = 30.0, logger=<Logger transmission-rpc (ERROR)>)

add_torrent(torrent, timeout=None, **kwargs)

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

Additional arguments are:

Argument	RPC	Replaced by	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.

blocklist_update(timeout=None)

Update block list. Returns the size of the block list.

change_torrent(ids, timeout=None, **kwargs)

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.

Note

transmission_rpc will try to automatically fix argument errors.

free_space(path, timeout=None)

Get the amount of free space (in bytes) at the provided location.

get_files(ids=None, timeout=None)

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.

{
        <torrent id>: {
                <file id>: {
                        'name': <file name>,
                        'size': <file size in bytes>,
                        'completed': <bytes completed>,
                        'priority': <priority ('high'|'normal'|'low')>,
                        'selected': <selected for download (True|False)>
                }

                ...
        }

        ...
}

get_session(timeout=None)

Get session parameters. See the Session class for more information.

get_torrent(torrent_id, arguments=None, timeout=None)

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.

Returns a Torrent object with the requested fields.

get_torrents(ids=None, arguments=None, timeout=None) → List[transmission_rpc.torrent.Torrent]

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

Returns a list of Torrent object. :type ids: Union[int, str] :rtype : list[Torrent]

locate_torrent_data(ids, location, timeout=None)

Locate torrent data at the provided location.

move_torrent_data(ids, location, timeout=None)

Move torrent data to the new location.

port_test(timeout=None)

Tests to see if your incoming peer port is accessible from the outside world.

queue_bottom(ids, timeout=None)

Move transfer to the bottom of the queue.

queue_down(ids, timeout=None)

Move transfer down in the queue.

queue_top(ids, timeout=None)

Move transfer to the top of the queue.

queue_up(ids, timeout=None)

Move transfer up in the queue.

reannounce_torrent(ids, timeout=None)

Reannounce torrent(s) with provided id(s)

remove_torrent(ids, delete_data=False, timeout=None)

remove torrent(s) with provided id(s). Local data is removed if delete_data is True, otherwise not.

rename_torrent_path(torrent_id, location, name, timeout=None)

Rename directory and/or files for torrent. Remember to use get_torrent or get_torrents to update your file information.

property rpc_version

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

session_stats(timeout=None)

Get session statistics

set_files(items, timeout=None)

Set file properties. Takes a dictionary with similar contents as the result of get_files.

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

                ...
        }

        ...
}

set_session(timeout=None, **kwargs)

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.

start_all(bypass_queue=False, timeout=None)

Start all torrents respecting the queue order

start_torrent(ids, bypass_queue=False, timeout=None)

Start torrent(s) with provided id(s)

stop_torrent(ids, timeout=None)

stop torrent(s) with provided id(s)

property timeout

Get current timeout for HTTP queries.

verify_torrent(ids, timeout=None)

verify torrent(s) with provided id(s)

Torrent

class transmission_rpc.torrent.Torrent(client, fields)

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 date_active

the attribute “activityDate” as datetime.datetime.

property date_added

the attribute “addedDate” as datetime.datetime.

property date_done

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

property date_started

the attribute “startDate” as datetime.datetime.

property download_limit

The download limit.

Can be a number or None.

property eta

the “eta” as datetime.timedelta.

files()

Get list of files for this torrent.

This function returns a dictionary with file information for each file. The file information is has following fields:

{
    <file id>: {
        'name': <file name>,
        'size': <file size in bytes>,
        'completed': <bytes completed>,
        'priority': <priority ('high'|'normal'|'low')>,
        'selected': <selected for download>
    }
    ...
}

format_eta()

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

locate_data(location, timeout=None)

Locate torrent data at location.

move_data(location, timeout=None)

Move torrent data to location.

property peer_limit

the peer limit.

property priority

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

property progress

download progress in percent.

property queue_position

queue position for this torrent.

property ratio

upload/download ratio.

property seed_idle_limit

seed idle limit in minutes.

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.

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.

start(bypass_queue=False, timeout=None)

Start the torrent.

property status

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

stop(timeout=None)

Stop the torrent.

update(timeout=None)

Update the torrent information.

property upload_limit

upload limit. Can be a number or None.

Utils

class transmission_rpc.utils.Field(value, dirty)

property dirty

Alias for field number 1

property value

Alias for field number 0

transmission_rpc.utils.argument_value_convert(method, argument, value, rpc_version)

Check and fix Transmission RPC issues with regards to methods, arguments and values.

transmission_rpc.utils.format_size(size: int) → Tuple[float, str]

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

transmission_rpc.utils.format_speed(size: int) → Tuple[float, str]

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

transmission_rpc.utils.format_timedelta(delta: datetime.timedelta) → str

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

transmission_rpc.utils.format_timestamp(timestamp: int, utc=False) → str

Format unix timestamp into ISO date format.

transmission_rpc.utils.get_arguments(method, rpc_version)

Get arguments for method in specified Transmission RPC version.

transmission_rpc.utils.make_python_name(name)

Convert Transmission RPC name to python compatible name.

transmission_rpc.utils.make_rpc_name(name)

Convert python compatible name to Transmission RPC name.

transmission_rpc.utils.rpc_bool(arg: Any) → int

Convert between Python boolean and Transmission RPC boolean.

Indices and tables

• Index

• Module Index

• Search Page