File: index.rst

package info (click to toggle)
transmissionrpc 0.11-1%2Bdeb8u1
  • links: PTS, VCS
  • area: main
  • in suites: jessie
  • size: 572 kB
  • ctags: 312
  • sloc: python: 2,330; makefile: 15
file content (177 lines) | stat: -rwxr-xr-x 4,760 bytes parent folder | download | duplicates (4)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
..
    Copyright (c) 2008-2013 Erik Svensson <erik.public@gmail.com>
    Licensed under the MIT license.

Transmission RPC
################

Introduction
============

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.

.. _Transmission: http://www.transmissionbt.com/

Getting started
===============

Transmission is available at
`Python Package Index <http://pypi.python.org/pypi/transmissionrpc/>`_. To
install the transmissionrpc python module use easy_install or pip.

::

    $ easy_install transmissionrpc

.. NOTE::
	You might need administrator privileges to install python modules.

You may also download the tarball from `Python Package Index <http://pypi.python.org/pypi/transmissionrpc/>`_. Untar and install.

::

    $ tar -xzf transmissionrpc-0.11.tar.gz
    $ cd transmissionrpc-0.11
    $ python setup.py install

Dependecies
-----------

transmissionrpc has the following dependencies.

 * Python >= 2.6
 * Six >= 1.1.0, https://pypi.python.org/pypi/six/

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

.. _existing issues: http://bitbucket.org/blueluna/transmissionrpc/issues/
.. _new issue: http://bitbucket.org/blueluna/transmissionrpc/issues/new/

Installing from source
======================

The source code
---------------

Transmission is hosted at bitbucket_ using mercurial_. To get a working copy,
run
::

   $ hg clone http://www.bitbucket.org/blueluna/transmissionrpc/

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

Then install the module using
::

    $ python setup.py install

Or if you wish to further develop transmissionrpc itself use
::

	$ python setup.py develop

This will link this directory to the library as transmissionrpc.

.. _bitbucket: http://www.bitbucket.org/blueluna/transmissionrpc/
.. _mercurial: http://www.selenic.com/mercurial

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('http://releases.ubuntu.com/8.10/ubuntu-8.10-desktop-i386.iso.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.name
    'ubuntu-8.10-desktop-i386.iso'
    >>> torrent.hashString
    '33820db6dd5e5928d23bc811bbac2f4ae94cb882'
    >>> torrent.status
    'downloading'
    >>> torrent.eta
    datetime.timedelta(0, 750)

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

.. toctree::
   :maxdepth: 2

   reference/transmissionrpc

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`