=========================
libtorrent python binding
=========================

:Author: Arvid Norberg, arvid@libtorrent.org

.. contents:: Table of contents
	:depth: 2
	:backlinks: none

building
========

Building the libtorrent python bindings will produce a shared library (DLL)
which is a python module that can be imported in a python program.

building using setup.py
-----------------------

There is a ``setup.py`` shipped with libtorrent that can be used on windows.
On windows the setup.py will invoke ``bjam`` and assume that you have boost
sources at ``$BOOST_PATH``. The resulting executable is self-contained, it does
not depend any boost or libtorrent dlls.

On other systems, the setup.py is generated by running
``./configure --enable-python-binding``.

To build the Python bindings do:

1. Run::

	python setup.py build

2. As root, run::

	python setup.py install


building using boost build
--------------------------

To set up your build environment, you need to add some settings to your
``$BOOST_BUILD_PATH/user-config.jam``.

Make sure your user config contains the following line::

	using python : 2.3 ;

Set the version to the version of python you have installed or want to use. If
you've installed python in a non-standard location, you have to add the prefix
path used when you installed python as a second option. Like this::

	using python : 2.6 : /usr/bin/python2.6 : /usr/include/python2.6 : /usr/lib/python2.6 ;

The bindings require *at least* python version 2.2.

For more information on how to install and set up boost-build, see the
`building libtorrent`__ section.

.. __: building.html#step-2-setup-bbv2

Once you have boost-build set up, you cd to the ``bindings/python``
directory and invoke ``bjam`` with the apropriate settings. For the available
build variants, see `libtorrent build options`_.

.. _`libtorrent build options`: building.html#step-3-building-libtorrent

For example::

	$ bjam dht-support=on link=static

On Mac OS X, this will produce the following python module::

	bin/darwin-4.0/release/dht-support-on/link-static/logging-none/threading-multi/libtorrent.so

using libtorrent in python
==========================

The python interface is nearly identical to the C++ interface. Please refer to
the `library reference`_. The main differences are:

asio::tcp::endpoint
	The endpoint type is represented as a tuple of a string (as the address) and an int for
	the port number. E.g. ``('127.0.0.1', 6881)`` represents the localhost port 6881.

lt::time_duration
	The time duration is represented as a number of seconds in a regular integer.

The following functions takes a reference to a container that is filled with
entries by the function. The python equivalent of these functions instead returns
a list of entries.

* torrent_handle::get_peer_info
* torrent_handle::file_progress
* torrent_handle::get_download_queue
* torrent_handle::piece_availability

``create_torrent::add_node()`` takes two arguments, one string and one integer,
instead of a pair. The string is the address and the integer is the port.

``session::apply_settings()`` accepts a dictionary with keys matching the names
of settings in settings_pack.
When calling ``apply_settings``, the dictionary does not need to have every settings set,
keys that are not present are not updated.

To get a python dictionary of the settings, call ``session::get_settings``.

.. _`library reference`: reference.html

Retrieving session statistics in Python is more convenient than that in C++.
The statistics are stored as an array in ``session_stats_alert``, which will be posted after calling ``post_session_stats()`` in the ``session`` object.
In order to interpret the statistics array, in C++ it is required to call ``session_stats_metrics()`` to get the indices of these metrics, while in Python it can be done using ``session_stats_alert.values["NAME_OF_METRIC"]``, where ``NAME_OF_METRIC`` is the name of a metric.

For an example python program, see ``client.py`` in the ``bindings/python``
directory.

A very simple example usage of the module would be something like this::

	import libtorrent as lt
	import time

	ses = lt.session()
	ses.listen_on(6881, 6891)

	e = lt.bdecode(open("test.torrent", 'rb').read())
	info = lt.torrent_info(e)

	params = { 'save_path': '.', \
		'storage_mode': lt.storage_mode_t.storage_mode_sparse, \
		'ti': info }
	h = ses.add_torrent(params)

	s = h.status()
	while (not s.is_seeding):
		s = h.status()

		state_str = ['queued', 'checking', 'downloading metadata', \
			'downloading', 'finished', 'seeding', 'allocating']
		print '%.2f%% complete (down: %.1f kb/s up: %.1f kB/s peers: %d) %s' % \
			(s.progress * 100, s.download_rate / 1000, s.upload_rate / 1000, \
			s.num_peers, state_str[s.state])

		time.sleep(1)