[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]

[tor-commits] [stem/master] Revised API docs for stem.descriptor.networkstatus



commit 29f500874cb90aa6d9c3626a609dfc957950590f
Author: Damian Johnson <atagar@xxxxxxxxxxxxxx>
Date:   Sat Oct 27 09:42:03 2012 -0700

    Revised API docs for stem.descriptor.networkstatus
---
 docs/api.rst                      |    1 +
 docs/contents.rst                 |    1 +
 docs/descriptor/networkstatus.rst |    5 +++
 stem/descriptor/networkstatus.py  |   68 +++++++++++++++++++-----------------
 4 files changed, 43 insertions(+), 32 deletions(-)

diff --git a/docs/api.rst b/docs/api.rst
index 711f9d4..b329c5a 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -14,6 +14,7 @@ Descriptors
  * `stem.descriptor <descriptor/descriptor.html>`_ - Base class for descriptors.
  * `stem.descriptor.server_descriptor <descriptor/server_descriptor.html>`_ - Relay and bridge server descriptors.
  * `stem.descriptor.extrainfo_descriptor <descriptor/extrainfo_descriptor.html>`_ - Relay and bridge extrainfo descriptors.
+ * `stem.descriptor.networkstatus <descriptor/networkstatus.html>`_ - Network status documents which make up the Tor consensus.
 
 * **Utilities**
  * `stem.descriptor.reader <descriptor/reader.html>`_ - Reads and parses descriptor files from disk.
diff --git a/docs/contents.rst b/docs/contents.rst
index 90d61d1..6cbf63a 100644
--- a/docs/contents.rst
+++ b/docs/contents.rst
@@ -14,6 +14,7 @@ Contents
    descriptor/descriptor
    descriptor/server_descriptor
    descriptor/extrainfo_descriptor
+   descriptor/networkstatus
 
    types/exit_policy
    types/version
diff --git a/docs/descriptor/networkstatus.rst b/docs/descriptor/networkstatus.rst
new file mode 100644
index 0000000..44b8bb3
--- /dev/null
+++ b/docs/descriptor/networkstatus.rst
@@ -0,0 +1,5 @@
+Network Status Documents
+========================
+
+.. automodule:: stem.descriptor.networkstatus
+
diff --git a/stem/descriptor/networkstatus.py b/stem/descriptor/networkstatus.py
index e8a2679..61319e3 100644
--- a/stem/descriptor/networkstatus.py
+++ b/stem/descriptor/networkstatus.py
@@ -38,9 +38,10 @@ constructor. Router entries are assigned to its 'routers' attribute...
 
 * :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.
