# libtorrent python binding

Author: | Arvid Norberg, arvid@libtorrent.org

Table of contents

- building
  - building using setup.py
  - building using boost build
- using libtorrent in python

# 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.

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.

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.
libtorrent::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`.

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:

System Message: WARNING/2 (`python_binding.rst`, line 115)

Cannot analyze code. Pygments package not found.

    .. include:: ../bindings/python/simple_client.py
            :code: python
            :tab-width: 2
            :start-after: from __future__ import print_function