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

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



commit 934a475cb1e07126847acdbe1166abf1d48128c1
Author: Damian Johnson <atagar@xxxxxxxxxxxxxx>
Date:   Sat Oct 27 08:19:06 2012 -0700

    Revised API docs for stem.descriptor.extrainfo_descriptor
---
 docs/api.rst                             |    1 +
 docs/contents.rst                        |    1 +
 docs/descriptor/extrainfo_descriptor.rst |    5 +++
 stem/descriptor/extrainfo_descriptor.py  |   54 +++++++++++++++---------------
 4 files changed, 34 insertions(+), 27 deletions(-)

diff --git a/docs/api.rst b/docs/api.rst
index 5306a20..711f9d4 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -13,6 +13,7 @@ Descriptors
 * **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.extrainfo_descriptor <descriptor/extrainfo_descriptor.html>`_ - Relay and bridge extrainfo descriptors.
 
 * **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 9fcb296..90d61d1 100644
--- a/docs/contents.rst
+++ b/docs/contents.rst
@@ -13,6 +13,7 @@ Contents
 
    descriptor/descriptor
    descriptor/server_descriptor
+   descriptor/extrainfo_descriptor
 
    types/exit_policy
    types/version
diff --git a/docs/descriptor/extrainfo_descriptor.rst b/docs/descriptor/extrainfo_descriptor.rst
new file mode 100644
index 0000000..1356dae
--- /dev/null
+++ b/docs/descriptor/extrainfo_descriptor.rst
@@ -0,0 +1,5 @@
+Extrainfo Descriptor
+====================
+
+.. automodule:: stem.descriptor.extrainfo_descriptor
+
diff --git a/stem/descriptor/extrainfo_descriptor.py b/stem/descriptor/extrainfo_descriptor.py
index d66ea87..4f5d562 100644
--- a/stem/descriptor/extrainfo_descriptor.py
+++ b/stem/descriptor/extrainfo_descriptor.py
@@ -4,16 +4,17 @@ their server descriptor is published and have a similar format. However, unlike
 server descriptors these don't contain information that Tor clients require to
 function and as such aren't fetched by default.
 
-Defined in section 2.2 of the dir-spec, extra-info descriptors contain
-interesting but non-vital information such as usage statistics. These documents
-cannot be requested of bridges.
+Defined in section 2.2 of the `dir-spec
+<https://gitweb.torproject.org/torspec.git/blob/HEAD:/dir-spec.txt>`_,
+extra-info descriptors contain interesting but non-vital information such as
+usage statistics. Tor clients cannot request these documents for bridges.
 
 Extra-info descriptors are available from a few sources...
 
 * if you have 'DownloadExtraInfo 1' in your torrc...
 
-  * control port via 'GETINFO extra-info/digest/*' queries
-  * the 'cached-extrainfo' file in tor's data directory
+ * control port via 'GETINFO extra-info/digest/\*' queries
+ * the 'cached-extrainfo' file in tor's data directory
 
 * tor metrics, at https://metrics.torproject.org/data.html
 * directory authorities and mirrors via their DirPort
@@ -121,13 +122,13 @@ def parse_file(descriptor_file, validate = True):
   Iterates over the extra-info 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 ExtraInfoDescriptor instances in the file
+  :returns: iterator for :class:`~stem.descriptor.extrainfo_descriptor.ExtraInfoDescriptor` 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
   """
   
   while True:
@@ -148,9 +149,9 @@ def _parse_timestamp_and_interval(keyword, content):
   :param str keyword: line's keyword
   :param str content: line content to be parsed
   
-  :returns: tuple of the form ``(timestamp (datetime), interval (int), remaining content (str))``
+  :returns: **tuple** of the form (timestamp (**datetime**), interval (**int**), remaining content (**str**))
   
-  :raises: ValueError if the content is malformed
+  :raises: **ValueError** if the content is malformed
   """
   
   line = "%s %s" % (keyword, content)
@@ -179,7 +180,7 @@ class ExtraInfoDescriptor(stem.descriptor.Descriptor):
   :var str fingerprint: **\*** identity key fingerprint
   :var datetime published: **\*** time in GMT when this descriptor was made
   :var str geoip_db_digest: sha1 of geoIP database file
-  :var dict transport: **\*** mapping of transport methods to their (address, port, args) tuple, these usually appeear on bridges in which case all of those are None
+  :var dict transport: **\*** mapping of transport methods to their (address, port, args) tuple, these usually appeear on bridges in which case all of those are **None**
   
   **Bi-directional connection usage:**
   
@@ -220,18 +221,18 @@ class ExtraInfoDescriptor(stem.descriptor.Descriptor):
   :var dict dir_v2_requests: mapping of locales to rounded count of requests
   :var dict dir_v3_requests: mapping of locales to rounded count of requests
   
-  :var dict dir_v2_responses: mapping of DirResponses to their rounded count
-  :var dict dir_v3_responses: mapping of DirResponses to their rounded count
+  :var dict dir_v2_responses: mapping of **DirResponses** to their rounded count
+  :var dict dir_v3_responses: mapping of **DirResponses** to their rounded count
   :var dict dir_v2_responses_unknown: mapping of unrecognized statuses to their count
   :var dict dir_v3_responses_unknown: mapping of unrecognized statuses to their count
   
-  :var dict dir_v2_direct_dl: mapping of DirStats to measurement over DirPort
-  :var dict dir_v3_direct_dl: mapping of DirStats to measurement over DirPort
+  :var dict dir_v2_direct_dl: mapping of **DirStats** to measurement over DirPort
+  :var dict dir_v3_direct_dl: mapping of **DirStats** to measurement over DirPort
   :var dict dir_v2_direct_dl_unknown: mapping of unrecognized stats to their measurement
   :var dict dir_v3_direct_dl_unknown: mapping of unrecognized stats to their measurement
   
-  :var dict dir_v2_tunneled_dl: mapping of DirStats to measurement over ORPort
-  :var dict dir_v3_tunneled_dl: mapping of DirStats to measurement over ORPort
+  :var dict dir_v2_tunneled_dl: mapping of **DirStats** to measurement over ORPort
+  :var dict dir_v3_tunneled_dl: mapping of **DirStats** to measurement over ORPort
   :var dict dir_v2_tunneled_dl_unknown: mapping of unrecognized stats to their measurement
   :var dict dir_v3_tunneled_dl_unknown: mapping of unrecognized stats to their measurement
   
@@ -267,7 +268,7 @@ class ExtraInfoDescriptor(stem.descriptor.Descriptor):
   :var datetime geoip_start_time: replaced by bridge_stats_end (deprecated)
   :var dict geoip_client_origins: replaced by bridge_ips (deprecated)
   
-  **\*** 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):
@@ -277,9 +278,9 @@ class ExtraInfoDescriptor(stem.descriptor.Descriptor):
     either improve performance or be accepting of malformed data.
     
     :param str raw_contents: extra-info content provided by the relay
-    :param bool validate: checks the validity of the extra-info descriptor if True, skips these checks otherwise
+    :param bool validate: checks the validity of the extra-info descriptor if **True**, skips these checks otherwise
     
-    :raises: ValueError if the contents is malformed and validate is True
+    :raises: **ValueError** if the contents is malformed and validate is True
     """
     
     super(ExtraInfoDescriptor, self).__init__(raw_contents)
@@ -391,7 +392,7 @@ class ExtraInfoDescriptor(stem.descriptor.Descriptor):
     :param dict entries: descriptor contents to be applied
     :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():
@@ -728,7 +729,7 @@ class ExtraInfoDescriptor(stem.descriptor.Descriptor):
     Provides the hex encoded sha1 of our content. This value is part of the
     server descriptor 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 ExtraInfoDescriptor subclass")
@@ -745,12 +746,12 @@ class ExtraInfoDescriptor(stem.descriptor.Descriptor):
 class RelayExtraInfoDescriptor(ExtraInfoDescriptor):
   """
   Relay extra-info descriptor, constructed from data such as that provided by
-  "GETINFO extra-info/digest/*", cached descriptors, and metrics
+  "GETINFO extra-info/digest/\*", cached descriptors, and metrics
   (`specification <https://gitweb.torproject.org/torspec.git/blob/HEAD:/dir-spec.txt>`_).
   
   :var str signature: **\*** signature for this extrainfo 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):
@@ -789,8 +790,7 @@ class RelayExtraInfoDescriptor(ExtraInfoDescriptor):
 
 class BridgeExtraInfoDescriptor(ExtraInfoDescriptor):
   """
-  Bridge extra-info descriptor (`specification <https://metrics.torproject.org/formats.html#bridgedesc>`_)
-  
+  Bridge extra-info descriptor (`bridge descriptor specification <https://metrics.torproject.org/formats.html#bridgedesc>`_)
   """
   
   def __init__(self, raw_contents, validate = True):



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