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