docs/python_binding.rst

   1 =========================
   2 libtorrent python binding
   3 =========================
   4
   5 :Author: Arvid Norberg, arvid@rasterbar.com
   6
   7 .. contents:: Table of contents
   8         :depth: 2
   9         :backlinks: none
  10
  11 building
  12 ========
  13
  14 Building the libtorrent python bindings will produce a shared library (DLL)
  15 which is a python module that can be imported in a python program.
  16
  17 The only supported build system for the bindings are currently boost build. To
  18 set up your build environment, you need to add some settings to your
  19 ``$BOOST_BUILD_PATH/user-config.jam``.
  20
  21 Make sure your user config contains the following line::
  22
  23         using python : 2.3 ;
  24
  25 Set the version to the version of python you have installed or want to use. If
  26 you've installed python in a non-standard location, you have to add the prefix
  27 path used when you installed python as a second option. Like this::
  28
  29         using python : 2.3 : /usr ;
  30
  31 The bindings require *at least* python version 2.2.
  32
  33 For more information on how to install and set up boost-build, see the
  34 `building libtorrent`_ section.
  35
  36 .. _`building libtorrent`: building.html#step-2-setup-bbv2
  37
  38 Once you have boost-build set up, you cd to the ``bindings/python``
  39 directory and invoke ``bjam`` with the apropriate settings. For the available
  40 build variants, see `libtorrent build options`_.
  41
  42 .. _`libtorrent build options`: building.html#step-3-building-libtorrent
  43
  44 For example::
  45
  46         $ bjam dht-support=on boost=source release link=static
  47
  48 On Mac OS X, this will produce the following python module::
  49
  50         bin/darwin-4.0/release/dht-support-on/link-static/logging-none/threading-multi/libtorrent.so
  51
  52 using libtorrent in python
  53 ==========================
  54
  55 The python interface is nearly identical to the C++ interface. Please refer to
  56 the `main library reference`_. The main differences are:
  57
  58 asio::tcp::endpoint
  59         The endpoint type is represented as a tuple of a string (as the address) and an int for
  60         the port number. E.g. ``('127.0.0.1', 6881)`` represents the localhost port 6881.
  61
  62 libtorrent::time_duration
  63         The time duration is represented as a number of seconds in a regular integer.
  64
  65 The following functions takes a reference to a container that is filled with
  66 entries by the function. The python equivalent of these functions instead returns
  67 a list of entries.
  68
  69 * torrent_handle::get_peer_info
  70 * torrent_handle::file_progress
  71 * torrent_handle::get_download_queue
  72 * torrent_handle::piece_availability
  73
  74
  75 .. _`main library reference`: manual.html
  76
  77 For an example python program, see ``client.py`` in the ``bindings/python``
  78 directory.
  79
  80 A very simple example usage of the module would be something like this::
  81
  82         import libtorrent as lt
  83         import time
  84
  85         ses = lt.session()
  86         ses.listen_on(6881, 6891)
  87
  88         e = lt.bdecode(open("test.torrent", 'rb').read())
  89         info = lt.torrent_info(e)
  90
  91         h = ses.add_torrent(info, "./", storage_mode=storage_mode_sparse)
  92
  93         while (not h.is_seed()):
  94                 s = h.status()
  95
  96                 state_str = ['queued', 'checking', 'connecting', 'downloading metadata', \
  97                         'downloading', 'finished', 'seeding', 'allocating']
  98                 print '%.2f%% complete (down: %.1f kb/s up: %.1f kB/s peers: %d) %s' % \
  99                         (s.progress * 100, s.download_rate / 1000, s.upload_rate / 1000, \
 100                         s.num_peers, state_str[s.state])
 101
 102                 time.sleep(1)
 103