
txtorcon
********

txtorcon is a Twisted-based Python asynchronous controller library for
Tor, following control-spec. This would be of interest to anyone
wishing to write event-based software in Python that talks to a Tor
program.

The main code is under 2000 lines according to ohcount, or 4500 lines
including tests. Some features and motivating examples:

   * "txtorcon.TorControlProtocol" implements the control-spec
     protocol (only)
        * see *monitor.py* which listens for events (SETEVENT ones)

   * "txtorcon.TorState" tracks state for you: all Routers, Streams
     and Circuits, with listeners
        * see *stream_circuit_logger.py* which logs all stream and
          circuit activity

   * "txtorcon.TorConfig" tracks and allows updating of config with
     attribute-style acccess (including hidden services):
        * "print config.ORPort"

        * "config.HiddenServices.append(HiddenService(config,
          '/hidden/service/dir', ['80 127.0.0.1:1234']))"

        * "config.SocksPort = 9052"

        * see *dump_config.py*

        * see also *launch_tor_with_hiddenservice.py*

   * helpers to launch new slave Tor instances
        * uses TAKEOWNERSHIP and __OwningControllerProcess (killing
          connection causes Tor to exit)

        * see *launch_tor.py*

        * see *launch_tor_with_hiddenservice.py*

   * *txtorcon.TCPHiddenServiceEndpoint* to simplify hidden service
     listening into Twisteds endpoint paradigm.
        * see *launch_tor_endpoint.py*

The canonical URI is http://timaq4ygg2iegci7.onion Code available at
https://github.com/meejah/txtorcon

* meejah@meejah.ca (public key: meejah.asc)

* "git clone git://github.com/meejah/txtorcon.git"

* **``pip install txtorcon``**

This documentation was generated May 25, 2013.


Known Users:
============

   * APAF anonymous Python application framework

   * OONI the Open Observatory of Network Interference


Get the Code:
=============

* Releases
  * unreleased
  * v0.8.1
  * v0.8.0
  * v0.7
  * v0.6
  * v0.5
  * v0.4
  * v0.3
  * v0.2
  * v0.1

Documentation
=============

* Introduction
* txtorcon README
  * quick start
  * overview
  * quick implementation overview
  * dependencies
  * documentation
  * contact information
* Examples
  * "disallow_streams_by_port.py"
  * "launch_tor.py"
  * "launch_tor_endpoint.py"
  * "launch_tor_with_hiddenservice.py"
  * "stream_circuit_logger.py"
  * "circuit_for_next_stream.py"
  * "attach_streams_by_country.py"
  * "schedule_bandwidth.py"
  * "dump_config.py"
  * "monitor.py"
  * "circuit_failure_rates.py"
  * "txtorcon.tac"

API Docs:
=========

* txtorcon Package
  * Protocol and Helper Classes
    * TorControlProtocol
    * TorProtocolFactory
    * TorProcessProtocol
    * TCPHiddenServiceEndpoint
  * State-Tracking Classes
    * build_tor_connection
    * TorState
    * Circuit
    * Stream
    * Router
  * Launching Tor
    * TorProcessProtocol
    * TCPHiddenServiceEndpoint
    * launch_tor
  * "txtorcon.interface" Module
    * interface.IStreamAttacher
    * interface.IStreamListener
    * interface.ICircuitListener
    * interface.ICircuitContainer
    * interface.IRouterContainer
    * interface.ITorControlProtocol
  * "txtorcon.util" Module
    * util.NetLocation
    * util.process_from_address
    * util.delete_file_or_tree

Indices and tables
******************

* *Index*

* *Module Index*

* *Search Page*
