[tor-commits] [stem/master] Move authority docs into module header

[atagar at torproject.org]

commit d99d6470ccc50eeefec056f2305cdacd05e07eef
Author: Damian Johnson <atagar at torproject.org>
Date:   Sat May 5 14:44:57 2018 -0700

    Move authority docs into module header
    
    This more expansive explanation of how tor works belongs in our module docs,
    not this particular class.
---
 stem/directory.py | 62 +++++++++++++++++++++++++++----------------------------
 1 file changed, 30 insertions(+), 32 deletions(-)

diff --git a/stem/directory.py b/stem/directory.py
index 4190e885..2982f4d0 100644
--- a/stem/directory.py
+++ b/stem/directory.py
@@ -2,16 +2,38 @@
 # See LICENSE for licensing information
 
 """
-Directories with Tor descriptor information.
+Directories with `tor descriptor information
+<../tutorials/mirror_mirror_on_the_wall.html>`_. At a very high level tor works
+as follows...
+
+1. Volunteer starts a new tor relay, during which it sends a `server
+   descriptor <descriptor/server_descriptor.html>`_ to each of the directory
+   authorities.
+
+2. Each hour the directory authorities make a `vote
+   <descriptor/networkstatus.html>`_  that says who they think the active
+   relays are in the network and some attributes about them.
+
+3. The directory authorities send each other their votes, and compile that
+   into the `consensus <descriptor/networkstatus.html>`_. This document is very
+   similar to the votes, the only difference being that the majority of the
+   authorities agree upon and sign this document. The idividual relay entries
+   in the vote or consensus is called `router status entries
+   <descriptor/router_status_entry.html>`_.
+
+4. Tor clients (people using the service) download the consensus from an
+   authority, fallback, or other mirror to determine who the active relays in
+   the network are. They then use this to construct circuits and use the
+   network.
 
 ::
 
-  Directory - Relay we can retrieve directory information from
-    | |- from_cache - Provides fallback directories cached with Stem.
-    | +- from_remote - Retrieves fallback directories remotely from tor's latest commit.
+  Directory - Relay we can retrieve descriptor information from
+    | |- from_cache - Provides cached information bundled with Stem.
+    | +- from_remote - Downloads the latest directory information from tor.
     |
-    |- Authority - Information about a tor directory authority
-    +- Fallback - Directory mirror tor uses when authories are unavailable
+    |- Authority - Tor directory authority
+    +- Fallback - Mirrors that can be used instead of the authorities
 
 .. versionadded:: 1.7.0
 """
@@ -149,28 +171,6 @@ class Authority(Directory):
   <https://gitweb.torproject.org/tor.git/plain/src/or/auth_dirs.inc>`_
   that enumerates the other relays within the network.
 
-  At a very high level tor works as follows...
-
-  1. A volunteer starts up a new tor relay, during which it sends a `server
-     descriptor <server_descriptor.html>`_ to each of the directory
-     authorities.
-
-  2. Each hour the directory authorities make a `vote <networkstatus.html>`_
-     that says who they think the active relays are in the network and some
-     attributes about them.
-
-  3. The directory authorities send each other their votes, and compile that
-     into the `consensus <networkstatus.html>`_. This document is very similar
-     to the votes, the only difference being that the majority of the
-     authorities agree upon and sign this document. The idividual relay entries
-     in the vote or consensus is called `router status entries
-     <router_status_entry.html>`_.
-
-  4. Tor clients (people using the service) download the consensus from one of
-     the authorities or a mirror to determine the active relays within the
-     network. They in turn use this to construct their circuits and use the
-     network.
-
   .. versionchanged:: 1.3.0
      Added the is_bandwidth_authority attribute.
 
@@ -319,14 +319,12 @@ class Fallback(Directory):
   ::
 
     import time
-    from stem.descriptor.remote import DescriptorDownloader
+    from stem.descriptor.remote import get_consensus
     from stem.directory import Fallback
 
-    downloader = DescriptorDownloader()
-
     for fallback in Fallback.from_cache().values():
       start = time.time()
-      downloader.get_consensus(endpoints = [(fallback.address, fallback.dir_port)]).run()
+      get_consensus(endpoints = [(fallback.address, fallback.dir_port)]).run()
       print('Downloading the consensus took %0.2f from %s' % (time.time() - start, fallback.fingerprint))
 
   ::