[tor-commits] [bridgedb/develop] Update Sphinx formatting in docstrings in bridgedb.parse.networkstatus.

[isis at torproject.org]

commit 0ff6962764d1b5b3995e2b5efae6ffa1923a909e
Author: Isis Lovecruft <isis at torproject.org>
Date:   Tue Apr 22 23:17:27 2014 +0000

    Update Sphinx formatting in docstrings in bridgedb.parse.networkstatus.
---
 lib/bridgedb/parse/networkstatus.py |   57 ++++++++++++++++++++---------------
 1 file changed, 32 insertions(+), 25 deletions(-)

diff --git a/lib/bridgedb/parse/networkstatus.py b/lib/bridgedb/parse/networkstatus.py
index 9304009..8592cd3 100644
--- a/lib/bridgedb/parse/networkstatus.py
+++ b/lib/bridgedb/parse/networkstatus.py
@@ -5,23 +5,27 @@
 # :authors: Isis Lovecruft 0xA3ADB67A2CDB8B35 <isis at torproject.org>
 #           please also see AUTHORS file
 # :copyright: (c) 2013 Isis Lovecruft
-#             (c) 2007-2013, The Tor Project, Inc.
-#             (c) 2007-2013, all entities within the AUTHORS file
+#             (c) 2007-2014, The Tor Project, Inc.
+#             (c) 2007-2014, all entities within the AUTHORS file
 # :license: 3-clause BSD, see included LICENSE for information
 
-"""Parsers for ``@type bridge-network-status 1.0`` descriptors.
+"""Parsers for bridge networkstatus descriptors.
 
+.. py:module:: bridgedb.parse.networkstatus
+   :synopsis: Parsers for ``@type bridge-network-status`` descriptors_.
 .. _descriptors: https://metrics.torproject.org/formats.html#descriptortypes
 
-**Module Overview:**
 
+bridgedb.parse.networkstatus
+============================
+::
+
+  networkstatus
+   |_ isValidRouterNickname - Determine if a nickname is according to spec
+   |_ parseRLine - Parse an 'r'-line from a networkstatus document
+   |_ parseALine - Parse an 'a'-line from a networkstatus document
+    \_ parseSLine - Parse an 's'-line from a networkstatus document
 ..
-  parse
-   \_networkstatus
-      |_ isValidRouterNickname - Determine if a nickname is according to spec
-      |_ parseRLine - Parse an 'r'-line from a networkstatus document
-      |_ parseALine - Parse an 'a'-line from a networkstatus document
-      \_ parseSLine - Parse an 's'-line from a networkstatus document
 """
 
 import binascii
@@ -67,25 +71,28 @@ def parseRLine(line):
     """Parse an 'r'-line from a networkstatus document.
 
     From torspec.git/dir-spec.txt, commit 36761c7d553d L1499-1512:
+      | "r" SP nickname SP identity SP digest SP publication SP IP SP ORPort
+      |     SP DirPort NL
       |
-      |"r" SP nickname SP identity SP digest SP publication SP IP SP ORPort
-      |    SP DirPort NL
-      |
-      |    [At start, exactly once.]
-      |
-      |    "Nickname" is the OR's nickname.  "Identity" is a hash of its
-      |    identity key, encoded in base64, with trailing equals sign(s)
-      |    removed.  "Digest" is a hash of its most recent descriptor as
-      |    signed (that is, not including the signature), encoded in base64.
-      |    "Publication" is the
-      |    publication time of its most recent descriptor, in the form
-      |    YYYY-MM-DD HH:MM:SS, in UTC.  "IP" is its current IP address;
-      |    ORPort is its current OR port, "DirPort" is its current directory
-      |    port, or "0" for "none".
+      |     [At start, exactly once.]
       |
+      |     "Nickname" is the OR's nickname.  "Identity" is a hash of its
+      |     identity key, encoded in base64, with trailing equals sign(s)
+      |     removed.  "Digest" is a hash of its most recent descriptor as
+      |     signed (that is, not including the signature), encoded in base64.
+      |     "Publication" is the
+      |     publication time of its most recent descriptor, in the form
+      |     YYYY-MM-DD HH:MM:SS, in UTC.  "IP" is its current IP address;
+      |     ORPort is its current OR port, "DirPort" is its current directory
+      |     port, or "0" for "none".
 
     :param string line: An 'r'-line from an bridge-network-status descriptor.
-
+    :returns:
+        A 7-tuple of::
+            (nickname, identityDigest, descriptorDigest, timestamp,
+             orAddress, orPort, dirport)
+        where each value is set according to the data parsed from the
+        **line**, or ``None`` if nothing suitable could be parsed.
     """
     (nickname, ID, descDigest, timestamp,
      ORaddr, ORport, dirport) = (None for x in xrange(7))