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

atagar at torproject.org atagar at torproject.org
Sun Oct 28 20:56:34 UTC 2012


commit 2c4e518adf545633e05fc97bba4718f9aebe3396
Author: Damian Johnson <atagar at torproject.org>
Date:   Fri Oct 26 09:05:00 2012 -0700

    Revised API docs for stem.descriptor.server_descriptor
---
 docs/api.rst                          |    9 +++--
 docs/contents.rst                     |    1 +
 docs/descriptor/server_descriptor.rst |    5 +++
 stem/descriptor/server_descriptor.py  |   57 ++++++++++++++++++---------------
 4 files changed, 43 insertions(+), 29 deletions(-)

diff --git a/docs/api.rst b/docs/api.rst
index 0e6d35a..5306a20 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -10,8 +10,11 @@ Types
 Descriptors
 -----------
 
-* `stem.descriptor.reader <descriptor/reader.html>`_ - Reads and parses descriptor files from disk.
-* `stem.descriptor.export <descriptor/export.html>`_ - Exports descriptors to other formats.
+* **Classes**
+ * `stem.descriptor <descriptor/descriptor.html>`_ - Base class for descriptors.
+ * `stem.descriptor.server_descriptor <descriptor/server_descriptor.html>`_ - Relay and bridge server descriptors.
 
-* `stem.descriptor <descriptor/descriptor.html>`_ - Base class for descriptors.
+* **Utilities**
+ * `stem.descriptor.reader <descriptor/reader.html>`_ - Reads and parses descriptor files from disk.
+ * `stem.descriptor.export <descriptor/export.html>`_ - Exports descriptors to other formats.
 
diff --git a/docs/contents.rst b/docs/contents.rst
index 3026ccc..9fcb296 100644
--- a/docs/contents.rst
+++ b/docs/contents.rst
@@ -12,6 +12,7 @@ Contents
    descriptor/reader
 
    descriptor/descriptor
+   descriptor/server_descriptor
 
    types/exit_policy
    types/version
diff --git a/docs/descriptor/server_descriptor.rst b/docs/descriptor/server_descriptor.rst
new file mode 100644
index 0000000..c46f391
--- /dev/null
+++ b/docs/descriptor/server_descriptor.rst
@@ -0,0 +1,5 @@
+Server Descriptor
+=================
+
+.. automodule:: stem.descriptor.server_descriptor
+
diff --git a/stem/descriptor/server_descriptor.py b/stem/descriptor/server_descriptor.py
index aa49499..4095a62 100644
--- a/stem/descriptor/server_descriptor.py
+++ b/stem/descriptor/server_descriptor.py
@@ -3,7 +3,7 @@ Parsing for Tor server descriptors, which contains the infrequently changing
 information about a Tor relay (contact information, exit policy, public keys,
 etc). This information is provided from a few sources...
 
-* control port via 'GETINFO desc/*' queries
+* control port via 'GETINFO desc/\*' queries
 * the 'cached-descriptors' file in tor's data directory
 * tor metrics, at https://metrics.torproject.org/data.html
 * directory authorities and mirrors via their DirPort
@@ -73,13 +73,13 @@ def parse_file(descriptor_file, validate = True):
   Iterates over the server descriptors in a file.
   
   :param file descriptor_file: file with descriptor content
-  :param bool validate: checks the validity of the descriptor's content if True, skips these checks otherwise
+  :param bool validate: checks the validity of the descriptor's content if **True**, skips these checks otherwise
   
   :returns: iterator for ServerDescriptor instances in the file
   
   :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
   """
   
   # Handler for relay descriptors
@@ -134,7 +134,7 @@ class ServerDescriptor(stem.descriptor.Descriptor):
   
   :var str address: **\*** IPv4 address of the relay
   :var int or_port: **\*** port used for relaying
-  :var int socks_port: **\*** port used as client (deprecated, always None)
+  :var int socks_port: **\*** port used as client (deprecated, always **None**)
   :var int dir_port: **\*** port used for descriptor mirroring
   
   :var str platform: line with operating system and tor version
@@ -156,7 +156,7 @@ class ServerDescriptor(stem.descriptor.Descriptor):
   :var bool extra_info_cache: **\*** flag if a mirror for extra-info documents
   :var str extra_info_digest: hex encoded digest of our extra-info document
   :var bool eventdns: flag for evdns backend (deprecated, always unset)
-  :var list address_alt: alternative for our address/or_port attributes, each entry is a tuple of the form ``(address (str), port (int), is_ipv6 (bool))``
+  :var list address_alt: alternative for our address/or_port attributes, each entry is a tuple of the form (address (**str**), port (**int**), is_ipv6 (**bool**))
   
   Deprecated, moved to extra-info descriptor...
   
@@ -168,7 +168,7 @@ class ServerDescriptor(stem.descriptor.Descriptor):
   :var int write_history_interval: seconds per interval
   :var list write_history_values: bytes written during each interval
   
-  **\*** 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, raw_contents, validate = True, annotations = None):
@@ -182,10 +182,10 @@ class ServerDescriptor(stem.descriptor.Descriptor):
     malformed data.
     
     :param str raw_contents: descriptor content provided by the relay
-    :param bool validate: checks the validity of the descriptor's content if True, skips these checks otherwise
+    :param bool validate: checks the validity of the descriptor's content if **True**, skips these checks otherwise
     :param list annotations: lines that appeared prior to the descriptor
     
-    :raises: ValueError if the contents is malformed and validate is True
+    :raises: **ValueError** if the contents is malformed and validate is True
     """
     
     super(ServerDescriptor, self).__init__(raw_contents)
@@ -254,7 +254,7 @@ class ServerDescriptor(stem.descriptor.Descriptor):
     Provides the hex encoded sha1 of our content. This value is part of the
     network status entry for this relay.
     
-    :returns: str with the digest value for this server descriptor
+    :returns: **str** with the digest value for this server descriptor
     """
     
     raise NotImplementedError("Unsupported Operation: this should be implemented by the ServerDescriptor subclass")
@@ -272,7 +272,7 @@ class ServerDescriptor(stem.descriptor.Descriptor):
       @downloaded-at 2012-03-18 21:18:29
       @source "173.254.216.66"
     
-    :returns: dict with the key/value pairs in our annotations
+    :returns: **dict** with the key/value pairs in our annotations
     """
     
     if self._annotation_dict is None:
@@ -291,10 +291,11 @@ class ServerDescriptor(stem.descriptor.Descriptor):
   def get_annotation_lines(self):
     """
     Provides the lines of content that appeared prior to the descriptor. This
-    is the same as the get_annotations() results, but with the unparsed lines
-    and ordering retained.
+    is the same as the
+    :func:`~stem.descriptor.server_descriptor.ServerDescriptor.get_annotations`
+    results, but with the unparsed lines and ordering retained.
     
-    :returns: list with the lines of annotation that came before this descriptor
+    :returns: **list** with the lines of annotation that came before this descriptor
     """
     
     return self._annotation_lines
@@ -305,9 +306,9 @@ class ServerDescriptor(stem.descriptor.Descriptor):
     them as attributes.
     
     :param dict entries: descriptor contents to be applied
-    :param bool validate: checks the validity of descriptor content if True
+    :param bool validate: checks the validity of descriptor content if **True**
     
-    :raises: ValueError if an error occures in validation
+    :raises: **ValueError** if an error occures in validation
     """
     
     for keyword, values in entries.items():
@@ -530,7 +531,7 @@ class ServerDescriptor(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():
@@ -569,13 +570,13 @@ class ServerDescriptor(stem.descriptor.Descriptor):
 
 class RelayDescriptor(ServerDescriptor):
   """
-  Server descriptor (`specification <https://gitweb.torproject.org/torspec.git/blob/HEAD:/dir-spec.txt>`_)
+  Server descriptor (`descriptor specification <https://gitweb.torproject.org/torspec.git/blob/HEAD:/dir-spec.txt>`_)
   
   :var str onion_key: **\*** key used to encrypt EXTEND cells
   :var str signing_key: **\*** relay's long-term identity key
   :var str signature: **\*** signature for this descriptor
   
-  **\*** attribute is either required when we're parsed with validation or has a default value, others are left as None if undefined
+  **\*** attribute is required when we're parsed with validation
   """
   
   def __init__(self, raw_contents, validate = True, annotations = None):
@@ -602,7 +603,9 @@ class RelayDescriptor(ServerDescriptor):
     """
     Validates that our content matches our signature.
     
-    :returns: True if our signature matches our content, False otherwise
+    **Method implementation is incomplete, and will raise a NotImplementedError**
+    
+    :returns: **True** if our signature matches our content, **False** otherwise
     """
     
     raise NotImplementedError # TODO: finish implementing
@@ -668,8 +671,8 @@ class RelayDescriptor(ServerDescriptor):
 
 class BridgeDescriptor(ServerDescriptor):
   """
-  Bridge descriptor (`specification <https://metrics.torproject.org/formats.html#bridgedesc>`_)
-  
+  Bridge descriptor (`bridge descriptor specification
+  <https://metrics.torproject.org/formats.html#bridgedesc>`_)
   """
   
   def __init__(self, raw_contents, validate = True, annotations = None):
@@ -700,11 +703,13 @@ class BridgeDescriptor(ServerDescriptor):
   
   def is_scrubbed(self):
     """
-    Checks if we've been properly scrubbed in accordance with the bridge
-    descriptor specification. Validation is a moving target so this may not
+    Checks if we've been properly scrubbed in accordance with the `bridge
+    descriptor specification
+    <https://metrics.torproject.org/formats.html#bridgedesc>`_. Validation is a
+    moving target so this may not
     be fully up to date.
     
-    :returns: True if we're scrubbed, False otherwise
+    :returns: **True** if we're scrubbed, **False** otherwise
     """
     
     return self.get_scrubbing_issues() == []
@@ -713,7 +718,7 @@ class BridgeDescriptor(ServerDescriptor):
     """
     Provides issues with our scrubbing.
     
-    :returns: list of strings which describe issues we have with our scrubbing, this list is empty if we're properly scrubbed
+    :returns: **list** of strings which describe issues we have with our scrubbing, this list is empty if we're properly scrubbed
     """
     
     if self._scrubbing_issues == None:





More information about the tor-commits mailing list