+Alternatively, the :func:`~stem.descriptor.networkstatus.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.
 
 ::
 
@@ -171,15 +172,15 @@ def parse_file(document_file, validate = True, is_microdescriptor = False, docum
   allow for limited memory usage.
   
   :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
-  :param bool is_microdescriptor: True if this is for a microdescriptor consensus, False otherwise
+  :param bool validate: checks the validity of the document's contents if **True**, skips these checks otherwise
+  :param bool is_microdescriptor: **True** if this is for a microdescriptor consensus, **False** otherwise
   :param int document_version: network status document version
   
   :returns: :class:`stem.descriptor.networkstatus.NetworkStatusDocument` object
   
   :raises:
-    * ValueError if the document_version is unrecognized or the contents is malformed and validate is True
-    * IOError if the file can't be read
+    * **ValueError** if the document_version is unrecognized or the contents is malformed and validate is **True**
+    * **IOError** if the file can't be read
   """
   
   # getting the document without the routers section
@@ -236,7 +237,7 @@ class NetworkStatusDocumentV2(NetworkStatusDocument):
   Version 2 network status document. These have been deprecated and are no
   longer generated by Tor.
   
-  :var tuple routers: RouterStatusEntryV2 contained in the document
+  :var tuple routers: :class:`~stem.descriptor.router_status_entry.RouterStatusEntryV2` contained in the document
   
   :var int version: **\*** document version
   
@@ -395,13 +396,13 @@ class NetworkStatusDocumentV3(NetworkStatusDocument):
   """
   Version 3 network status document. This could be either a vote or consensus.
   
-  :var tuple routers: RouterStatusEntryV3 contained in the document
+  :var tuple routers: :class:`~stem.descriptor.router_status_entry.RouterStatusEntryV3` contained in the document
   
   :var int version: **\*** document version
   :var str version_flavor: **\*** flavor associated with the document (such as 'microdesc')
-  :var bool is_consensus: **\*** true if the document is a consensus
-  :var bool is_vote: **\*** true if the document is a vote
-  :var bool is_microdescriptor: **\*** true if this is a microdescriptor flavored document, false otherwise
+  :var bool is_consensus: **\*** **True** if the document is a consensus
+  :var bool is_vote: **\*** **True** if the document is a vote
+  :var bool is_microdescriptor: **\*** **True** if this is a microdescriptor flavored document, **False** otherwise
   :var datetime valid_after: **\*** time when the consensus became valid
   :var datetime fresh_until: **\*** time when the next consensus should be produced
   :var datetime valid_until: **\*** time when this consensus becomes obsolete
@@ -410,15 +411,17 @@ class NetworkStatusDocumentV3(NetworkStatusDocument):
   :var list client_versions: list of recommended client tor versions
   :var list server_versions: list of recommended server tor versions
   :var list known_flags: **\*** list of known router flags
-  :var list params: **\*** dict of parameter(str) => value(int) mappings
-  :var list directory_authorities: **\*** list of DirectoryAuthority objects that have generated this document
-  :var list signatures: **\*** DocumentSignature of the authorities that have signed the document
+  :var list params: **\*** dict of parameter(**str**) => value(**int**) mappings
+  :var list directory_authorities: **\*** list of :class:`~stem.descriptor.networkstatus.DirectoryAuthority` objects that have generated this document
+  :var list signatures: **\*** :class:`~stem.descriptor.networkstatus.DocumentSignature` of the authorities that have signed the document
   
   **Consensus Attributes:**
+  
   :var int consensus_method: method version used to generate this consensus
   :var dict bandwidth_weights: dict of weight(str) => value(int) mappings
   
   **Vote Attributes:**
+  
   :var list consensus_methods: list of ints for the supported method versions
   :var datetime published: time when the document was published
   
@@ -427,14 +430,13 @@ class NetworkStatusDocumentV3(NetworkStatusDocument):
   
   def __init__(self, raw_content, validate = True, default_params = True):
     """
-    Parse a v3 network status document and provide a new
-    NetworkStatusDocumentV3 object.
+    Parse a v3 network status document.
     
     :param str raw_content: raw network status document data
-    :param bool validate: True if the document is to be validated, False otherwise
+    :param bool validate: **True** if the document is to be validated, **False** otherwise
     :param bool default_params: includes defaults in our params dict, otherwise it just contains values from the document
     
-    :raises: ValueError if the document is invalid
+    :raises: **ValueError** if the document is invalid
     """
     
     super(NetworkStatusDocumentV3, self).__init__(raw_content)
@@ -489,7 +491,7 @@ class NetworkStatusDocumentV3(NetworkStatusDocument):
     
     :param int method: consensus-method to check for
     
-    :returns: True if we meet the given consensus-method, and False otherwise
+    :returns: **True** if we meet the given consensus-method, and **False** otherwise
     """
     
     return self._header.meets_consensus_method(method)
@@ -780,9 +782,9 @@ def _check_for_missing_and_disallowed_fields(header, entries, fields):
   
   :param _DocumentHeader header: document header
   :param dict entries: ordered keyword/value mappings of the header or footer
-  :param list fields: expected field attributes (either HEADER_STATUS_DOCUMENT_FIELDS or FOOTER_STATUS_DOCUMENT_FIELDS)
+  :param list fields: expected field attributes (either **HEADER_STATUS_DOCUMENT_FIELDS** or **FOOTER_STATUS_DOCUMENT_FIELDS**)
   
-  :raises: ValueError if we're missing mandatory fields or have fiels we shouldn't
+  :raises: **ValueError** if we're missing mandatory fields or have fiels we shouldn't
   """
   
   missing_fields, disallowed_fields = [], []
@@ -810,9 +812,9 @@ def _check_for_misordered_fields(entries, expected):
   are ignored).
   
   :param dict entries: ordered keyword/value mappings of the header or footer
-  :param list expected: ordered list of expected fields (either HEADER_FIELDS or FOOTER_FIELDS)
+  :param list expected: ordered list of expected fields (either **HEADER_FIELDS** or **FOOTER_FIELDS**)
   
-  :raises: ValueError if entries aren't properly ordered
+  :raises: **ValueError** if entries aren't properly ordered
   """
   
   # Earlier validation has ensured that our fields either belong to our
@@ -880,11 +882,13 @@ class DirectoryAuthority(stem.descriptor.Descriptor):
   :var str contact: **\*** contact information
   
   **Consensus Attributes:**
+  
   :var str vote_digest: **\*** digest of the authority that contributed to the consensus
   
   **Vote Attributes:**
+  
   :var str legacy_dir_key: fingerprint of and obsolete identity key
-  :var :class:`stem.descriptor.networkstatus.KeyCertificate` key_certificate: **\*** authority's key certificate
+  :var stem.descriptor.networkstatus.KeyCertificate key_certificate: **\*** authority's key certificate
   
   **\*** mandatory attribute
   """
@@ -925,9 +929,9 @@ class DirectoryAuthority(stem.descriptor.Descriptor):
     
     :param str content: descriptor content
     :param bool validate: checks validity if True
-    :param bool is_vote: True if this is for a vote, False if it's for a consensus
+    :param bool is_vote: **True** if this is for a vote, **False** if it's for a consensus
     
-    :raises: ValueError if a validity check fails
+    :raises: **ValueError** if a validity check fails
     """
     
     # separate the directory authority entry from its key certificate
@@ -1091,9 +1095,9 @@ class KeyCertificate(stem.descriptor.Descriptor):
     Parses the given content and applies the attributes.
     
     :param str content: descriptor content
-    :param bool validate: checks validity if True
+    :param bool validate: checks validity if **True**
     
-    :raises: ValueError if a validity check fails
+    :raises: **ValueError** if a validity check fails
     """
     
     entries = stem.descriptor._get_descriptor_components(content, validate)
@@ -1194,7 +1198,7 @@ class KeyCertificate(stem.descriptor.Descriptor):
     """
     Returns any unrecognized lines.
     
-    :returns: a list of unrecognized lines
+    :returns: **list** of unrecognized lines
     """
     
     return self._unrecognized_lines
@@ -1213,9 +1217,9 @@ class DocumentSignature(object):
   :var str identity: fingerprint of the authority that made the signature
   :var str key_digest: digest of the signing key
   :var str signature: document signature
-  :param bool validate: checks validity if True
+  :param bool validate: checks validity if **True**
   
-  :raises: ValueError if a validity check fails
+  :raises: **ValueError** if a validity check fails
   """
   
   def __init__(self, method, identity, key_digest, signature, validate = True):



_______________________________________________
tor-commits mailing list
tor-commits@xxxxxxxxxxxxxxxxxxxx
https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-commits