Makefile

 .PHONY: test html counts coverage sdist clean install doc integration diagrams
 default: test
-VERSION = 0.19.3
+VERSION = 18.0.2
 
 test:
 	PYTHONPATH=. trial --reporter=text test
@@ -69,10 +69,10 @@ coverage-debian:
 	python-coverage report
 
 pep8: txtorcon/*.py test/*.py examples/*.py
-	pep8 --ignore=E501 $^
+	pycodestyle --ignore=E501 $^
 
 pep8count:
-	pep8 --ignore=E501,E265 $^ | wc -l
+	pycodestyle --ignore=E501,E265 $^ | wc -l
 
 pyflakes:
 	pyflakes txtorcon/ examples/ test/
@@ -104,9 +104,11 @@ dist: dist/txtorcon-${VERSION}-py2.py3-none-any.whl dist/txtorcon-${VERSION}.tar
 dist-sigs: dist/txtorcon-${VERSION}-py2.py3-none-any.whl.asc dist/txtorcon-${VERSION}.tar.gz.asc
 
 sdist: setup.py
+	python setup.py check
 	python setup.py sdist
 
 dist/txtorcon-${VERSION}-py2.py3-none-any.whl:
+	python setup.py check
 	python setup.py bdist_wheel --universal
 
 dist/txtorcon-${VERSION}-py2.py3-none-any.whl.asc: dist/txtorcon-${VERSION}-py2.py3-none-any.whl
@@ -132,3 +134,6 @@ venv:
 
 html: docs/*.rst
 	cd docs && make html
+
+html-server: html
+	twistd -n web --path docs/_build/html --port tcp:9999:interface=localhost

PKG-INFO

-Metadata-Version: 1.1
+Metadata-Version: 2.1
 Name: txtorcon
-Version: 0.19.3
+Version: 18.0.2
 Summary: 
     Twisted-based Tor controller client, with state-tracking and
     configuration abstractions.
@@ -62,7 +62,7 @@ Description:
         - MIT-licensed;
         - Python 2.7, PyPy 5.0.0+, Python 3.4+;
         - depends on
-          `Twisted <https://twistedmatrix.com>`_,
+          `Twisted`_,
           `Automat <https://github.com/glyph/automat>`_,
           (and the `ipaddress <https://pypi.python.org/pypi/ipaddress>`_ backport for non Python 3)
         
@@ -78,9 +78,8 @@ Description:
         
         txtorcon is an implementation of the `control-spec
         <https://gitweb.torproject.org/torspec.git/blob/HEAD:/control-spec.txt>`_
-        for `Tor <https://www.torproject.org/>`_ using the `Twisted
-        <https://twistedmatrix.com/trac/>`_ networking library for `Python
-        <http://python.org/>`_.
+        for `Tor <https://www.torproject.org/>`_ using the `Twisted`_
+        networking library for `Python <http://python.org/>`_.
         
         This is useful for writing utilities to control or make use of Tor in
         event-based Python programs. If your Twisted program supports
@@ -151,7 +150,7 @@ Description:
         
         .. code-block:: shell-session
         
-            $ sudo apt-get install python-txtorcon
+            $ sudo apt-get install --install-suggests python-txtorcon
             $ twistd -n web --port "onion:80" --path ~/public_html
         
         
@@ -165,6 +164,8 @@ Description:
         You'll want to start with `the introductions <docs/introduction.rst>`_ (`hosted at RTD
         <https://txtorcon.readthedocs.org/en/latest/introduction.html>`_).
         
+        .. _Twisted: https://twistedmatrix.com/trac
+        
 Keywords: python,twisted,tor,tor controller
 Platform: UNKNOWN
 Classifier: Framework :: Twisted
@@ -178,7 +179,9 @@ Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 2
 Classifier: Programming Language :: Python :: 2.6
 Classifier: Programming Language :: Python :: 2.7
+Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Internet :: Proxy Servers
 Classifier: Topic :: Internet
 Classifier: Topic :: Security
+Provides-Extra: dev

README.rst

@@ -49,7 +49,7 @@ txtorcon
 - MIT-licensed;
 - Python 2.7, PyPy 5.0.0+, Python 3.4+;
 - depends on
-  `Twisted <https://twistedmatrix.com>`_,
+  `Twisted`_,
   `Automat <https://github.com/glyph/automat>`_,
   (and the `ipaddress <https://pypi.python.org/pypi/ipaddress>`_ backport for non Python 3)
 
@@ -65,9 +65,8 @@ Ten Thousand Feet
 
 txtorcon is an implementation of the `control-spec
 <https://gitweb.torproject.org/torspec.git/blob/HEAD:/control-spec.txt>`_
-for `Tor <https://www.torproject.org/>`_ using the `Twisted
-<https://twistedmatrix.com/trac/>`_ networking library for `Python
-<http://python.org/>`_.
+for `Tor <https://www.torproject.org/>`_ using the `Twisted`_
+networking library for `Python <http://python.org/>`_.
 
 This is useful for writing utilities to control or make use of Tor in
 event-based Python programs. If your Twisted program supports
@@ -138,7 +137,7 @@ service):
 
 .. code-block:: shell-session
 
-    $ sudo apt-get install python-txtorcon
+    $ sudo apt-get install --install-suggests python-txtorcon
     $ twistd -n web --port "onion:80" --path ~/public_html
 
 
@@ -151,3 +150,5 @@ All the documentation starts `in docs/index.rst
 
 You'll want to start with `the introductions <docs/introduction.rst>`_ (`hosted at RTD
 <https://txtorcon.readthedocs.org/en/latest/introduction.html>`_).
+
+.. _Twisted: https://twistedmatrix.com/trac

dev-requirements.txt

@@ -9,7 +9,8 @@ codecov
 wheel
 twine
 pyflakes
-pep8
+pycodestyle
 mock
 ipaddress>=1.0.16
 geoip
+readme_renderer

docs/index.rst

@@ -4,7 +4,10 @@
 txtorcon
 ========
 
-- **docs**: https://txtorcon.readthedocs.org or http://timaq4ygg2iegci7.onion
+- **docs**:
+   - v3 onion: http://fjblvrw2jrxnhtg67qpbzi45r7ofojaoo3orzykesly2j3c2m3htapid.onion/
+   - v2 onion: http://timaq4ygg2iegci7.onion
+   - clearnet: https://txtorcon.readthedocs.org
 - **code**: https://github.com/meejah/txtorcon
 - ``torsocks git clone git://timaq4ygg2iegci7.onion/txtorcon.git``
 - .. image:: https://travis-ci.org/meejah/txtorcon.png?branch=master
@@ -49,6 +52,8 @@ Supported and tested platforms: Python 2.7+, Python 3.5+, PyPy 5.0.0+
 using Twisted 15.5.0+, 16.3.0+, or 17.1.0+ (see `travis
 <https://travis-ci.org/meejah/txtorcon>`_).
 
+**Asycnio inter-operation** is now possible, see :ref:`interop_asyncio`
+
 
 Documentation
 -------------
@@ -60,6 +65,7 @@ Documentation
    installing
    guide
    examples
+   interop_asyncio
    hacking
 
 

docs/installing.rst

@@ -45,6 +45,11 @@ setuptools. At least on Debian, it is important to upgrade setuptools
    pip install path/to/txtorcon-*.whl
 
 
+If you get an error like `SyntaxError: invalid syntax` on
+`txtorcon/test/py3_torstate.py` or similar, you have an out-of-date
+pip or setuptools; see above.
+
+
 Compatibility
 -------------
 

docs/interop_asyncio.rst

+.. _interop_asyncio:
+
+Using Asyncio Libraries with txtorcon
+=====================================
+
+It is possible to use Twisted's `asyncioreactor
+<https://twistedmatrix.com/documents/current/api/twisted.internet.asyncioreactor.html>`_
+in order to use Twisted together with asyncio libraries. This comes
+with a couple caveats:
+
+* You need to install Twisted
+* Twisted "owns" the event-loop (i.e. you call :func:`reactor.run`);
+* You need to convert Futures/co-routines to Deferred sometimes
+  (Twisted provides the required machinery)
+
+Here is an example using the `aiohttp
+<https://aiohttp.readthedocs.io/en/stable/>`_ library as a Web server
+behind an Onion service that txtorcon has set up (in a newly-launched
+Tor process):
+
+**wanted**: I can't get this example to work properly with a Unix
+socket.
+
+.. _web_onion_service_aiohttp.py:
+
+``web_onion_service_aiohttp.py``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:download:`Download the example <../examples/web_onion_service_aiohttp.py>`.
+
+.. literalinclude:: ../examples/web_onion_service_aiohttp.py

docs/introduction.rst

@@ -7,21 +7,25 @@ txtorcon is an implementation of the `control-spec
 <https://gitweb.torproject.org/torspec.git/blob/HEAD:/control-spec.txt>`_
 for `Tor <https://www.torproject.org/projects/projects.html.en>`_
 using the `Twisted <https://twistedmatrix.com/trac/>`_ networking
-library for `Python <http://python.org/>`_.
-
-With txtorcon you can launch tor; connect to already-running tor
-instances; use tor as a client (via SOCKS5); set up services over tor;
-change all aspects of configuration; track live state (active circuits
-and streams, etc); do DNS via Tor; and query other information from
-the tor daemon.
-
-txtorcon would be of interest to anyone wishing to write event-based
+library for `Python <http://python.org/>`_ (*supports Py2, PyPy and
+Py3*).
+
+**txtorcon gives you a live view of all Tor state and the ability to
+control most aspects of Tor's operation**. With txtorcon you can
+launch tor; connect to already-running tor instances; use tor as a
+client (via SOCKS5); set up (onion) services over tor; change all
+aspects of configuration; track live state (active circuits and
+streams, etc); do DNS via Tor; and query other information from the
+tor daemon.
+
+txtorcon is the library to use if you want to write event-based
 software in Python that uses the Tor network as a client or a service
-(or just wants to display information about a locally running
-tor). Twisted already provides many robust protocol implementations,
-deployment, logging and integration with GTK, Qt and other graphics
-frameworks -- so txtorcon can be used for command-line or GUI
-applications or integrate with long-lived daemons easily.
+(or **integrate Tor support for existing Twisted-using applications**,
+or display information about a locally running tor). Twisted already
+provides many robust protocol implementations, deployment, logging and
+integration with GTK, Qt and other graphics frameworks -- so txtorcon
+can be used for command-line or GUI applications or integrate with
+long-lived daemons easily.
 
 In fact, due to support for endpoints (adding the ``tor:`` and
 ``onion:`` plugins), many Twisted applications can now integrate with
@@ -31,11 +35,18 @@ directory over an onion service:
 
 .. code-block:: shell-session
 
-   $ sudo apt-get install python-txtorcon
+   $ sudo apt-get install --install-suggests python-txtorcon
    $ twistd web --port "onion:80" --path ~/public_html
 
+(You should ideally enable the `Tor project repositories
+<https://www.torproject.org/docs/debian.html.en>`_ first).
+
 txtorcon strives to provide sane and **safe** defaults. txtorcon is `a
-Tor project <https://www.torproject.org/projects/projects.html.en>`_.
+Tor project
+<https://www.torproject.org/projects/projects.html.en>`_. The
+applications `Tahoe-LAFS <https://tahoe-lafs.org>`_ and `Crossbar.io
+<https://crossbar.io>`_ have successfully integrated Tor support using
+txtorcon.
 
 
 .. _features:
@@ -95,6 +106,7 @@ Known Users
 
 - `magic-wormhole <https://github.com/warner/magic-wormhole>`_ "get things from one computer to another, safely"
 - `Tahoe-LAFS <https://tahoe-lafs.org>`_ a Free and Open encrypted distributed storage system
+- `Crossbar.io <https://crossbar.io>`_ a Free and Open distributed-systems (RPC and PubSub) protocol (called WAMP) router. Supports e2e-encrypted payloads.
 - txtorcon received a brief mention `at 29C3 <http://media.ccc.de/browse/congress/2012/29c3-5306-en-the_tor_software_ecosystem_h264.html>`_ starting at 12:20 (or via `youtube <http://youtu.be/yG2-ci95h78?t=12m27s>`_).
 - `carml <https://github.com/meejah/carml>`_ command-line utilities for Tor
 - `foolscap <https://github.com/warner/foolscap/>`_ RPC system inspired by Twisted's built-in "Perspective Broker" package.

docs/release-checklist.rst

@@ -12,6 +12,10 @@ Release Checklist
 * run all tests, on all configurations
    * "tox"
 
+* ensure long_description will render properly:
+   * python setup.py check -r -s
+   * tox -e readme_render
+
 * "make pep8" should run cleanly (ideally)
 
 * update docs/releases.rst to reflect upcoming reality
@@ -19,7 +23,7 @@ Release Checklist
    * update heading, date
 
 * on both signing-machine and build-machine shells:
-   * export VERSION=0.19.3
+   * export VERSION=18.0.0
 
 * (if on signing machine) "make dist" and "make dist-sigs"
    * creates:
@@ -35,11 +39,11 @@ Release Checklist
      * gpg --no-version --detach-sign --armor --local-user meejah@meejah.ca txtorcon-${VERSION}-py2-none-any.whl
      * gpg --no-version --detach-sign --armor --local-user meejah@meejah.ca txtorcon-${VERSION}.tar.gz
   * copy signatures back to build machine, in dist/
-  * double-check that they validate
-     * gpg --verify dist/txtorcon-${VERSION}-py2-none-any.whl.asc
-     * gpg --verify dist/txtorcon-${VERSION}.tar.gz.asc
+  * double-check that they validate::
+     gpg --verify dist/txtorcon-${VERSION}-py2.py3-none-any.whl.asc
+     gpg --verify dist/txtorcon-${VERSION}.tar.gz.asc
 
-* generate sha256sum for each:
+* generate sha256sum for each::
      sha256sum dist/txtorcon-${VERSION}.tar.gz dist/txtorcon-${VERSION}-py2.py3-none-any.whl
 
 * copy signature files to <root of dist>/signatures and commit them
@@ -72,6 +76,11 @@ Release Checklist
               http://timaq4ygg2iegci7.onion/txtorcon-0.12.0.tar.gz
               http://timaq4ygg2iegci7.onion/txtorcon-0.12.0.tar.gz.asc
 
+           Or via a "version 3" service:
+
+              http://fjblvrw2jrxnhtg67qpbzi45r7ofojaoo3orzykesly2j3c2m3htapid.onion/txtorcon-18.0.0.tar.gz
+              http://fjblvrw2jrxnhtg67qpbzi45r7ofojaoo3orzykesly2j3c2m3htapid.onion/txtorcon-18.0.0.tar.gz.asc
+
            You can verify the sha256sum of both by running the following 4 lines
            in a shell wherever you have the files downloaded:
 
@@ -101,7 +110,7 @@ Release Checklist
    * verify sigs
    * verify sha256sums versus announcement text
    * verify tag (git tag --verify v${VERSION}) on machine other than signing-machine
-   * run: ./scripts/download-release-onion.sh
+   * run: ./scripts/download-release-onion.sh ${VERSION}
 
 * upload release
    * to PyPI: "make release" (which uses twine so this isn't the same step as "sign the release")

docs/releases.rst

@@ -7,16 +7,131 @@ There isn't a "release schedule" in any sense. If there is something
 in master your project depends upon, let me know and I'll do a
 release.
 
-Starting after v0.19.0 versions are following `calendar versioning
-<http://calver.org/>`_ with the major version being the 2-digit
-year. The second digit will be "non-trivial" releases and the third
-will be for bugfix releases.
+txtorcon follows `calendar versioning <http://calver.org/>`_ with the
+major version being the 2-digit year. The second digit will be
+"non-trivial" releases and the third will be for bugfix releases. So
+the second release in 2019 would be "19.2.0" and a bug-fix release of
+that will be "19.2.1".
+
+See also :ref:`api_stability`.
 
 
 unreleased
 ----------
 
-`git master <https://github.com/meejah/txtorcon>`_ *will likely become v17.0.0*
+`git master <https://github.com/meejah/txtorcon>`_ *will likely become v19.0.0*
+
+v18.0.2
+-------
+
+July 2, 2018
+
+ * `txtorcon-18.0.2.tar.gz <http://timaq4ygg2iegci7.onion/txtorcon-18.0.2.tar.gz>`_ (`PyPI <https://pypi.python.org/pypi/txtorcon/18.0.2>`_ (:download:`local-sig </../signatues/txtorcon-18.0.2.tar.gz.asc>` or `github-sig <https://github.com/meejah/txtorcon/blob/master/signatues/txtorcon-18.0.2.tar.gz.asc?raw=true>`_) (`source <https://github.com/meejah/txtorcon/archive/v18.0.2.tar.gz>`_)
+ * Python3.4 doesn't support async-def or await
+
+
+v18.0.1
+-------
+
+June 30, 2018
+
+ * `txtorcon-18.0.1.tar.gz <http://timaq4ygg2iegci7.onion/txtorcon-18.0.1.tar.gz>`_ (`PyPI <https://pypi.python.org/pypi/txtorcon/18.0.1>`_ (:download:`local-sig </../signatues/txtorcon-18.0.1.tar.gz.asc>` or `github-sig <https://github.com/meejah/txtorcon/blob/master/signatues/txtorcon-18.0.1.tar.gz.asc?raw=true>`_) (`source <https://github.com/meejah/txtorcon/archive/v18.0.1.tar.gz>`_)
+ * fix a Python2/3 regression when parsing onion services
+
+
+v18.0.0
+-------
+
+June 21, 2018
+
+ * `txtorcon-18.0.0.tar.gz <http://timaq4ygg2iegci7.onion/txtorcon-18.0.0.tar.gz>`_ (`PyPI <https://pypi.python.org/pypi/txtorcon/18.0.0>`_ (:download:`local-sig </../signatues/txtorcon-18.0.0.tar.gz.asc>` or `github-sig <https://github.com/meejah/txtorcon/blob/master/signatues/txtorcon-18.0.0.tar.gz.asc?raw=true>`_) (`source <https://github.com/meejah/txtorcon/archive/v18.0.0.tar.gz>`_)
+
+ * `await_all_uploads` options when creating Onions
+ * properly re-map progress percentages (including descriptor uploads)
+ * properly wait for all event-listeners during startup
+ * re-work how `TorState.event_map` works, hopefully reducing
+   reproducible-builds issues
+ * :meth:`txtorcon.TorControlProtocol.add_event_listener` and
+   :meth:`txtorcon.TorControlProtocol.remove_event_listener` are now
+   async methods returning Deferred -- they always should have been; new
+   code can now be assured that the event-listener change is known to Tor
+   by awaiting this Deferred.
+ * :meth:`txtorcon.TorControlProtocol.get_conf_single` method added, which
+   gets and returns (asynchronously) a single GETCONF key (instead of a dict)
+ * also :meth:`txtorcon.TorControlProtocol.get_info_single` similar to above
+ * if Tor disconnects while a command is in-progress or pending, the
+   `.errback()` for the corresponding Deferred is now correctly fired
+   (with a :class:`txtorcon.TorDisconnectError`
+
+ * tired: `get_global_tor()` (now deprecated)
+   wired: :meth:`txtorcon.get_global_tor_instance`
+
+ * Adds a comprehensive set of Onion Services APIs (for all six
+   variations). For non-authenticated services, instances of
+   :class:`txtorcon.IOnionService` represent services; for
+   authenticated services, instances of
+   :class:`txtorcon.IAuthenticatedOnionClients` encapsulated named
+   lists of clients (each client is an instance implementing
+   `IOnionService`).
+ * Version 3 ("Proposition 279") Onion service support (same APIs) as
+   released in latest Tor
+ * Four new methods to handle creating endpoints for Onion services
+   (either ephemeral or not and authenticated or not):
+   ** :method:`txtorcon.Tor.create_authenticated_onion_endpoint`
+   ** :method:`txtorcon.Tor.create_authenticated_filesystem_onion_endpoint`
+   ** :method:`txtorcon.Tor.create_onion_endpoint`
+   ** :method:`txtorcon.Tor.create_filesystem_onion_endpoint`
+ * see :ref:`create_onion` for information on how to choose an
+   appropriate type of Onion Service.
+
+ * :method:`txtorcon.Tor.create_onion_service` to add a new ephemeral
+   Onion service to Tor. This uses the `ADD_ONION` command under the
+   hood and can be version 2 or version 3. Note that there is an
+   endpoint-style API as well so you don't have to worry about mapping
+   ports yourself (see below).
+ * :method:`txtorcon.Tor.create_filesystem_onion_service` to add a new
+   Onion service to Tor with configuration (private keys) stored in a
+   provided directory. These can be version 2 or version 3
+   services. Note that there is an endpoint-style API as well so you
+   don't have to worry about mapping ports yourself (see below).
+
+ * Additional APIs to make visiting authenticated Onion services as a
+   client easier:
+
+ * :method:`txtorcon.Tor.add_onion_authentication` will add a
+   client-side Onion service authentication token. If you add a token
+   for a service which already has a token, it is an error if they
+   don't match. This corresponds to `HidServAuth` lines in torrc.
+ * :method:`txtorcon.Tor.remove_onion_authentication` will remove a
+   previously added client-side Onion service authentication
+   token. Fires with True if such a token existed and was removed or
+   False if no existing token was found.
+ * :method:`txtorcon.Tor.onion_authentication` (Python3 only) an async
+   context-manager that adds and removes an Onion authentication token
+   (i.e. adds in on `__aenter__` and removes it on `__aexit__`).
+ * onion services support listening on Unix paths.
+ * make sure README renders on Warehouse/PyPI
+
+
+v0.20.0
+-------
+
+February 22, 2018
+
+ * `txtorcon-0.20.0.tar.gz <http://timaq4ygg2iegci7.onion/txtorcon-0.20.0.tar.gz>`_ (`PyPI <https://pypi.python.org/pypi/txtorcon/0.20.0>`_ (:download:`local-sig </../signatues/txtorcon-0.20.0.tar.gz.asc>` or `github-sig <https://github.com/meejah/txtorcon/blob/master/signatues/txtorcon-0.20.0.tar.gz.asc?raw=true>`_) (`source <https://github.com/meejah/txtorcon/archive/v0.20.0.tar.gz>`_)
+
+ * doc fixes from `hotelzululima <https://twitter.com/hotelzululima>`_
+ * fix endpoints so `.connect` on them works properly more than once
+   from `Brian Warner <https://github.com/warner>`_
+ * allow a `CertificateOptions` to be passed as `tls=` to endpoints
+ * add method :func:`txtorcon.Tor.is_ready`
+ * add method :func:`txtorcon.Tor.become_ready`
+ * fix handling of certain defaults (`*PortLines` and friends)
+ * fix last router (usually) missing with (new) `MicroDescriptorParser`
+ * use OnionOO via Onion service `tgel7v4rpcllsrk2.onion` for :func:`txtorcon.Router.get_onionoo_details`
+ * fix parsing of Router started-times
+ * `Issue 255 <https://github.com/meejah/txtorcon/issues/255>`_ removed routers now deleted following NEWCONSENSUS
+ * `Issue 279 <https://github.com/meejah/txtorcon/issues/279>`_ remember proxy endpoint
 
 
 v0.19.3
@@ -175,6 +290,15 @@ v0.15.0
  * fix `issue 176 <https://github.com/meejah/txtorcon/issues/176>`_
 
 
+v0.14.2
+-------
+
+*December 2, 2015*
+
+ * `txtorcon-0.14.2.tar.gz <http://timaq4ygg2iegci7.onion/txtorcon-0.14.2.tar.gz>`_ (`PyPI <https://pypi.python.org/pypi/txtorcon/0.14.2>`_ (:download:`local-sig </../signatues/txtorcon-0.14.2.tar.gz.asc>` or `github-sig <https://github.com/meejah/txtorcon/blob/master/signatues/txtorcon-0.14.2.tar.gz.asc?raw=true>`_) (`source <https://github.com/meejah/txtorcon/archive/v0.14.2.tar.gz>`_)
+ * compatibility for Twisted 15.5.0 (released on 0.14.x for `OONI <http://ooni.io/>`_)
+
+
 v0.14.1
 -------
 
@@ -434,7 +558,7 @@ June 1, 2012
  * faster TorState startup;
  * SAFECOOKIE support;
  * several bug fixes;
- * options to :ref:`circuit_failure_rates.py` example to make it actually-useful;
+ * options to `circuit_failure_rates.py` example to make it actually-useful;
  * include built documentation + sources in tarball;
  * include tests in tarball;
  * improved logging;

docs/txtorcon-controller.rst

@@ -6,19 +6,17 @@ This is the recommended API. See the :ref:`programming_guide` for
 
 
 Tor
-----
+---
 .. autoclass:: txtorcon.Tor
 
 
 connect
 -------
 
-# FIXME why doesn't "txtorcon.connect" work here with automethod??
-
-.. method:: txtorcon.connect
+.. automethod:: txtorcon.controller.connect
 
 
 launch
 ------
 
-.. method:: txtorcon.launch
+.. automethod:: txtorcon.controller.launch

docs/txtorcon-endpoints.rst

@@ -32,9 +32,3 @@ IProgressProvider
 -----------------
 
 .. autointerface:: txtorcon.IProgressProvider
-
-
-IHiddenService
---------------
-
-.. autointerface:: txtorcon.IHiddenService

docs/txtorcon-interface.rst

 :mod:`txtorcon.interface` Module
 ================================
 
+Note: the Onion interfaces are defined in :ref:`onion_api`
+
 interface.IStreamAttacher
 -------------------------
 .. autointerface:: txtorcon.interface.IStreamAttacher

docs/txtorcon-onion.rst

+.. _onion_api:
+
+Onion APIs
+==========
+
+See the :ref:`programming_guide` for "prose" documentation of these
+(and other) APIs.
+
+For non-authenticated services:
+
+IOnionService
+-------------
+.. autointerface:: txtorcon.IOnionService
+
+IFilesystemOnionService
+-----------------------
+.. autointerface:: txtorcon.IFilesystemOnionService
+
+
+
+Both kinds of authenticated service (ephemeral or disk) implement
+these interfaces:
+
+IAuthenticatedOnionClients
+--------------------------
+.. autointerface:: txtorcon.IAuthenticatedOnionClients
+
+IOnionClient
+------------
+.. autointerface:: txtorcon.IOnionClient
+
+
+Concrete classes implementing specific variations of Onion
+services. First, ephemeral services (private keys do not live on
+disk). See :ref:`server_use` for an overview of the variations.
+
+EphemeralOnionService
+---------------------
+.. autoclass:: txtorcon.EphemeralOnionService
+
+EphemeralAuthenticatedOnionService
+----------------------------------
+.. autoclass:: txtorcon.EphemeralAuthenticatedOnionService
+
+EphemeralAuthenticatedOnionServiceClient
+----------------------------------------
+.. autoclass:: txtorcon.EphemeralAuthenticatedOnionServiceClient
+
+
+Onion services which store their secret keys on disk:
+
+FilesystemOnionService
+----------------------
+.. autoclass:: txtorcon.FilesystemOnionService
+
+FilesystemAuthenticatedOnionService
+-----------------------------------
+.. autoclass:: txtorcon.FilesystemAuthenticatedOnionService
+
+FilesystemAuthenticatedOnionServiceClient
+-----------------------------------------
+.. autoclass:: txtorcon.FilesystemAuthenticatedOnionServiceClient
+
+
+Some utility-style classes:
+
+AuthBasic
+---------
+.. autoclass:: txtorcon.AuthBasic
+
+AuthStealth
+-----------
+.. autoclass:: txtorcon.AuthStealth
+

docs/txtorcon.rst

@@ -14,6 +14,7 @@ place to start**.
     txtorcon-state
     txtorcon-config
     txtorcon-endpoints
+    txtorcon-onion
     txtorcon-protocol
     txtorcon-socks
     txtorcon-interface