transmissionrpc / doc / index.rst

Full commit

Transmission RPC


This is transmissionrpc. This module helps using Python to connect to a Transmission JSON-RPC service. transmissionrpc is compatible with Transmission 1.31 and later.

transmissionrpc is licensed under the MIT license.

Getting started

Transmission is available at Python Package Index. To install the transmissionrpc python module use easy_install or pip.

$ easy_install transmissionrpc


You might need administrator privileges to install python modules.

You may also download the tarball from Python Package Index. Untar and install.

$ tar -xzf transmissionrpc-0.10.tar.gz
$ cd transmissionrpc-0.10
$ python install


transmissionrpc has the following dependencies.

Report a problem

Problems with transmissionrpc should be reported through the issue tracker at bitbucket. Please look through the existing issues before opening a new issue.

Installing from source

The source code

Transmission is hosted at bitbucket using mercurial. To get a working copy, run

$ hg clone

The source code will be fetched and stored the directory transmissionrpc.

Then install the module using

$ python install

Or if you wish to further develop transmissionrpc itself use

$ python develop

This will link this directory to the library as transmissionrpc.

Poking around

Now that transmissionrpc has been installed, run python and start to poke around. Following will create a RPC client and list all torrents.

>>> import transmissionrpc
>>> tc = transmissionrpc.Client('localhost', port=9091)
>>> tc.get_torrents()

List will return a dictionary of Torrent object indexed by their id. You might not have any torrents yet. This can be remedied by adding an torrent.

>>> tc.add_torrent('')
{1: <Torrent 1 "ubuntu-8.10-desktop-i386.iso">}
>>> tc.get_torrent(1)
{1: <Torrent 1 "ubuntu-8.10-desktop-i386.iso">}

As you saw, the add_url and info calls also returns a dictionary with {<id>: <Torrent>, ...}. More information about a torrent transfer can be found in the Torrent object.

>>> torrent = tc.get_torrent(1)[1]
>>> torrent.hashString
>>> torrent.status
>>> torrent.eta
datetime.timedelta(0, 750)
>>> for key, value in torrent.fields.iteritems():
...     print(key, value)
('comment', 'Ubuntu CD')

The last call will list all known data provided by Transmission.

Well, we weren't that interested in Ubuntu so lets stop the transfer and the remove it.

>>> tc.stop_torrent(1)
>>> tc.remove_torrent('33820db6dd5e5928d23bc811bbac2f4ae94cb882')

See what we did there? most methods in transmissionrpc can take both torrent id and torrent hash when referring to a torrent. lists and sequences are also supported.

>>> tc.get_torrents([2, 'caff87b88f50f46bc22da3a2712a6a4e9a98d91e'])
{2: <Torrent 2 "ubuntu-8.10-server-amd64.iso">, 3: <Torrent 3 "ubuntu-8.10-alternate-amd64.iso">}
>>> tc.get_torrents('1:3')
{2: <Torrent 2 "ubuntu-8.10-server-amd64.iso">, 3: <Torrent 3 "ubuntu-8.10-alternate-amd64.iso">}

Continue to explore and have fun! For more in depth information read the module reference.

A note about debugging information

If you ever need to see what's going on inside transmissionrpc, you can change the logging level of transmissionrpc. This is done with these easy steps

>>> import logging
>>> logging.getLogger('transmissionrpc').setLevel(logging.DEBUG)

Note that this will produce a whole lot of output! Other levels are (listed by severity)

  • logging.ERROR
  • logging.WARNING
  • logging.INFO
  • logging.DEBUG

The default logging level of transmissionrpc is logging.ERROR.

Module reference