commit 8ee4c14fe0784c82637f7d3bb0b6d496c44717c9 Author: Damian Johnson atagar@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