Welcome to transmission-rpc’s documentation!

transmission-rpc is a python3 library to help your control your transmission deamon 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(address='localhost', port=9091,
                  user='transmission', password='password')
c.add_torrent(torrent_url)

########

from transmission_rpc import Client, DEFAULT_PORT

c = Client(port=DEFAULT_PORT,
           user='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(user='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

class transmission_rpc.client.Client(address='localhost', port=9091, user=None, password=None, timeout=None, logger=<logging.Logger object>)

Client is the class handling the Transmission JSON-RPC client protocol.

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

Add torrent to transfers list. Takes a uri to a torrent or base64 encoded torrent data in torrent. 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)

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.

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:

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)

timeout

HTTP query timeout.

verify_torrent(ids, timeout=None)

verify torrent(s) with provided id(s)

Utils

class transmission_rpc.utils.Field(value, dirty)

dirty

Alias for field number 1

value

Alias for field number 0

exception transmission_rpc.utils.INetAddressError

Error parsing / generating a internet address.

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)

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

transmission_rpc.utils.format_speed(size)

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

transmission_rpc.utils.format_timedelta(delta)

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

transmission_rpc.utils.format_timestamp(timestamp, utc=False)

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.inet_address(address, default_port, default_address='localhost')

Parse internet address.

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)

Convert between Python boolean and Transmission RPC boolean.

Indices and tables

• Index
• Module Index
• Search Page