| Author: | Arvid Norberg, [email protected] |
|---|
Table of contents
Building the libtorrent python bindings will produce a shared library (DLL) which is a python module that can be imported in a python program.
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:
Run:
python setup.py build
As root, run:
python setup.py install
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
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.
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: