[tor-commits] [stem/master] Revised API docs for stem.descriptor.extrainfo_descriptor
atagar at torproject.org
atagar at torproject.org
Sun Oct 28 20:56:34 UTC 2012
commit 934a475cb1e07126847acdbe1166abf1d48128c1
Author: Damian Johnson <atagar at torproject.org>
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):
More information about the tor-commits
mailing list