[Pkg-privacy-commits] [txtorcon] 90/96: Imported Upstream version 0.13.0
Jérémy Bobbio
lunar at moszumanska.debian.org
Sun Sep 6 18:34:05 UTC 2015
This is an automated email from the git hooks/post-receive script.
lunar pushed a commit to branch master
in repository txtorcon.
commit b1015c5a860123e2eaf66abeec6cd69fedfb2e0d
Merge: cf88688 7c8f4f2
Author: Jérémy Bobbio <lunar at debian.org>
Date: Fri Aug 28 22:15:33 2015 +0200
Imported Upstream version 0.13.0
Makefile | 14 +-
PKG-INFO | 21 +-
README.rst | 19 +-
dev-requirements.txt | 4 +
docs/index.rst | 19 +-
docs/release-checklist.rst | 17 +-
docs/releases.rst | 47 +-
docs/txtorcon-config.rst | 2 +-
docs/txtorcon-endpoints.rst | 6 +-
docs/txtorcon-state.rst | 2 +-
docs/walkthrough.rst | 32 +-
examples/add_hiddenservice_to_system_tor.py | 81 ---
examples/disallow_streams_by_port.py | 4 +-
examples/dump_config.py | 4 +-
examples/hidden_echo.py | 3 +-
examples/launch_tor.py | 76 +--
examples/launch_tor2web.py | 47 ++
examples/launch_tor_endpoint.py | 19 +-
examples/launch_tor_endpoint2.py | 13 +-
examples/launch_tor_with_hiddenservice.py | 64 ++-
examples/list_circuits.py | 20 +
examples/monitor.py | 6 +-
examples/multiple-socks-ports.py | 42 ++
examples/schedule_bandwidth.py | 6 +-
examples/stream_circuit_logger.py | 27 +-
examples/tor_info.py | 34 +-
examples/torflow_path_selection.py | 93 ++++
examples/webui_server.py | 30 +-
setup.py | 4 +-
test/profile_startup.py | 14 +-
test/test_addrmap.py | 49 +-
test/test_circuit.py | 66 ++-
test/test_endpoints.py | 165 ++++--
test/test_fsm.py | 7 +
test/test_router.py | 41 +-
test/test_stream.py | 96 ++--
test/test_torconfig.py | 685 ++++++++++++++++++++-----
test/test_torcontrolprotocol.py | 175 +++++--
test/test_torinfo.py | 71 ++-
test/test_torstate.py | 273 ++++++----
test/test_util.py | 65 ++-
test/test_util_imports.py | 13 +-
test/util.py | 4 +-
txtorcon.egg-info/PKG-INFO | 21 +-
txtorcon.egg-info/SOURCES.txt | 5 +-
txtorcon.egg-info/requires.txt | 2 +-
txtorcon/__init__.py | 30 +-
txtorcon/addrmap.py | 8 +-
txtorcon/circuit.py | 26 +-
txtorcon/endpoints.py | 116 +++--
txtorcon/interface.py | 8 +-
txtorcon/router.py | 21 +-
txtorcon/spaghetti.py | 9 +-
txtorcon/stream.py | 39 +-
txtorcon/torconfig.py | 759 +++++++++++++++++++---------
txtorcon/torcontrolprotocol.py | 200 +++++---
txtorcon/torinfo.py | 100 ++--
txtorcon/torstate.py | 276 +++++-----
txtorcon/util.py | 21 +-
59 files changed, 2821 insertions(+), 1300 deletions(-)
diff --cc PKG-INFO
index 97b2645,0000000..9cd2ccb
mode 100644,000000..100644
--- a/PKG-INFO
+++ b/PKG-INFO
@@@ -1,274 -1,0 +1,277 @@@
+Metadata-Version: 1.1
+Name: txtorcon
- Version: 0.11.0
++Version: 0.13.0
+Summary: Twisted-based Tor controller client, with state-tracking and configuration abstractions.
+Home-page: https://github.com/meejah/txtorcon
+Author: meejah
+Author-email: meejah at meejah.ca
+License: MIT
+Description: README
+ ======
+
+ Documentation at https://txtorcon.readthedocs.org
+
+ .. image:: https://travis-ci.org/meejah/txtorcon.png?branch=master
+ :target: https://www.travis-ci.org/meejah/txtorcon
+
+ .. image:: https://coveralls.io/repos/meejah/txtorcon/badge.png
+ :target: https://coveralls.io/r/meejah/txtorcon
+
+ .. image:: http://api.flattr.com/button/flattr-badge-large.png
+ :target: http://flattr.com/thing/1689502/meejahtxtorcon-on-GitHub
+
+
+ quick start
+ -----------
+
+ For the impatient, there are two quick ways to install this::
+
+ $ pip install txtorcon
+
- (Thanks to Lunar^ for all his packaging work) or, if you checked out
- or downloaded the source::
++ ... or, if you checked out or downloaded the source::
+
+ $ python setup.py install
+
+ To avoid installing, you can just add the base of the source to your
+ PYTHONPATH::
+
+ $ export PYTHONPATH=`pwd`:$PYTHONPATH
+
+ Then, you will want to explore the examples. Try "python
+ examples/stream\_circuit\_logger.py" for instance.
+
- On Debian testing (jessie), or with wheezy-backports you can install
- version 0.8.2::
++ On Debian testing (jessie), or with wheezy-backports (big thanks to
++ Lunar^ for all his packaging work) you can install easily::
+
+ $ apt-get install python-txtorcon
+
+ You may also like `this asciinema demo <http://asciinema.org/a/5654>`_
+ for an overview.
+
+ Tor configuration
+ -----------------
+
+ You'll want to have the following options on in your ``torrc``::
+
+ CookieAuthentication 1
+ CookieAuthFileGroupReadable 1
+
+ If you want to use unix sockets to speak to tor::
+
+ ControlSocketsGroupWritable 1
+ ControlSocket /var/run/tor/control
+
- The defaults used by :meth:`txtorcon.build_local_tor_connection` will
++ The defaults used by py:meth:`txtorcon.build_local_tor_connection` will
+ find a Tor on ``9051`` or ``/var/run/tor/control``
+
+
+ overview
+ --------
+
+ txtorcon is a Twisted-based asynchronous Tor control protocol
+ implementation. Twisted is an event-driven networking engine written
+ in Python and Tor is an onion-routing network designed to improve
+ people's privacy and anonymity on the Internet.
+
+ The main abstraction of this library is txtorcon.TorControlProtocol
+ which presents an asynchronous API to speak the Tor client protocol in
+ Python. txtorcon also provides abstractions to track and get updates
+ about Tor's state (txtorcon.TorState) and current configuration
+ (including writing it to Tor or disk) in txtorcon.TorConfig, along
+ with helpers to asynchronously launch slave instances of Tor including
+ Twisted endpoint support.
+
+ txtorcon runs all tests cleanly on:
+
+ - Debian "squeeze", "wheezy" and "jessie"
+ - OS X 10.4 (naif)
+ - OS X 10.8 (lukas lueg)
+ - OS X 10.9 (kurt neufeld)
+ - Fedora 18 (lukas lueg)
+ - FreeBSD 10 (enrique fynn) (**needed to install "lsof"**)
+ - RHEL6
+ - Reports from other OSes appreciated.
+
+ If instead you want a synchronous (threaded) Python controller
+ library, check out Stem at https://stem.torproject.org/
+
+ quick implementation overview
+ -----------------------------
+
+ txtorcon provides a class to track Tor's current state -- such as
+ details about routers, circuits and streams -- called
+ txtorcon.TorState and an abstraction to the configuration values via
+ txtorcon.TorConfig which provides attribute-style accessors to Tor's
+ state (including making changes). txtorcon.TorState provides
+ txtorcon.Router, txtorcon.Circuit and txtorcon.Stream objects which
+ implement a listener interface so client code may receive updates (in
+ real time) including Tor events.
+
+ txtorcon uses **trial for unit-tests** and has 96% test-coverage --
+ which is not to say I've covered all the cases, but nearly all of the
+ code is at least exercised somehow by the unit tests.
+
+ Tor itself is not required to be running for any of the tests. There are
+ no integration tests. ohcount claims around 2000 lines of code for the
+ core bit; around 4000 including tests. About 37% comments in the
+ not-test code.
+
+ dependencies / requirements
+ ---------------------------
+
+ - `twisted <http://twistedmatrix.com>`_: txtorcon should work with any
+ Twisted 11.1.0 or newer. I am working against Twisted 13.2.0 on
+ Debian with Python 2.7.6. Twisted 12 works fine as well. Twisted
+ does not yet support Python 3.
+
+ - `GeoIP <https://www.maxmind.com/app/python>`_: **optional** provides location
+ information for ip addresses; you will want to download GeoLite City
+ from `MaxMind <https://www.maxmind.com/app/geolitecity>`_ or pay them
+ for more accuracy. Or use tor-geoip, which makes this sort-of
+ optional, in that we'll query Tor for the IP if the GeoIP database
+ doesn't have an answer. It also does ASN lookups if you installed that MaxMind database.
+
+ - `python-ipaddr <http://code.google.com/p/ipaddr-py/>`_: **optional**.
+ Google's IP address manipulation code.
+
+ - development: `Sphinx <http://sphinx.pocoo.org/>`_ if you want to build the
+ documentation. In that case you'll also need something called
+ ``python-repoze.sphinx.autointerface`` (at least in Debian) to build
+ the Interface-derived docs properly.
+
+ - development: `coverage <http://nedbatchelder.com/code/coverage/>`_ to
+ run the code-coverage metrics
+
+ - optional: GraphViz is used in the tests (and to generate state-machine
+ diagrams, if you like) but those tests are skipped if "dot" isn't
+ in your path
+
++ .. BEGIN_INSTALL
++
+ In any case, on a `Debian <http://www.debian.org/>`_ wheezy, squeeze or
+ Ubuntu system, this should work::
+
- apt-get install python-setuptools python-twisted python-ipaddr python-geoip graphviz
- apt-get install python-sphinx python-repoze.sphinx.autointerface python-coverage # for develoment
++ apt-get install -y python-setuptools python-twisted python-ipaddr python-geoip graphviz tor
++ apt-get install -y python-sphinx python-repoze.sphinx.autointerface python-coverage # for development
++
++ .. END_INSTALL
+
+ Using pip this would be::
+
+ pip install Twisted ipaddr pygeoip
+ pip install GeoIP Sphinx repoze.sphinx.autointerface coverage # for development
+
+ or::
+
+ pip install -r requirements.txt
+ pip install -r dev-requirements.txt
+
+ or for the bare minimum::
+
+ pip install Twisted # will install zope.interface too
+
+ documentation
+ -------------
+
+ It is likely that you will need to read at least some of
+ `control-spec.txt <https://gitweb.torproject.org/torspec.git/blob/HEAD:/control-spec.txt>`_
+ from the torspec git repository so you know what's being abstracted by
+ this library.
+
+ Run "make doc" to build the Sphinx documentation locally, or rely on
+ ReadTheDocs https://txtorcon.readthedocs.org which builds each tagged
+ release and the latest master.
+
+ There is also a directory of examples/ scripts, which have inline
+ documentation explaining their use. You may also use pydoc::
+
+ pydoc txtorcon.TorControlProtocol
+ pydoc txtorcon.TorState
+ pydoc txtorcon.TorConfig
+
+ ...for the main classes. If you're using TorState, you will also be
+ interested in the support classes for it::
+
+ pydoc txtorcon.Circuit
+ pydoc txtorcon.Stream
+ pydoc txtorcon.Router
+ pydoc txtorcon.AddrMap
+
+ There are also Zope interfaces for some things, if you wish to listen
+ for events for your own purposes (the best example of the use of these
+ being TorState itself)::
+
+ txtorcon.ITorControlProtocol
+ txtorcon.IStreamAttacher
+ txtorcon.ICircuitListener
+ txtorcon.IStreamListener
+
+ For launching Tor and Twisted integration, you will want to look at::
+
+ txtorcon.launch_tor (in torconfig.py)
+ txtorcon.TCPHiddenServiceEndpoint (in torconfig.py)
+ txtorcon.TorProtocolFactory (in torcontrolprotocol.py)
+ txtorcon.build_tor_connection (in torstate.py)
+ txtorcon.build_local_tor_connection (in torstate.py)
+
+ IStreamAttacher affects Tor's behaviour, allowing one to customize how
+ circuits for particular streams are selected. You can build your own
+ circuits via ITorControlProtocol.build\_circuit(). There is an example
+ of this called custom\_stream\_attacher.py which builds (or uses)
+ circuits exiting in the same country as the address to which the
+ stream is connecting.
+
+
+ contact information
+ -------------------
+
+ For novelty value, the Web site (with built documentation and so forth)
- can be viewed via Tor at https://timaq4ygg2iegci7.onion although the
++ can be viewed via Tor at http://timaq4ygg2iegci7.onion although the
+ code itself is hosted via git::
+
+ torsocks git clone git://timaq4ygg2iegci7.onion/txtorcon.git
+
+ or::
+
+ git clone git://github.com/meejah/txtorcon.git
+
+ You may contact me via ``meejah at meejah dot ca`` with GPG key
+ `0xC2602803128069A7
+ <http://pgp.mit.edu:11371/pks/lookup?op=get&search=0xC2602803128069A7>`_
+ or see ``meejah.asc`` in the repository. The fingerprint is ``9D5A
+ 2BD5 688E CB88 9DEB CD3F C260 2803 1280 69A7``.
+
+ It is often possible to contact me as ``meejah`` in #tor-dev on `OFTC
+ <http://www.oftc.net/oftc/>`_ but be patient for replies (I do look at
+ scrollback, so putting "meejah: " in front will alert my client).
+
+ More conventionally, you may get the code at GitHub and documentation
+ via ReadTheDocs:
+
+ - https://github.com/meejah/txtorcon
+ - https://txtorcon.readthedocs.org
+
+ Please do **use the GitHub issue-tracker** to report bugs. Patches,
+ pull-requests, comments and criticisms are all welcomed and
+ appreciated.
+
+Keywords: python,twisted,tor,tor controller
+Platform: UNKNOWN
+Classifier: Framework :: Twisted
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Unix
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 2
+Classifier: Programming Language :: Python :: 2.6
+Classifier: Programming Language :: Python :: 2.7
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Internet :: Proxy Servers
+Classifier: Topic :: Internet
+Classifier: Topic :: Security
+Requires: Twisted (>=11.1.0)
+Requires: ipaddr (>=2.1.10)
+Requires: zope.interface (>=3.6.1)
diff --cc examples/hidden_echo.py
index f45c13e,0000000..b7b29c3
mode 100644,000000..100644
--- a/examples/hidden_echo.py
+++ b/examples/hidden_echo.py
@@@ -1,15 -1,0 +1,16 @@@
+from __future__ import print_function
+from twisted.internet import protocol, reactor, endpoints
+
+
+class Echo(protocol.Protocol):
+ def dataReceived(self, data):
+ self.transport.write(data)
+
+
+class EchoFactory(protocol.Factory):
+ def buildProtocol(self, addr):
+ return Echo()
+
- endpoints.serverFromString(reactor, "onion:1234").listen(EchoFactory()).addCallback(lambda x: print(x.getHost()))
++d = endpoints.serverFromString(reactor, "onion:1234").listen(EchoFactory())
++d.addCallback(lambda x: print(x.getHost()))
+reactor.run()
diff --cc examples/list_circuits.py
index 0000000,0000000..3fcec1e
new file mode 100644
--- /dev/null
+++ b/examples/list_circuits.py
@@@ -1,0 -1,0 +1,20 @@@
++#!/usr/bin/env python
++
++from twisted.internet.task import react
++from twisted.internet.defer import inlineCallbacks
++import txtorcon
++
++from guppy import hpy
++
++
++ at inlineCallbacks
++def main(reactor):
++ state = yield txtorcon.build_local_tor_connection(reactor)
++ for circuit in state.circuits.values():
++ first_relay = circuit.path[0]
++ print "Circuit {} first hop: {}".format(circuit.id, first_relay.ip)
++ print "heap:"
++ print hpy().heap()
++
++if __name__ == '__main__':
++ react(main)
diff --cc examples/multiple-socks-ports.py
index 0000000,0000000..a2ef55f
new file mode 100644
--- /dev/null
+++ b/examples/multiple-socks-ports.py
@@@ -1,0 -1,0 +1,42 @@@
++#!/usr/bin/env python
++
++# This connects to the system Tor (by default on control port 9151)
++# and adds a new hidden service configuration to it.
++
++import os
++import functools
++import shutil
++
++from twisted.internet import reactor, defer
++from twisted.internet.endpoints import TCP4ClientEndpoint, TCP4ServerEndpoint
++from twisted.web import server, resource
++from twisted.internet.task import react
++
++import txtorcon
++
++
++def setup_failed(arg):
++ print "SETUP FAILED", arg
++ reactor.stop()
++
++
++ at defer.inlineCallbacks
++def main(reactor):
++ # Connect to the system Tor. Since we leave the
++ # "build_state=True" default, this callbacks with a TorState
++ # object. Otherwise, it would be a TorControlProtocol object.
++ ep = TCP4ClientEndpoint(reactor, "localhost", 9051)
++ state = yield txtorcon.build_tor_connection(ep)
++
++ config = txtorcon.TorConfig(state.protocol)
++ yield config.post_bootstrap
++
++ if False:
++ config.socksport = [5432, 4321]
++ else:
++ config.socksport.append(5555)
++ config.socksport.append(4444)
++ yield config.save()
++
++# run the reactor main loop until the last callback from main() fires
++react(main)
diff --cc examples/torflow_path_selection.py
index 0000000,0000000..0204230
new file mode 100644
--- /dev/null
+++ b/examples/torflow_path_selection.py
@@@ -1,0 -1,0 +1,93 @@@
++#!/usr/bin/env python
++
++# playing around with some ideas as far as bwauth (inside TorFlow)
++# works, and the path-selection stuff from TorCtl which has been
++# mentioned as a desireable txtorcon feature.
++
++import random
++from functools import partial
++from twisted.internet import defer
++from twisted.internet import task
++import txtorcon
++
++
++def node_selector(routers, # torstate,
++ node_filter=lambda x: True,
++ chooser=random.choice):
++ nodes = filter(node_filter, routers)
++ if len(nodes) == 0:
++ raise RuntimeError("No nodes left after filtering.")
++ return chooser(nodes)
++
++
++def flag_filter(flag, router):
++ return flag in router.flags
++
++
++def cmp_bandwidth(router_a, router_b):
++ return cmp(router_a.bandwidth, router_b.bandwidth)
++
++guard_filter = partial(flag_filter, 'guard')
++exit_filter = partial(flag_filter, 'exit')
++
++
++def percent_filter(torstate, min_pct, max_pct):
++ if min_pct <= 0.0:
++ raise RuntimeError("Minimum is too low")
++ if max_pct >= 100.0:
++ raise RuntimeError("Maximum is too high")
++
++ def actual_filter(router):
++ return
++
++
++def create_paths(routers):
++ '''
++ This is a generator that produces paths the way Tor does: with a
++ single guard node, a single middle node and a single exit
++ node.
++
++ Every time the generator runs it returns a tuple of Router
++ instances representing the chosen path.
++
++ FIXME need to consider when underlying router list
++ changes. e.g. between any iteration it's possible all our cached
++ data became stale...
++ '''
++
++ guard_selector = lambda: node_selector(routers, node_filter=guard_filter)
++ middle_selector = lambda: node_selector(routers)
++ exit_selector = lambda: node_selector(routers, node_filter=exit_filter)
++ while True:
++ yield (guard_selector(), middle_selector(), exit_selector())
++
++
++ at defer.inlineCallbacks
++def main(reactor):
++ state = yield txtorcon.build_local_tor_connection(reactor)
++ yield state.post_bootstrap
++
++ # make a generator for selecting from any possible router
++ g = create_paths(state.all_routers)
++ for i in range(10):
++ path = g.next()
++ print map(lambda r: r.name, path)
++
++ # same, except we limit the routers to the top N% fastest ones in
++ # each category: guard, middle, exit
++ guards = filter(guard_filter, torstate.all_routers)
++ guards.sort(key=lambda x: x.bandwidth)
++ middles = list(torstate.all_routers)
++ middles.sort(key=lambda x: x.bandwidth)
++ exits = filter(exit_filter, torstate.all_routers)
++ exits.sort(key=lambda x: x.bandwidth)
++
++ print len(routers_by_bandwidth), "routers"
++ percent = 10.0
++ top_n = int((percent / 100.0) * len(routers_by_bandwidth))
++ g = create_paths(routers_by_bandwidth[:top_n])
++ for i in range(10):
++ path = g.next()
++ print map(lambda r: r.name, path)
++
++task.react(main)
diff --cc test/profile_startup.py
index a4ab1c8,0000000..997007a
mode 100644,000000..100644
--- a/test/profile_startup.py
+++ b/test/profile_startup.py
@@@ -1,11 -1,0 +1,21 @@@
+#!/usr/bin/env python
+
++from time import time
+import cProfile
+import txtorcon
+
+proto = txtorcon.TorControlProtocol()
+state = txtorcon.TorState(proto)
+
+data = open('consensus', 'r').read()
- #cProfile.run('state._update_network_status(data)')
- state._update_network_status(data)
++routers = 4724 # number of routers in above file
++iters = 100
++
++start = time()
++if False:
++ cProfile.run('state._update_network_status(data)')
++else:
++ for x in xrange(iters):
++ state._update_network_status(data)
++diff = time() - start
++print "%fs: %f microdescriptors/second" % (diff, (routers * iters) / diff)
diff --cc txtorcon.egg-info/PKG-INFO
index 97b2645,0000000..9cd2ccb
mode 100644,000000..100644
--- a/txtorcon.egg-info/PKG-INFO
+++ b/txtorcon.egg-info/PKG-INFO
@@@ -1,274 -1,0 +1,277 @@@
+Metadata-Version: 1.1
+Name: txtorcon
- Version: 0.11.0
++Version: 0.13.0
+Summary: Twisted-based Tor controller client, with state-tracking and configuration abstractions.
+Home-page: https://github.com/meejah/txtorcon
+Author: meejah
+Author-email: meejah at meejah.ca
+License: MIT
+Description: README
+ ======
+
+ Documentation at https://txtorcon.readthedocs.org
+
+ .. image:: https://travis-ci.org/meejah/txtorcon.png?branch=master
+ :target: https://www.travis-ci.org/meejah/txtorcon
+
+ .. image:: https://coveralls.io/repos/meejah/txtorcon/badge.png
+ :target: https://coveralls.io/r/meejah/txtorcon
+
+ .. image:: http://api.flattr.com/button/flattr-badge-large.png
+ :target: http://flattr.com/thing/1689502/meejahtxtorcon-on-GitHub
+
+
+ quick start
+ -----------
+
+ For the impatient, there are two quick ways to install this::
+
+ $ pip install txtorcon
+
- (Thanks to Lunar^ for all his packaging work) or, if you checked out
- or downloaded the source::
++ ... or, if you checked out or downloaded the source::
+
+ $ python setup.py install
+
+ To avoid installing, you can just add the base of the source to your
+ PYTHONPATH::
+
+ $ export PYTHONPATH=`pwd`:$PYTHONPATH
+
+ Then, you will want to explore the examples. Try "python
+ examples/stream\_circuit\_logger.py" for instance.
+
- On Debian testing (jessie), or with wheezy-backports you can install
- version 0.8.2::
++ On Debian testing (jessie), or with wheezy-backports (big thanks to
++ Lunar^ for all his packaging work) you can install easily::
+
+ $ apt-get install python-txtorcon
+
+ You may also like `this asciinema demo <http://asciinema.org/a/5654>`_
+ for an overview.
+
+ Tor configuration
+ -----------------
+
+ You'll want to have the following options on in your ``torrc``::
+
+ CookieAuthentication 1
+ CookieAuthFileGroupReadable 1
+
+ If you want to use unix sockets to speak to tor::
+
+ ControlSocketsGroupWritable 1
+ ControlSocket /var/run/tor/control
+
- The defaults used by :meth:`txtorcon.build_local_tor_connection` will
++ The defaults used by py:meth:`txtorcon.build_local_tor_connection` will
+ find a Tor on ``9051`` or ``/var/run/tor/control``
+
+
+ overview
+ --------
+
+ txtorcon is a Twisted-based asynchronous Tor control protocol
+ implementation. Twisted is an event-driven networking engine written
+ in Python and Tor is an onion-routing network designed to improve
+ people's privacy and anonymity on the Internet.
+
+ The main abstraction of this library is txtorcon.TorControlProtocol
+ which presents an asynchronous API to speak the Tor client protocol in
+ Python. txtorcon also provides abstractions to track and get updates
+ about Tor's state (txtorcon.TorState) and current configuration
+ (including writing it to Tor or disk) in txtorcon.TorConfig, along
+ with helpers to asynchronously launch slave instances of Tor including
+ Twisted endpoint support.
+
+ txtorcon runs all tests cleanly on:
+
+ - Debian "squeeze", "wheezy" and "jessie"
+ - OS X 10.4 (naif)
+ - OS X 10.8 (lukas lueg)
+ - OS X 10.9 (kurt neufeld)
+ - Fedora 18 (lukas lueg)
+ - FreeBSD 10 (enrique fynn) (**needed to install "lsof"**)
+ - RHEL6
+ - Reports from other OSes appreciated.
+
+ If instead you want a synchronous (threaded) Python controller
+ library, check out Stem at https://stem.torproject.org/
+
+ quick implementation overview
+ -----------------------------
+
+ txtorcon provides a class to track Tor's current state -- such as
+ details about routers, circuits and streams -- called
+ txtorcon.TorState and an abstraction to the configuration values via
+ txtorcon.TorConfig which provides attribute-style accessors to Tor's
+ state (including making changes). txtorcon.TorState provides
+ txtorcon.Router, txtorcon.Circuit and txtorcon.Stream objects which
+ implement a listener interface so client code may receive updates (in
+ real time) including Tor events.
+
+ txtorcon uses **trial for unit-tests** and has 96% test-coverage --
+ which is not to say I've covered all the cases, but nearly all of the
+ code is at least exercised somehow by the unit tests.
+
+ Tor itself is not required to be running for any of the tests. There are
+ no integration tests. ohcount claims around 2000 lines of code for the
+ core bit; around 4000 including tests. About 37% comments in the
+ not-test code.
+
+ dependencies / requirements
+ ---------------------------
+
+ - `twisted <http://twistedmatrix.com>`_: txtorcon should work with any
+ Twisted 11.1.0 or newer. I am working against Twisted 13.2.0 on
+ Debian with Python 2.7.6. Twisted 12 works fine as well. Twisted
+ does not yet support Python 3.
+
+ - `GeoIP <https://www.maxmind.com/app/python>`_: **optional** provides location
+ information for ip addresses; you will want to download GeoLite City
+ from `MaxMind <https://www.maxmind.com/app/geolitecity>`_ or pay them
+ for more accuracy. Or use tor-geoip, which makes this sort-of
+ optional, in that we'll query Tor for the IP if the GeoIP database
+ doesn't have an answer. It also does ASN lookups if you installed that MaxMind database.
+
+ - `python-ipaddr <http://code.google.com/p/ipaddr-py/>`_: **optional**.
+ Google's IP address manipulation code.
+
+ - development: `Sphinx <http://sphinx.pocoo.org/>`_ if you want to build the
+ documentation. In that case you'll also need something called
+ ``python-repoze.sphinx.autointerface`` (at least in Debian) to build
+ the Interface-derived docs properly.
+
+ - development: `coverage <http://nedbatchelder.com/code/coverage/>`_ to
+ run the code-coverage metrics
+
+ - optional: GraphViz is used in the tests (and to generate state-machine
+ diagrams, if you like) but those tests are skipped if "dot" isn't
+ in your path
+
++ .. BEGIN_INSTALL
++
+ In any case, on a `Debian <http://www.debian.org/>`_ wheezy, squeeze or
+ Ubuntu system, this should work::
+
- apt-get install python-setuptools python-twisted python-ipaddr python-geoip graphviz
- apt-get install python-sphinx python-repoze.sphinx.autointerface python-coverage # for develoment
++ apt-get install -y python-setuptools python-twisted python-ipaddr python-geoip graphviz tor
++ apt-get install -y python-sphinx python-repoze.sphinx.autointerface python-coverage # for development
++
++ .. END_INSTALL
+
+ Using pip this would be::
+
+ pip install Twisted ipaddr pygeoip
+ pip install GeoIP Sphinx repoze.sphinx.autointerface coverage # for development
+
+ or::
+
+ pip install -r requirements.txt
+ pip install -r dev-requirements.txt
+
+ or for the bare minimum::
+
+ pip install Twisted # will install zope.interface too
+
+ documentation
+ -------------
+
+ It is likely that you will need to read at least some of
+ `control-spec.txt <https://gitweb.torproject.org/torspec.git/blob/HEAD:/control-spec.txt>`_
+ from the torspec git repository so you know what's being abstracted by
+ this library.
+
+ Run "make doc" to build the Sphinx documentation locally, or rely on
+ ReadTheDocs https://txtorcon.readthedocs.org which builds each tagged
+ release and the latest master.
+
+ There is also a directory of examples/ scripts, which have inline
+ documentation explaining their use. You may also use pydoc::
+
+ pydoc txtorcon.TorControlProtocol
+ pydoc txtorcon.TorState
+ pydoc txtorcon.TorConfig
+
+ ...for the main classes. If you're using TorState, you will also be
+ interested in the support classes for it::
+
+ pydoc txtorcon.Circuit
+ pydoc txtorcon.Stream
+ pydoc txtorcon.Router
+ pydoc txtorcon.AddrMap
+
+ There are also Zope interfaces for some things, if you wish to listen
+ for events for your own purposes (the best example of the use of these
+ being TorState itself)::
+
+ txtorcon.ITorControlProtocol
+ txtorcon.IStreamAttacher
+ txtorcon.ICircuitListener
+ txtorcon.IStreamListener
+
+ For launching Tor and Twisted integration, you will want to look at::
+
+ txtorcon.launch_tor (in torconfig.py)
+ txtorcon.TCPHiddenServiceEndpoint (in torconfig.py)
+ txtorcon.TorProtocolFactory (in torcontrolprotocol.py)
+ txtorcon.build_tor_connection (in torstate.py)
+ txtorcon.build_local_tor_connection (in torstate.py)
+
+ IStreamAttacher affects Tor's behaviour, allowing one to customize how
+ circuits for particular streams are selected. You can build your own
+ circuits via ITorControlProtocol.build\_circuit(). There is an example
+ of this called custom\_stream\_attacher.py which builds (or uses)
+ circuits exiting in the same country as the address to which the
+ stream is connecting.
+
+
+ contact information
+ -------------------
+
+ For novelty value, the Web site (with built documentation and so forth)
- can be viewed via Tor at https://timaq4ygg2iegci7.onion although the
++ can be viewed via Tor at http://timaq4ygg2iegci7.onion although the
+ code itself is hosted via git::
+
+ torsocks git clone git://timaq4ygg2iegci7.onion/txtorcon.git
+
+ or::
+
+ git clone git://github.com/meejah/txtorcon.git
+
+ You may contact me via ``meejah at meejah dot ca`` with GPG key
+ `0xC2602803128069A7
+ <http://pgp.mit.edu:11371/pks/lookup?op=get&search=0xC2602803128069A7>`_
+ or see ``meejah.asc`` in the repository. The fingerprint is ``9D5A
+ 2BD5 688E CB88 9DEB CD3F C260 2803 1280 69A7``.
+
+ It is often possible to contact me as ``meejah`` in #tor-dev on `OFTC
+ <http://www.oftc.net/oftc/>`_ but be patient for replies (I do look at
+ scrollback, so putting "meejah: " in front will alert my client).
+
+ More conventionally, you may get the code at GitHub and documentation
+ via ReadTheDocs:
+
+ - https://github.com/meejah/txtorcon
+ - https://txtorcon.readthedocs.org
+
+ Please do **use the GitHub issue-tracker** to report bugs. Patches,
+ pull-requests, comments and criticisms are all welcomed and
+ appreciated.
+
+Keywords: python,twisted,tor,tor controller
+Platform: UNKNOWN
+Classifier: Framework :: Twisted
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Unix
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 2
+Classifier: Programming Language :: Python :: 2.6
+Classifier: Programming Language :: Python :: 2.7
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Internet :: Proxy Servers
+Classifier: Topic :: Internet
+Classifier: Topic :: Security
+Requires: Twisted (>=11.1.0)
+Requires: ipaddr (>=2.1.10)
+Requires: zope.interface (>=3.6.1)
diff --cc txtorcon.egg-info/SOURCES.txt
index 3ee29a7,0000000..2334e50
mode 100644,000000..100644
--- a/txtorcon.egg-info/SOURCES.txt
+++ b/txtorcon.egg-info/SOURCES.txt
@@@ -1,103 -1,0 +1,106 @@@
+INSTALL
+LICENSE
+MANIFEST.in
+Makefile
+README.rst
+TODO
+dev-requirements.txt
+meejah.asc
+requirements.txt
+setup.py
+docs/Makefile
+docs/README.rst
+docs/apilinks_sphinxext.py
+docs/conf.py
+docs/examples.rst
+docs/howtos.rst
+docs/index.rst
+docs/introduction.rst
+docs/release-checklist.rst
+docs/releases.rst
+docs/txtorcon-config.rst
+docs/txtorcon-endpoints.rst
+docs/txtorcon-interface.rst
+docs/txtorcon-launching.rst
+docs/txtorcon-protocol.rst
+docs/txtorcon-state.rst
+docs/txtorcon-util.rst
+docs/txtorcon.rst
+docs/walkthrough.rst
+docs/_static/avatar.png
+docs/_static/haiku.css
+docs/_static/logo.png
+docs/_static/logo.svg
+docs/_themes/README
+docs/_themes/alabaster/__init__.py
+docs/_themes/alabaster/_version.py
+docs/_themes/alabaster/about.html
+docs/_themes/alabaster/donate.html
+docs/_themes/alabaster/layout.html
+docs/_themes/alabaster/navigation.html
+docs/_themes/alabaster/support.py
+docs/_themes/alabaster/theme.conf
+docs/_themes/alabaster/static/alabaster.css_t
+docs/_themes/alabaster/static/pygments.css
- examples/add_hiddenservice_to_system_tor.py
+examples/attach_streams_by_country.py
+examples/circuit_failure_rates.py
+examples/circuit_for_next_stream.py
+examples/disallow_streams_by_port.py
+examples/dump_config.py
+examples/hello_darkweb.py
+examples/hidden-service-systemd.service
+examples/hidden_echo.py
+examples/launch_tor.py
++examples/launch_tor2web.py
+examples/launch_tor_endpoint.py
+examples/launch_tor_endpoint2.py
+examples/launch_tor_with_hiddenservice.py
+examples/launch_tor_with_simplehttpd.py
++examples/list_circuits.py
+examples/minimal_endpoint.py
+examples/monitor.py
++examples/multiple-socks-ports.py
+examples/schedule_bandwidth.py
+examples/stream_circuit_logger.py
+examples/systemd.service
+examples/tor_info.py
++examples/torflow_path_selection.py
+examples/txtorcon.tac
+examples/webui_server.py
+scripts/asciinema-demo0.py
+test/__init__.py
+test/profile_startup.py
+test/test_addrmap.py
+test/test_circuit.py
+test/test_endpoints.py
+test/test_fsm.py
+test/test_log.py
+test/test_router.py
+test/test_stream.py
+test/test_torconfig.py
+test/test_torcontrolprotocol.py
+test/test_torinfo.py
+test/test_torstate.py
+test/test_util.py
+test/test_util_imports.py
+test/util.py
+twisted/plugins/txtorcon_endpoint_parser.py
+txtorcon/__init__.py
+txtorcon/addrmap.py
+txtorcon/circuit.py
+txtorcon/endpoints.py
+txtorcon/interface.py
+txtorcon/log.py
+txtorcon/router.py
+txtorcon/spaghetti.py
+txtorcon/stream.py
+txtorcon/torconfig.py
+txtorcon/torcontrolprotocol.py
+txtorcon/torinfo.py
+txtorcon/torstate.py
+txtorcon/util.py
+txtorcon.egg-info/PKG-INFO
+txtorcon.egg-info/SOURCES.txt
+txtorcon.egg-info/dependency_links.txt
+txtorcon.egg-info/requires.txt
+txtorcon.egg-info/top_level.txt
diff --cc txtorcon.egg-info/requires.txt
index b54eaeb,0000000..1afedf0
mode 100644,000000..100644
--- a/txtorcon.egg-info/requires.txt
+++ b/txtorcon.egg-info/requires.txt
@@@ -1,2 -1,0 +1,2 @@@
+Twisted>=11.1.0
- zope.interface>=3.6.1
++zope.interface>=3.6.1
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-privacy/packages/txtorcon.git
More information about the Pkg-privacy-commits
mailing list