[tor-commits] [stem/master] Rewriting network status module pydocs

[atagar at torproject.org]

commit 3ddd3c55da9b859dcce218283ee91aab251bf230
Author: Damian Johnson <atagar at torproject.org>
Date:   Mon Oct 8 09:27:57 2012 -0700

    Rewriting network status module pydocs
    
    Revising the header documentation for the network status document module. The
    bit about v2 support is presently a lie, and I need to include the examples in
    the tests. Otherwise, this module is almost done!
---
 stem/descriptor/networkstatus.py |   78 +++++++++++++++++++++++--------------
 1 files changed, 48 insertions(+), 30 deletions(-)

diff --git a/stem/descriptor/networkstatus.py b/stem/descriptor/networkstatus.py
index 91c50e6..f6116c5 100644
--- a/stem/descriptor/networkstatus.py
+++ b/stem/descriptor/networkstatus.py
@@ -1,55 +1,73 @@
 """
-Parsing for Tor network status documents. Currently supports parsing v3 network
-status documents (both votes and consensuses).
-
-The network status documents also contain a list of router descriptors,
-directory authorities, signatures etc. If you only need the
-:class:`stem.descriptor.router_status_entry.RouterStatusEntry` objects, use
-:func:`stem.descriptor.parse_file`. Other information can be accessed by
-directly instantiating :class:`stem.descriptor.networkstatus.NetworkStatusDocument`
-objects.
-
-The documents can be obtained from any of the following sources...
+Parsing for Tor network status documents. This supports both the v2 and v3
+dir-spec. Documents can be obtained from a few sources...
 
 * the 'cached-consensus' file in tor's data directory
 * tor metrics, at https://metrics.torproject.org/data.html
 * directory authorities and mirrors via their DirPort
 
+... and contain the following sections...
+
+* document header
+* list of :class:`stem.descriptor.networkstatus.DirectoryAuthority`
+* list of :class:`stem.descriptor.router_status_entry.RouterStatusEntry`
+* document footer
+
+Of these, the router status entry section can be quite large (on the order of
+hundreds of kilobytes). As such we provide a couple methods of reading network
+status documents...
+
+* :class:`stem.descriptor.networkstatus.NetworkStatusDocument` constructor
+
+If read time and memory aren't a concern then you can simply use the document
+constructor. Router entries are assigned to its 'routers' attribute...
+
 ::
 
-  import stem.descriptor.networkstatus
+  from stem.descriptor.networkstatus import NetworkStatusDocument
   
-  nsdoc_file = open("/home/neena/.tor/cached-consensus")
-  try:
-    consensus = stem.descriptor.networkstatus.parse_file(nsdoc_file)
-  except ValueError:
-    print "Invalid cached-consensus file"
+  with open('.tor/cached-consensus', 'r') as consensus_file:
+    # Reads the full consensus into memory twice (both for the parsed and
+    # unparsed contents).
+    
+    consensus = NetworkStatusDocument(consensus_file.read())
+    
+    for router in consensus.routers:
+      print router.nickname
+
+* :func:`stem.descriptor.parse_file`
+
+Alternatively, the parse_file() function provides an iterator for a document's
+routers. Those routers refer to a 'thin' document, which doesn't have a
+'routers' attribute. This allows for lower memory usage and upfront runtime.
+
+::
+
+  from stem.descriptor.networkstatus import parse_file
   
-  print "Consensus was valid between %s and %s" % (str(consensus.valid_after), str(consensus.valid_until))
+  with open('.tor/cached-consensus', 'r') as consensus_file:
+    # Processes the routers as we read them in. The routers refer to a document
+    # with an unset 'routers' attribute.
+    
+    for router in parse_file(consensus_file):
+      print router.nickname
 
 **Module Overview:**
 
 ::
 
-  parse_file - parses a network status file and provides a NetworkStatusDocument
-  NetworkStatusDocument - Tor v3 network status document
-    +- MicrodescriptorConsensus - Microdescriptor flavoured consensus documents
-  DocumentSignature - Signature of a document by a directory authority
-  DirectoryAuthority - Directory authority defined in a v3 network status document
+  parse_file - parses a network status file, providing an iterator for its routers
+  NetworkStatusDocument - Version 3 network status document.
+  DocumentSignature - Signature of a document by a directory authority.
+  DirectoryAuthority - Directory authority as defined in a v3 network status document.
 """
 
-import re
 import datetime
-
-try:
-  from cStringIO import StringIO
-except:
-  from StringIO import StringIO
+from StringIO import StringIO
 
 import stem.descriptor
 import stem.descriptor.router_status_entry
 import stem.version
-import stem.exit_policy
 import stem.util.tor_tools
 
 # Network status document are either a 'vote' or 'consensus', with different