# 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.