[tor-commits] [stem/master] More documentation

atagar at torproject.org atagar at torproject.org
Sat Oct 13 18:35:44 UTC 2012


commit e7cc83b4e382d209dda4660b5d30b9691f3fd713
Author: Ravi Chandra Padmala <neenaoffline at gmail.com>
Date:   Tue Aug 7 13:48:24 2012 +0530

    More documentation
---
 stem/descriptor/networkstatus.py |   51 ++++++++++++++++++++++++++++---------
 1 files changed, 38 insertions(+), 13 deletions(-)

diff --git a/stem/descriptor/networkstatus.py b/stem/descriptor/networkstatus.py
index a9b23e2..c9b86a1 100644
--- a/stem/descriptor/networkstatus.py
+++ b/stem/descriptor/networkstatus.py
@@ -62,7 +62,7 @@ def parse_file(document_file, validate = True):
   :param file document_file: file with network status document content
   :param bool validate: checks the validity of the document's contents if True, skips these checks otherwise
   
-  :returns: iterator for  :class:`stem.descriptor.networkstatus.RouterDescriptor` instances in the file
+  :returns: iterator for :class:`stem.descriptor.networkstatus.RouterDescriptor` instances in the file
   
   :raises:
     * ValueError if the contents is malformed and validate is True
@@ -86,9 +86,9 @@ class NetworkStatusDocument(stem.descriptor.Descriptor):
   :var bool validated: **\*** whether the document is validated
   :var str network_status_version: **\*** a document format version. For v3 documents this is "3"
   :var str vote_status: **\*** status of the vote (is either "vote" or "consensus")
-  :var list consensus_methods: A list of supported consensus generation methods (integers)
-  :var datetime published: time when the document was published
-  :var int consensus_method: consensus method used to generate a consensus
+  :var list consensus_methods: **^** A list of supported consensus generation methods (integers)
+  :var datetime published: **^** time when the document was published
+  :var int consensus_method: **~** consensus method used to generate a consensus
   :var datetime valid_after: **\*** time when the consensus becomes valid
   :var datetime fresh_until: **\*** time until when the consensus is considered to be fresh
   :var datetime valid_until: **\*** time until when the consensus is valid
@@ -100,10 +100,12 @@ class NetworkStatusDocument(stem.descriptor.Descriptor):
   :var list params: dict of parameter(str) => value(int) mappings
   :var list router_descriptors: **\*** iterator for RouterDescriptor objects defined in the document
   :var list directory_authorities: **\*** list of DirectoryAuthority objects that have generated this document
-  :var dict bandwidth_weights: dict of weight(str) => value(int) mappings
+  :var dict bandwidth_weights: **~** dict of weight(str) => value(int) mappings
   :var list directory_signatures: **\*** list of signatures this document has
   
-  **\*** attribute is either required when we're parsed with validation or has a default value, others are left as None if undefined
+  | **\*** attribute is either required when we're parsed with validation or has a default value, others are left as None if undefined
+  | **^** attribute appears only in votes
+  | **~** attribute appears only in consensuses
   """
   
   def __init__(self, raw_content, validate = True):
@@ -247,9 +249,13 @@ class DirectoryAuthority(stem.descriptor.Descriptor):
   :var int dirport: current directory port
   :var int orport: current orport
   :var str contact: directory authority's contact information
-  :var str legacy_dir_key: fingerprint of and obsolete identity key
-  :var :class:`stem.descriptor.KeyCertificate` key_certificate: directory authority's current key certificate
-  :var str vote_digest: digest of the authority that contributed to the consensus
+  :var str legacy_dir_key: **^** fingerprint of and obsolete identity key
+  :var :class:`stem.descriptor.KeyCertificate` key_certificate: **^** directory authority's current key certificate
+  :var str vote_digest: **~** digest of the authority that contributed to the consensus
+  
+  | **^** attribute appears only in votes
+  | **~** attribute appears only in consensuses
+  | legacy_dir_key is the only optional attribute
   """
   
   def __init__(self, raw_content, vote = True, validate = True):
@@ -280,9 +286,18 @@ class DirectoryAuthority(stem.descriptor.Descriptor):
       self.key_certificate = stem.descriptor.KeyCertificate("\n".join(parser.remaining()), validate)
     else:
       self.vote_digest = parser.read_keyword_line("vote-digest", True)
-    rmng = parser.remaining()
-    if rmng and validate:
+    self._unrecognized_lines = parser.remaining()
+    if self._unrecognized_lines and validate:
       raise ValueError("Unrecognized trailing data in directory authority information")
+  
+  def get_unrecognized_lines(self):
+    """
+    Returns any unrecognized lines.
+    
+    :returns: a list of unrecognized lines
+    """
+    
+    return self._unrecognized_lines
 
 class DirectorySignature(stem.descriptor.Descriptor):
   """
@@ -320,6 +335,15 @@ class DirectorySignature(stem.descriptor.Descriptor):
     self._unrecognized_lines = parser.remaining()
     if self._unrecognized_lines and validate:
       raise ValueError("Unrecognized trailing data in directory signature")
+  
+  def get_unrecognized_lines(self):
+    """
+    Returns any unrecognized lines.
+    
+    :returns: a list of unrecognized lines
+    """
+    
+    return self._unrecognized_lines
 
 class RouterDescriptor(stem.descriptor.Descriptor):
   """
@@ -354,11 +378,12 @@ class RouterDescriptor(stem.descriptor.Descriptor):
   :var int bandwidth: router's claimed bandwidth
   :var int measured_bandwidth: router's measured bandwidth
   
-  :var :class:`stem.exit_policy.MicrodescriptorExitPolicy` exitpolicy: router's exitpolicy
+  :var :class:`stem.exit_policy.MicrodescriptorExitPolicy` exit_policy: router's exit policy
   
   :var str microdescriptor_hashes: a list of two-tuples with a list of consensus methods(int) that may produce the digest and a dict with algorithm(str) => digest(str) mappings. algorithm is the hashing algorithm (usually "sha256") that is used to produce digest (the base64 encoding of the hash of the router's microdescriptor with trailing =s omitted).
   
-  **\*** attribute is either required when we're parsed with validation or has a default value, others are left as None if undefined
+  | **\*** attribute is either required when we're parsed with validation or has a default value, others are left as None if undefined
+  | exit_policy appears only in votes
   """
   
   def __init__(self, raw_contents, vote = True, validate = True):





More information about the tor-commits mailing list