April 2024 - This site, and Kamaelia are being updated. There is significant work needed, and PRs are welcome.


TorrentClient - a BitTorrent Client

This component is for downloading and uploading data using the peer-to-peer BitTorrent protocol. You MUST have the Mainline (official) BitTorrent client installed for any BitTorrent stuff to work in Kamaelia.

NOTE: This code has only been successfully tested with version 4.20.8. Problems have been experienced with other more recent versions regarding a missing or misplaced language translations file. See http://download.bittorrent.com/dl/?M=D and download the appropriate version 4.20.8 package for for your platform.

Use TorrentPatron instead!

I should start by saying "DO NOT USE THIS COMPONENT YOURSELF"!

This component wraps the Mainline (official) BitTorrent client, which unfortunately is not thread-safe (at least with the latest version - 4.20). If you run two instances of this client simultaneously, Python will die with an exception, or if you're really unlucky, a segfault.

But despair not! There is a solution - use TorrentPatron instead. TorrentPatrons will organise the sharing of a single TorrentClient amongst themselves and expose exactly the same interface (except that the tickInterval optional argument cannot be set) with the key advantage that you can run as many of them as you want.

For a description of the interfaces of TorrentClient see TorrentPatron

How does it work?

TorrentClient is a threadedcomponent that uses the libraries of the Mainline (official) BitTorrent client to provide BitTorrent functionality. As Mainline was designed to block (use blocking function calls) this makes it incompatible with the normal structure of an Axon component - it cannot yield regularly. As such it uses a threadedcomponent, allowing it to block with impunity.

Each torrent is assigned a unique id (currently equal to the count of torrents seen but don't rely on it). Inboxes are checked periodically (every tickInterval seconds, where tickInterval is 5 by default)


prefab: BasicTorrentExplainer

BasicTorrentExplainer is component useful for debugging TorrentClient/TorrentPatron. It converts each torrent IPC messages it receives into human readable lines of text.


class TorrentClient(Axon.ThreadedComponent.threadedcomponent)

TorrentClient([tickInterval]) -> component capable of downloading/sharing torrents.

Initialises the Mainline client. Uses threadedcomponent so it doesn't have to worry about blocking I/O or making Mainline yield periodically.

Keyword arguments:

  • tickInterval -- the interval in seconds at which TorrentClient checks inboxes (default=5)


  • control : Shut me down
  • inbox : Torrent IPC - add a torrent, stop a torrent etc.


  • outbox : Torrent IPC - status updates, completion, new torrent added etc.
  • signal : Say when I've shutdown

Methods defined here


You should be using the inbox/outbox interface, not these methods (except construction). This documentation is designed as a roadmap as to their functionalilty for maintainers and new component developers.

__init__(self[, tickInterval])

_create_torrent(self, metainfo, save_incomplete_as, save_as)

_start_torrent(self, metainfo, torrentid)

decodeTorrent(self, data)

Converts bencoded raw metadata (as one would find in a .torrent file) into a metainfo object (which one can then get the torrent's properties from).



Start the Mainline client and block indefinitely, listening for connectons.


Send a TIPCTorrentStatusUpdate for each running torrent.

startTorrent(self, metainfo, save_incomplete_as, save_as, torrentid)

startTorrent causes MultiTorrent to begin downloading a torrent eventually. Use it instead of _start_torrent as it retries repeatedly if Mainline is busy.


Called periodically... by itself (gets rawserver to call it back after a delay of tickInterval seconds). Checks inboxes and sends a status-update message for every active torrent.


Got a problem with the documentation? Something unclear that could be clearer? Want to help improve it? Constructive criticism is very welcome - especially if you can suggest a better rewording!

Please leave you feedback here in reply to the documentation thread in the Kamaelia blog.

-- Automatic documentation generator, 05 Jun 2009 at 03:01:38 UTC/GMT