Metadata-Version: 1.1
Name: txtorcon
Version: 0.6
Summary: Twisted-based Tor controller client, with state-tracking and configuration abstractions.
Home-page: https://github.com/meejah/txtorcon
Author: meejah
Author-email: meejah@meejah.ca
License: MIT
Description: txtorcon README
        ===============
        
        Full documentation at ReadTheDocs <https://txtorcon.readthedocs.org>
        
        quick start
        -----------
        
        For the impatient, there are two quick ways to install this:
        
           $ pip install txtorcon
        
        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.
        
        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.
        
        My main motivation to write this was to learn more about Twisted and
        Tor. I was playing with pyglet and pygame to try out some
        visualization ideas and the only Python controller library was
        synchronous (thread-based) so I thought I'd write my own.
        
        NOTE: that this is currently a moving target still; if you're going to
        depend on txtorcon as a controller library, it Very Highly Recommended
        that you follow the source at github (or via the hidden service). I
        fairly regularly push code to both.
        
        txtorcon runs all tests cleanly on:
        
         * Debian stable (squeeze)
         * Debian testing (wheezy)
         * naif reports OS X 10.4 works
         * Reports from other OSes appreciated.
        
        If instead you want a synchronous Python controller library, check out
        Stem at https://stem.readthedocs.org/en/latest/
        
        quick implementation overview
        -----------------------------
        
        txtorcon also 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.
        
        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.
        
            $ make test
            Ran 220 tests in 0.394s
        
            $ make coverage
            ## ...deleted lots of output...
            covered: 1922
            uncovered: 69
            96.79% test coverage
        
        Tor itself is not required to be running for any of the tests. There
        are no integration tests. ohcount claims under 2000 lines of code for
        the core bit; around 4000 including tests. About 37% comments in the
        not-test code.
        
        
        dependencies
        ------------
        
         * [twisted](http://twistedmatrix.com): I am working against
           Twisted 11.1.0 on Debian with Python 2.7.2. Twisted 12 works fine as well.
        
         * [GeoIP](https://www.maxmind.com/app/python): 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 if the GeoIP database
           doesn't have an answer but I haven't bothered removing the
           dependency yet..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. 
        
         * [Sphinx](http://sphinx.pocoo.org/): Only 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.
        
         * GraphViz is used in the tests (and to generate state-machine
           diagrams, if you like). If you don't have/want it see
           ``txtorcon/test/test_fsm.py`` around line 62 to disable the test
        
        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 # for documentation
        
        
        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.
        
        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.build_tor_connection (in torstate.py)
            txtorcon.TorProtocolFactory (in torcontrolprotocol.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 code itself is hosted via git:
        
            torsocks git clone git://timaq4ygg2iegci7.onion/txtorcon.git
        
        You may contact me via ``meejah at meejah dot ca`` with GPG key
        [128069A7]<http://pgp.mit.edu:11371/pks/lookup?op=get&search=0xC2602803128069A7>
        or see ``meejah.asc``. 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 mention my nick).
        
        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. See TODO for notes on deficiencies, planned features,
        lunatic raving, etc.
        
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: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: Proxy Servers
Classifier: Topic :: Internet
Classifier: Topic :: Security
Requires: pygeoip
Requires: Sphinx
Requires: Twisted (>=11.1.0)
Requires: ipaddr (>=2.1.10)
Requires: repoze.sphinx.autointerface (>=0.4)
Requires: zope.interface (>=3.6.1)
