docs/python_binding.html

   1 <?xml version="1.0" encoding="utf-8" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   4 <head>
   5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   6 <meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
   7 <title>libtorrent python binding</title>
   8 <meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
   9 <link rel="stylesheet" href="style.css" type="text/css" />
  10 </head>
  11 <body>
  12 <div class="document" id="libtorrent-python-binding">
  13 <h1 class="title">libtorrent python binding</h1>
  14 <table class="docinfo" frame="void" rules="none">
  15 <col class="docinfo-name" />
  16 <col class="docinfo-content" />
  17 <tbody valign="top">
  18 <tr><th class="docinfo-name">Author:</th>
  19 <td>Arvid Norberg, <a class="last reference external" href="mailto:arvid&#64;rasterbar.com">arvid&#64;rasterbar.com</a></td></tr>
  20 </tbody>
  21 </table>
  22 <div class="contents topic" id="table-of-contents">
  23 <p class="topic-title first">Table of contents</p>
  24 <ul class="simple">
  25 <li><a class="reference internal" href="#building" id="id1">building</a></li>
  26 <li><a class="reference internal" href="#using-libtorrent-in-python" id="id2">using libtorrent in python</a></li>
  27 </ul>
  28 </div>
  29 <div class="section" id="building">
  30 <h1>building</h1>
  31 <p>Building the libtorrent python bindings will produce a shared library (DLL)
  32 which is a python module that can be imported in a python program.</p>
  33 <p>The only supported build system for the bindings are currently boost build. To
  34 set up your build environment, you need to add some settings to your
  35 <tt class="docutils literal"><span class="pre">$BOOST_BUILD_PATH/user-config.jam</span></tt>.</p>
  36 <p>Make sure your user config contains the following line:</p>
  37 <pre class="literal-block">
  38 using python : 2.3 ;
  39 </pre>
  40 <p>Set the version to the version of python you have installed or want to use. If
  41 you've installed python in a non-standard location, you have to add the prefix
  42 path used when you installed python as a second option. Like this:</p>
  43 <pre class="literal-block">
  44 using python : 2.3 : /usr ;
  45 </pre>
  46 <p>The bindings require <em>at least</em> python version 2.2.</p>
  47 <p>For more information on how to install and set up boost-build, see the
  48 <a class="reference external" href="building.html#step-2-setup-bbv2">building libtorrent</a> section.</p>
  49 <p>Once you have boost-build set up, you cd to the <tt class="docutils literal"><span class="pre">bindings/python</span></tt>
  50 directory and invoke <tt class="docutils literal"><span class="pre">bjam</span></tt> with the apropriate settings. For the available
  51 build variants, see <a class="reference external" href="building.html#step-3-building-libtorrent">libtorrent build options</a>.</p>
  52 <p>For example:</p>
  53 <pre class="literal-block">
  54 $ bjam dht-support=on boost=source release link=static
  55 </pre>
  56 <p>On Mac OS X, this will produce the following python module:</p>
  57 <pre class="literal-block">
  58 bin/darwin-4.0/release/dht-support-on/link-static/logging-none/threading-multi/libtorrent.so
  59 </pre>
  60 </div>
  61 <div class="section" id="using-libtorrent-in-python">
  62 <h1>using libtorrent in python</h1>
  63 <p>The python interface is nearly identical to the C++ interface. Please refer to
  64 the <a class="reference external" href="manual.html">main library reference</a>. The main differences are:</p>
  65 <dl class="docutils">
  66 <dt>asio::tcp::endpoint</dt>
  67 <dd>The endpoint type is represented as a tuple of a string (as the address) and an int for
  68 the port number. E.g. <tt class="docutils literal"><span class="pre">('127.0.0.1',</span> <span class="pre">6881)</span></tt> represents the localhost port 6881.</dd>
  69 <dt>libtorrent::time_duration</dt>
  70 <dd>The time duration is represented as a number of seconds in a regular integer.</dd>
  71 </dl>
  72 <p>The following functions takes a reference to a container that is filled with
  73 entries by the function. The python equivalent of these functions instead returns
  74 a list of entries.</p>
  75 <ul class="simple">
  76 <li>torrent_handle::get_peer_info</li>
  77 <li>torrent_handle::file_progress</li>
  78 <li>torrent_handle::get_download_queue</li>
  79 <li>torrent_handle::piece_availability</li>
  80 </ul>
  81 <p>For an example python program, see <tt class="docutils literal"><span class="pre">client.py</span></tt> in the <tt class="docutils literal"><span class="pre">bindings/python</span></tt>
  82 directory.</p>
  83 <p>A very simple example usage of the module would be something like this:</p>
  84 <pre class="literal-block">
  85 import libtorrent as lt
  86 import time
  87
  88 ses = lt.session()
  89 ses.listen_on(6881, 6891)
  90
  91 e = lt.bdecode(open(&quot;test.torrent&quot;, 'rb').read())
  92 info = lt.torrent_info(e)
  93
  94 h = ses.add_torrent(info, &quot;./&quot;, storage_mode=storage_mode_sparse)
  95
  96 while (not h.is_seed()):
  97         s = h.status()
  98
  99         state_str = ['queued', 'checking', 'connecting', 'downloading metadata', \
 100                 'downloading', 'finished', 'seeding', 'allocating']
 101         print '%.2f%% complete (down: %.1f kb/s up: %.1f kB/s peers: %d) %s' % \
 102                 (s.progress * 100, s.download_rate / 1000, s.upload_rate / 1000, \
 103                 s.num_peers, state_str[s.state])
 104
 105         time.sleep(1)
 106 </pre>
 107 </div>
 108 </div>
 109 </body>
 110 </html>