========================= libtorrent python binding ========================= :Author: Arvid Norberg, arvid@rasterbar.com .. 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.3 : /usr ; 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 boost=source release 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 `main 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::set_settings()`` not only accepts a ``session_settings`` object, but also a dictionary with keys matching the names of the members of the ``session_settings`` struct. When calling ``set_settings``, the dictionary does not need to have every settings set, keys that are not present, are set to their default value. For backwards compatibility, ``session::settings()`` still returns a ``session_settings`` struct. To get a python dictionary of the settings, call ``session::get_settings``. .. _`main library reference`: manual.html 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) h = ses.add_torrent(info, "./", storage_mode=storage_mode_sparse) while (not h.is_seed()): 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)