Low-Level Protocol Classes

build_tor_connection

txtorcon.build_tor_connection(connection, build_state=True, wait_for_proto=True, password_function=<function <lambda>>)

This is used to build a valid TorState (which has .protocol for the TorControlProtocol). For example:

from twisted.internet import reactor
from twisted.internet.endpoints import TCP4ClientEndpoint
import txtorcon

def example(state):
    print "Fully bootstrapped state:",state
    print "   with bootstrapped protocol:",state.protocol

d = txtorcon.build_tor_connection(TCP4ClientEndpoint(reactor,
                                                     "localhost",
                                                     9051))
d.addCallback(example)
reactor.run()
Parameters:

  • password_function – See txtorcon.TorControlProtocol

  • build_state – If True (the default) a TorState object will be built as well. If False, just a TorControlProtocol will be returned via the Deferred.

Returns:

a Deferred that fires with a TorControlProtocol or, if you specified build_state=True, a TorState. In both cases, the object has finished bootstrapping (i.e. TorControlProtocol.post_bootstrap or TorState.post_bootstap has fired, as needed)

build_local_tor_connection

txtorcon.build_local_tor_connection(reactor, host='127.0.0.1', port=9051, socket='/var/run/tor/control', *args, **kwargs)

This builds a connection to a local Tor, either via 127.0.0.1:9051 or /var/run/tor/control (by default; the latter is tried first). See also build_tor_connection for other key-word arguments that are accepted here also.

Note: new code should use txtorcon.connect() instead.

Parameters:

  • host – An IP address to find Tor at. Corresponds to the ControlListenAddress torrc option.

  • port – The port to use with the address when trying to contact Tor. This corresponds to the ControlPort option in torrc (default is 9051).

TorControlProtocol

class txtorcon.TorControlProtocol(password_function=None)

This is the main class that talks to a Tor and implements the “raw” procotol.

This instance does not track state; see txtorcon.TorState for the current state of all Circuits, Streams and Routers.

txtorcon.TorState.build_circuit() allows you to build custom circuits.

txtorcon.TorControlProtocol.add_event_listener() can be used to listen for specific events.

To see how circuit and stream listeners are used, see txtorcon.TorState, which is also the place to go if you wish to add your own stream or circuit listeners.

Parameters:

password_function – A zero-argument callable which returns a password (or Deferred). It is only called if the Tor doesn’t have COOKIE authentication turned on. Tor’s default is COOKIE.

TorProtocolFactory

class txtorcon.TorProtocolFactory(password_function=<function TorProtocolFactory.<lambda>>)

Builds TorControlProtocol objects. Implements IProtocolFactory for Twisted interaction.

If your running Tor doesn’t support COOKIE authentication, then you should supply a password callback.

Builds protocols to talk to a Tor client on the specified address. For example:

ep = TCP4ClientEndpoint(reactor, "localhost", 9051)
ep.connect(TorProtocolFactory())
reactor.run()

By default, COOKIE authentication is used if available.

Parameters:

password_function – If supplied, this is a zero-argument method that returns a password (or a Deferred). By default, it returns None. This is only queried if the Tor we connect to doesn’t support (or hasn’t enabled) COOKIE authentication.

TorProcessProtocol

class txtorcon.TorProcessProtocol(connection_creator, progress_updates=None, config=None, ireactortime=None, timeout=None, kill_on_stderr=True, stdout=None, stderr=None)

This will read the output from a Tor process and attempt a connection to its control port when it sees any ‘Bootstrapped’ message on stdout. You probably don’t need to use this directly except as the return value from the txtorcon.launch_tor() method. tor_protocol contains a valid txtorcon.TorControlProtocol instance by that point.

connection_creator is a callable that should return a Deferred that callbacks with a txtorcon.TorControlProtocol; see txtorcon.launch_tor() for the default one which is a functools.partial that will call connect(TorProtocolFactory()) on an appropriate twisted.internet.endpoints.TCP4ClientEndpoint

Parameters:

  • connection_creator – A no-parameter callable which returns a Deferred which promises a IStreamClientEndpoint. If this is None, we do NOT attempt to connect to the underlying Tor process.

  • progress_updates – A callback which received progress updates with three args: percent, tag, summary

  • config – a TorConfig object to connect to the TorControlProtocl from the launched tor (should it succeed)

  • ireactortime – An object implementing IReactorTime (i.e. a reactor) which needs to be supplied if you pass a timeout.

  • timeout – An int representing the timeout in seconds. If we are unable to reach 100% by this time we will consider the setting up of Tor to have failed. Must supply ireactortime if you supply this.

  • kill_on_stderr – When True, kill subprocess if we receive anything on stderr

  • stdout – Anything subprocess writes to stdout is sent to .write() on this

  • stderr – Anything subprocess writes to stderr is sent to .write() on this

Variables:

tor_protocol – The TorControlProtocol instance connected to the Tor this ProcessProtocol>` is speaking to. Will be valid after the Deferred returned from TorProcessProtocol.when_connected() is triggered.