Welcome to transmission-fluid’s documentation!

transmission-fluid is a Python wrapper around the Transmission BitTorrent client’s RPC interface.

>>> from transmission import Transmission
>>> client = Transmission()
>>> response = client('torrent-get', ids=1, fields=['name'])
>>> response['torrents']
[{u'name': u'torrent 1'}]

Getting started

transmission-fluid is available on PyPI.

Installing

Install via pip or easy_install:

$ pip install transmission-fluid

Or download the source and run python setup.py install, if that’s your thing.

transmission-fluid works with Python 2.6, 2.7, and 3.4.

It also depends on the requests library, which will be automatically installed if setuptools or distribute are available.

Creating a client

Once installed, create a client object:

>>> from transmission import Transmission
>>> client = Transmission()

By default, the client connects to localhost:9091 without authentication.

But that can be changed:

>>> client = Transmission(host='192.168.1.102', port=9090,
...                       username='foo', password='bar')

New in version 0.3: Pass ssl = True when constructing the client to use HTTPS for communication between the client and the daemon. It’s off by default.

First steps

After creating a client object, communicating with Transmission is a breeze:

>>> response = client('torrent-get', ids=[1,2,3], fields=['name'])
>>> response['torrents']
[{u'name': u'torrent 1'}, {u'name': u'torrent 2'}, {u'name': u'torrent 3'}]

This calls the torrent-get method along with the ids and fields request arguments.

No matter what RPC method you’re calling, the syntax will always be the same:

client(method_name[, **request_arguments])
Parameters:
  • method_name (string) – A method name as described in RPC specification sections 3.1 to 4.6 (e.g., torrent-start, torrent-add, session-get, etc.)
  • request_arguments – Keyword arguments as explained in the specification
Return type:

A dictionary of the “arguments” object returned from Transmission

Dashes in request arguments

Some request arguments contain dashes in their name. As this is invalid in Python, replace any dashes with underscores:

>>> client('torrent-set', ids=1, peer_limit=30) # instead of 'peer-limit'

Timestamp handling

The only area where transmission-fluid deviates from the RPC specification is when dealing with timestamps.

The RPC specification returns all date and time information as Unix timestamps. To make life easier for developers, transmission-fluid transparently converts these timestamps to UTC datetime objects:

>>> response = client('torrent-get', ids=1, fields=['addedDate'])
>>> response['torrents']
[{u'addedDate': datetime.datetime(2011, 10, 31, 20, 1, 23)}]

Similarly, you can pass datetime objects as request arguments and they’ll be converted to Unix timestamps before being transmitted to Transmission.

New in version 0.3.

Examples

Getting torrent information

Say you want the name and infohash for the first torrent in Transmission:

>>> response = client('torrent-get', ids=1, fields=['name', 'hashString']
>>> response['torrents']
[{u'hashString': u'7c44acebe5828dc53f460c312454141aa3fd1317',
  u'name': 'torrent 1'}]

You can also specify a list of IDs:

>>> response = client('torrent-get', ids=range(1,11), fields=['name', 'hashString']
>>> response['torrents']
[{u'hashString': u'7c44acebe5828dc53f460c312454141aa3fd1317',
  u'name': 'torrent 1'},
 {u'hashString': u'833e29014ed46e5ea05becc89aaaffb81d0ea9d0',
  u'name': 'torrent 2'}, ... ]

ids can also accept infohashes, if you’re already working with them:

>>> infohash = '833e29014ed46e5ea05becc89aaaffb81d0ea9d0'
>>> response = client('torrent-get', ids=infohash, fields=['name']
>>> response['torrents']
[{u'name': 'torrent 2'}]

Adding torrents

Add a torrent to Transmission by filename:

>>> client('torrent-add', filename='/path/to/file.torrent')

Removing torrents

Say you wanted to remove all torrents that were added more than 30 days ago:

>>> import datetime
>>> def is_old(torrent):
...   now = datetime.datetime.utcnow()
...   elapsed = now - torrent['addedDate']
...   return elapsed.days > 30

>>> # When no ids are given, grabs from all torrents
>>> torrents = client('torrent-get', fields=['id', 'addedDate'])['torrents']

>>> torrent_ids = [torrent['id'] for torrent in torrents if is_old(torrent)]
>>> client('torrent-remove', ids=torrent_ids)

Operate on torrents in batches

Always try to structure your program to operate on a list of torrent IDs rather than looping through a list of torrents and making an RPC call for each torrent ID.

It’s the difference between making one HTTP request with all the torrents you want to operate on and N HTTP requests with one ID at a time. The overhead can get noticable quick.

Note

The IDs don’t have to be numeric, either. If you’re using infohashes already, you can use them as-is in any ids request argument.

Developers

transmission-fluid is available on Github and contributions are welcome.

Tests and Docs

transmission-fluid tries to uphold the Python ecosystem’s commitment to well-tested and well-documented code.

As such, use tox to run the full test suite with different Python versions.

Contributions that include tests and docs will likely get acted upon sooner than contributions that don’t.

That said, if you have a bugfix or new feature for transmission-fluid but aren’t sure how to test it, just explain what you’re trying to do. We’ll try to work something out. Same goes if English isn’t your first language – just do what you can and we’ll go from there.

https://secure.travis-ci.org/edavis/transmission-fluid.png

License

MIT

Philosophy

The goal of transmission-fluid is to be a thin wrapper around Transmission’s RPC specification. It purposefully exposes most of the RPC specification for the following reasons:

Easy for developers
Once you’ve grasped Transmission’s RPC specification, you can begin using transmission-fluid immediately. Just plug in a method name and any applicable request arguments and you’re ready to go.
Stays current
As the Transmission developers add more methods and arguments, you’ll be able to use them right away instead of waiting for this wrapper to be updated to take advantage of them.

Changelog

Version 0.6 (April 26, 2014)

  • Add Python 3 support

Version 0.4 (September 7, 2013)

  • Bump requests from version 0.13.1 to 1.2.3

Version 0.3 (August 1, 2012)

  • Add SSL proxy support
  • Drop anyjson requirement
  • Automatically convert Unix timestamps to datetime objects

Version 0.2.1 (June 24, 2012)

  • Bugfix: Fix anyjson ImportError when loading setup.py

Version 0.2 (June 23, 2012)

  • Use setuptools, if available
  • Add test suite
  • Test against Python 2.6 and 2.7
  • Update documentation

Version 0.1 (June 16, 2012)

  • Initial release