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

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



commit 8ee4c14fe0784c82637f7d3bb0b6d496c44717c9
Author: Damian Johnson <atagar@xxxxxxxxxxxxxx>
Date:   Sat Oct 27 10:23:51 2012 -0700

    Revised API docs for stem.descriptor.router_status_entry
---
 docs/api.rst                            |    1 +
 docs/contents.rst                       |    1 +
 docs/descriptor/router_status_entry.rst |    5 +++
 stem/descriptor/router_status_entry.py  |   53 ++++++++++++++++++------------
 4 files changed, 39 insertions(+), 21 deletions(-)

diff --git a/docs/api.rst b/docs/api.rst
index b329c5a..637c634 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -15,6 +15,7 @@ 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.
+ * `stem.descriptor.router_status_entry <descriptor/router_status_entry.html>`_ - Relay entries within a network status document.
 
 * **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 6cbf63a..b142114 100644
--- a/docs/contents.rst
+++ b/docs/contents.rst
@@ -15,6 +15,7 @@ Contents
    descriptor/server_descriptor
    descriptor/extrainfo_descriptor
    descriptor/networkstatus
+   descriptor/router_status_entry
 
    types/exit_policy
    types/version
diff --git a/docs/descriptor/router_status_entry.rst b/docs/descriptor/router_status_entry.rst
new file mode 100644
index 0000000..90b2b01
--- /dev/null
+++ b/docs/descriptor/router_status_entry.rst
@@ -0,0 +1,5 @@
+Router Status Entries
+=====================
+
+.. automodule:: stem.descriptor.router_status_entry
+
diff --git a/stem/descriptor/router_status_entry.py b/stem/descriptor/router_status_entry.py
index a46d006..df0562c 100644
--- a/stem/descriptor/router_status_entry.py
+++ b/stem/descriptor/router_status_entry.py
@@ -3,7 +3,7 @@ Parsing for router status entries, the information for individual routers
 within a network status document. This information is provided from a few
 sources...
 
-* control port via 'GETINFO ns/*' and 'GETINFO md/*' queries
+* control port via 'GETINFO ns/\*' and 'GETINFO md/\*' queries
 * router entries in a network status document, like the cached-consensus
 
 **Module Overview:**
@@ -32,19 +32,22 @@ def parse_file(document_file, validate, entry_class, entry_keyword = "r", start_
   Either a end_position or section_end_keywords must be provided.
   
   :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 validate: checks the validity of the document's contents if
+    **True**, skips these checks otherwise
   :param class entry_class: class to construct instance for
   :param str entry_keyword: first keyword for the entry instances
   :param int start_position: start of the section, default is the current position
   :param int end_position: end of the section
-  :param tuple section_end_keywords: keyword(s) that deliminate the end of the section if no end_position was provided
-  :param tuple extra_args: extra arguments for the entry_class (after the content and validate flag)
+  :param tuple section_end_keywords: keyword(s) that deliminate the end of the
+    section if no end_position was provided
+  :param tuple extra_args: extra arguments for the entry_class (after the
+    content and validate flag)
   
   :returns: iterator over entry_class instances
   
   :raises:
-    * ValueError if the contents is malformed and validate is True
-    * IOError if the file can't be read
+    * **ValueError** if the contents is malformed and validate is **True**
+    * **IOError** if the file can't be read
   """
   
   if start_position is None:
@@ -76,7 +79,8 @@ class RouterStatusEntry(stem.descriptor.Descriptor):
   
   :var list flags: **\*** list of status flags
   
-  :var stem.version.Version version: parsed version of tor, this is None if the relay's using a new versioning scheme
+  :var stem.version.Version version: parsed version of tor, this is **None** if
+    the relay's using a new versioning scheme
   :var str version_line: versioning information reported by the relay
   """
   
@@ -86,9 +90,10 @@ class RouterStatusEntry(stem.descriptor.Descriptor):
     
     :param str content: router descriptor content to be parsed
     :param NetworkStatusDocument document: document this descriptor came from
-    :param bool validate: checks the validity of the content if True, skips these checks otherwise
+    :param bool validate: checks the validity of the content if **True**, skips
+      these checks otherwise
     
-    :raises: ValueError if the descriptor data is invalid
+    :raises: **ValueError** if the descriptor data is invalid
     """
     
     super(RouterStatusEntry, self).__init__(content)
@@ -118,9 +123,9 @@ class RouterStatusEntry(stem.descriptor.Descriptor):
     Parses the given content and applies the attributes.
     
     :param dict entries: keyword => (value, pgp key) entries
-    :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
     """
     
     for keyword, values in entries.items():
@@ -140,7 +145,7 @@ class RouterStatusEntry(stem.descriptor.Descriptor):
     
     :param dict entries: keyword => (value, pgp key) entries
     
-    :raises: ValueError if an issue arises in validation
+    :raises: **ValueError** if an issue arises in validation
     """
     
     for keyword in self._required_fields():
@@ -200,7 +205,8 @@ class RouterStatusEntryV2(RouterStatusEntry):
   
   :var str digest: **\*** router's digest
   
-  **\*** 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
   """
   
   def __init__(self, content, validate = True, document = None):
@@ -244,13 +250,16 @@ class RouterStatusEntryV3(RouterStatusEntry):
   
   :var int bandwidth: bandwidth claimed by the relay (in kb/s)
   :var int measured: bandwith measured to be available by the relay
-  :var list unrecognized_bandwidth_entries: **\*** bandwidth weighting information that isn't yet recognized
+  :var list unrecognized_bandwidth_entries: **\*** bandwidth weighting
+    information that isn't yet recognized
   
   :var stem.exit_policy.MicrodescriptorExitPolicy exit_policy: router's exit policy
   
-  :var list microdescriptor_hashes: tuples of two values, the list of consensus methods for generting a set of digests and the 'algorithm => digest' mappings
+  :var list microdescriptor_hashes: tuples of two values, the list of consensus
+    methods for generting a set of digests and the 'algorithm => digest' mappings
   
-  **\*** 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
   """
   
   def __init__(self, content, validate = True, document = None):
@@ -309,11 +318,13 @@ class RouterStatusEntryMicroV3(RouterStatusEntry):
   
   :var int bandwidth: bandwidth claimed by the relay (in kb/s)
   :var int measured: bandwith measured to be available by the relay
-  :var list unrecognized_bandwidth_entries: **\*** bandwidth weighting information that isn't yet recognized
+  :var list unrecognized_bandwidth_entries: **\*** bandwidth weighting
+    information that isn't yet recognized
   
   :var str digest: **\*** router's base64 encoded router microdescriptor digest
   
-  **\*** 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
   """
   
   def __init__(self, content, validate = True, document = None):
@@ -535,11 +546,11 @@ def _decode_fingerprint(identity, validate):
     'A7569A83B5706AB1B1A9CB52EFF7D2D32E4553EB'
   
   :param str identity: encoded fingerprint from the consensus
-  :param bool validate: checks validity if True
+  :param bool validate: checks validity if **True**
   
-  :returns: str with the uppercase hex encoding of the relay's fingerprint
+  :returns: **str** with the uppercase hex encoding of the relay's fingerprint
   
-  :raises: ValueError if the result isn't a valid fingerprint
+  :raises: **ValueError** if the result isn't a valid fingerprint
   """
   
   # trailing equal signs were stripped from the identity



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