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


TorrentPatron - A BitTorrent Client

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.

Known quirks

  • Clear out your ~/.bittorrent/ directory if you get errors about torrents including files that are part of other torrents.
  • Files can only be downloaded to/uploaded from within the current directory

This component is for downloading and uploading data using the peer-to-peer BitTorrent protocol.

Use this component in preference to TorrentClient.

This component uses a TorrentService component to co-ordinate the sharing of a single TorrentClient between many TorrentPatrons. This is necessary as running more than one instance of TorrentClient will fail (see TorrentClient.py for a full explanation).

How does it work?

When TorrentPatron is first run, it will get a TorrentService object - if one already exists it will pick that, otherwise it will create a new one. It then registers itself with this service allowing it to receive messages from it. Messages TorrentPatron receives on its inbox are forwarded to TorrentService (in a TIPCServicePassOn wrapper) which in turn forwards them to TorrentClient. Messages generated by TorrentClient relevant to the torrents started by this instance of TorrentPatron are forwarded to it by TorrentService.

The result of this is that inboxes/outboxes used and the IPC messages accepted/ produced are identical to TorrentClient.

These IPC messages may be found in TorrentIPC.py

Those used internally: * TIPCServicePassOn - used to wrap messages from TorrentPatron for TorrentClient * TIPCServiceAdd - register this TorrentPatron with a TorrentService * TIPCServiceRemove - deregister this TorrentPatron with a TorrentService

Those used externally (i.e. seen/sent by user components):

  • Send to TorrentPatron:
    • TIPCCreateNewTorrent - start a new torrent from the contents of a .torrent file
    • TIPCCloseTorrent - stop a running torrent
  • Sent by TorrentPatron:
    • TIPCNewTorrentCreated - a new torrent has been started from your (oldest) TIPCCreateNewTorrent message
    • TIPCTorrentStartFail - the torrent associated with your (oldest) TIPCCreateNewTorrent message could not be started
    • TIPCTorrentAlreadyDownloading - the torrent associated with your (oldest) TIPCCreateNewTorrent message is already downloading
    • TIPCTorrentStatusUpdate - a status object for one of your active torrents


class TorrentPatron(Axon.Component.component)

Inboxes/outboxes and message behaviour identical to TorrentClient but thread-safe so you can create many of these.


  • torrent-inbox : Received feedback from TorrentClient
  • control : Shut me down
  • inbox : Commands for the TorrentClient


  • outbox : Forward feedback from TorrentClient out of
  • torrent-outbox : Talk to TorrentClient with
  • signal : producerFinished sent 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.


Main loop of TorrentPatron


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