47
62
with helpers to asynchronously launch slave instances of Tor including
48
63
Twisted endpoint support.
50
NOTE: that this is currently a moving target still; if you're going to
51
depend on txtorcon as a controller library, it Very Highly Recommended
52
that you follow the source at github (or via the hidden service). I
53
fairly regularly push code to both.
55
65
txtorcon runs all tests cleanly on:
57
- Debian stable (squeeze)
58
- Debian testing (wheezy)
67
- Debian "squeeze", "wheezy" and "jessie"
60
69
- OS X 10.8 (lukas lueg)
61
70
- Fedora 18 (lukas lueg)
62
71
- Reports from other OSes appreciated.
64
If instead you want a synchronous Python controller library, check out
65
Stem at https://stem.torproject.org/
73
If instead you want a synchronous (threaded) Python controller
74
library, check out Stem at https://stem.torproject.org/
67
76
quick implementation overview
68
77
-----------------------------
70
txtorcon also provides a class to track Tor's current state -- such as
71
details about routers, circuits and streams -- called txtorcon.TorState
72
and an abstraction to the configuration values via txtorcon.TorConfig
73
which provides attribute-style accessors to Tor's state (including
74
making changes). txtorcon.TorState provides txtorcon.Router,
75
txtorcon.Circuit and txtorcon.Stream objects which implement a listener
76
interface so client code may receive updates.
79
txtorcon provides a class to track Tor's current state -- such as
80
details about routers, circuits and streams -- called
81
txtorcon.TorState and an abstraction to the configuration values via
82
txtorcon.TorConfig which provides attribute-style accessors to Tor's
83
state (including making changes). txtorcon.TorState provides
84
txtorcon.Router, txtorcon.Circuit and txtorcon.Stream objects which
85
implement a listener interface so client code may receive updates (in
86
real time) including Tor events.
78
txtorcon uses **trial for unit-tests** and has 97% test-coverage --
88
txtorcon uses **trial for unit-tests** and has 96% test-coverage --
79
89
which is not to say I've covered all the cases, but nearly all of the
80
90
code is at least exercised somehow by the unit tests.
85
**Ran 227 tests in 1.394s**
88
## ...deleted lots of output...
91
**97.81% test coverage**
93
92
Tor itself is not required to be running for any of the tests. There are
94
93
no integration tests. ohcount claims around 2000 lines of code for the
95
94
core bit; around 4000 including tests. About 37% comments in the
97
dependencies / requirements
98
---------------------------
101
100
- `twisted <http://twistedmatrix.com>`_: I am working against Twisted
102
11.1.0 on Debian with Python 2.7.2. Twisted 12 works fine as well.
101
11.1.0 on Debian with Python 2.7.2. Twisted 12 works fine as
102
well. Twisted does not yet support Python 3.
104
- `GeoIP <https://www.maxmind.com/app/python>`_: provides location
104
- `GeoIP <https://www.maxmind.com/app/python>`_: **optional** provides location
105
105
information for ip addresses; you will want to download GeoLite City
106
106
from `MaxMind <https://www.maxmind.com/app/geolitecity>`_ or pay them
107
107
for more accuracy. Or use tor-geoip, which makes this sort-of
108
108
optional, in that we'll query Tor for the if the GeoIP database
109
109
doesn't have an answer but I haven't bothered removing the dependency
110
yet..It also does ASN lookups if you installed that MaxMind database.
110
yet. It also does ASN lookups if you installed that MaxMind database.
112
112
- `python-ipaddr <http://code.google.com/p/ipaddr-py/>`_: **optional**.
113
113
Google's IP address manipulation code.
115
- `Sphinx <http://sphinx.pocoo.org/>`_: Only if you want to build the
115
- development: `Sphinx <http://sphinx.pocoo.org/>`_ if you want to build the
116
116
documentation. In that case you'll also need something called
117
117
``python-repoze.sphinx.autointerface`` (at least in Debian) to build
118
118
the Interface-derived docs properly.
120
- GraphViz is used in the tests (and to generate state-machine
120
- development: `coverage <http://nedbatchelder.com/code/coverage/>`_ to
121
run the code-coverage metrics
123
- optional: GraphViz is used in the tests (and to generate state-machine
121
124
diagrams, if you like) but those tests are skipped if "dot" isn't
125
128
Ubuntu system, this should work::
127
130
apt-get install python-setuptools python-twisted python-ipaddr python-geoip graphviz
128
apt-get install python-sphinx python-repoze.sphinx.autointerface # for documentation
130
Using pip this would be:
132
pip install Twisted ipaddr pygeoip
131
apt-get install python-sphinx python-repoze.sphinx.autointerface python-coverage # for develoment
133
Using pip this would be::
135
pip install Twisted ipaddr pygeoip
136
pip install GeoIP Sphinx repoze.sphinx.autointerface coverage # for development
140
pip install -r requirements.txt
141
pip install -r dev-requirements.txt
143
or for the bare minimum::
145
pip install Twisted # will install zope.interface too
196
210
git clone git://github.com/meejah/txtorcon.git
198
212
You may contact me via ``meejah at meejah dot ca`` with GPG key
199
`128069A7 <http://pgp.mit.edu:11371/pks/lookup?op=get&search=0xC2602803128069A7>`_
200
or see ``meejah.asc``. It is often possible to contact me as ``meejah``
201
in #tor-dev on `OFTC <http://www.oftc.net/oftc/>`_ but be patient for
202
replies (I do look at scrollback, so mention my nick).
214
<http://pgp.mit.edu:11371/pks/lookup?op=get&search=0xC2602803128069A7>`_
215
or see ``meejah.asc`` in the repository. The fingerprint is ``9D5A
216
2BD5 688E CB88 9DEB CD3F C260 2803 1280 69A7``.
218
It is often possible to contact me as ``meejah`` in #tor-dev on `OFTC
219
<http://www.oftc.net/oftc/>`_ but be patient for replies (I do look at
220
scrollback, so putting "meejah: " in front will alert my client).
204
222
More conventionally, you may get the code at GitHub and documentation
added
removed
PKG-INFO
