commit 29f500874cb90aa6d9c3626a609dfc957950590f Author: Damian Johnson atagar@torproject.org Date: Sat Oct 27 09:42:03 2012 -0700

Revised API docs for stem.descriptor.networkstatus --- docs/api.rst | 1 + docs/contents.rst | 1 + docs/descriptor/networkstatus.rst | 5 +++ stem/descriptor/networkstatus.py | 68 +++++++++++++++++++----------------- 4 files changed, 43 insertions(+), 32 deletions(-)

diff --git a/docs/api.rst b/docs/api.rst index 711f9d4..b329c5a 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -14,6 +14,7 @@ Descriptors * `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. + * `stem.descriptor.networkstatus <descriptor/networkstatus.html>`_ - Network status documents which make up the Tor consensus.

* **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 90d61d1..6cbf63a 100644 --- a/docs/contents.rst +++ b/docs/contents.rst @@ -14,6 +14,7 @@ Contents descriptor/descriptor descriptor/server_descriptor descriptor/extrainfo_descriptor + descriptor/networkstatus

types/exit_policy types/version diff --git a/docs/descriptor/networkstatus.rst b/docs/descriptor/networkstatus.rst new file mode 100644 index 0000000..44b8bb3 --- /dev/null +++ b/docs/descriptor/networkstatus.rst @@ -0,0 +1,5 @@ +Network Status Documents +======================== + +.. automodule:: stem.descriptor.networkstatus + diff --git a/stem/descriptor/networkstatus.py b/stem/descriptor/networkstatus.py index e8a2679..61319e3 100644 --- a/stem/descriptor/networkstatus.py +++ b/stem/descriptor/networkstatus.py @@ -38,9 +38,10 @@ constructor. Router entries are assigned to its 'routers' attribute...

* :func:`stem.descriptor.parse_file`

-Alternatively, the parse_file() function provides an iterator for a document's -routers. Those routers refer to a 'thin' document, which doesn't have a -'routers' attribute. This allows for lower memory usage and upfront runtime. +Alternatively, the :func:`~stem.descriptor.networkstatus.parse_file` function +provides an iterator for a document's routers. Those routers refer to a 'thin' +document, which doesn't have a 'routers' attribute. This allows for lower +memory usage and upfront runtime.

::

@@ -171,15 +172,15 @@ def parse_file(document_file, validate = True, is_microdescriptor = False, docum allow for limited memory usage.

: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 is_microdescriptor: True if this is for a microdescriptor consensus, False otherwise + :param bool validate: checks the validity of the document's contents if **True**, skips these checks otherwise + :param bool is_microdescriptor: **True** if this is for a microdescriptor consensus, **False** otherwise :param int document_version: network status document version

:returns: :class:`stem.descriptor.networkstatus.NetworkStatusDocument` object

:raises: - * ValueError if the document_version is unrecognized or the contents is malformed and validate is True - * IOError if the file can't be read + * **ValueError** if the document_version is unrecognized or the contents is malformed and validate is **True** + * **IOError** if the file can't be read """

# getting the document without the routers section @@ -236,7 +237,7 @@ class NetworkStatusDocumentV2(NetworkStatusDocument): Version 2 network status document. These have been deprecated and are no longer generated by Tor.

- :var tuple routers: RouterStatusEntryV2 contained in the document + :var tuple routers: :class:`~stem.descriptor.router_status_entry.RouterStatusEntryV2` contained in the document

:var int version: ***** document version

@@ -395,13 +396,13 @@ class NetworkStatusDocumentV3(NetworkStatusDocument): """ Version 3 network status document. This could be either a vote or consensus.

- :var tuple routers: RouterStatusEntryV3 contained in the document + :var tuple routers: :class:`~stem.descriptor.router_status_entry.RouterStatusEntryV3` contained in the document

:var int version: ***** document version :var str version_flavor: ***** flavor associated with the document (such as 'microdesc') - :var bool is_consensus: ***** true if the document is a consensus - :var bool is_vote: ***** true if the document is a vote - :var bool is_microdescriptor: ***** true if this is a microdescriptor flavored document, false otherwise + :var bool is_consensus: ***** **True** if the document is a consensus + :var bool is_vote: ***** **True** if the document is a vote + :var bool is_microdescriptor: ***** **True** if this is a microdescriptor flavored document, **False** otherwise :var datetime valid_after: ***** time when the consensus became valid :var datetime fresh_until: ***** time when the next consensus should be produced :var datetime valid_until: ***** time when this consensus becomes obsolete @@ -410,15 +411,17 @@ class NetworkStatusDocumentV3(NetworkStatusDocument): :var list client_versions: list of recommended client tor versions :var list server_versions: list of recommended server tor versions :var list known_flags: ***** list of known router flags - :var list params: ***** dict of parameter(str) => value(int) mappings - :var list directory_authorities: ***** list of DirectoryAuthority objects that have generated this document - :var list signatures: ***** DocumentSignature of the authorities that have signed the document + :var list params: ***** dict of parameter(**str**) => value(**int**) mappings + :var list directory_authorities: ***** list of :class:`~stem.descriptor.networkstatus.DirectoryAuthority` objects that have generated this document + :var list signatures: ***** :class:`~stem.descriptor.networkstatus.DocumentSignature` of the authorities that have signed the document

**Consensus Attributes:** + :var int consensus_method: method version used to generate this consensus :var dict bandwidth_weights: dict of weight(str) => value(int) mappings

**Vote Attributes:** + :var list consensus_methods: list of ints for the supported method versions :var datetime published: time when the document was published

@@ -427,14 +430,13 @@ class NetworkStatusDocumentV3(NetworkStatusDocument):

def __init__(self, raw_content, validate = True, default_params = True): """ - Parse a v3 network status document and provide a new - NetworkStatusDocumentV3 object. + Parse a v3 network status document.

:param str raw_content: raw network status document data - :param bool validate: True if the document is to be validated, False otherwise + :param bool validate: **True** if the document is to be validated, **False** otherwise :param bool default_params: includes defaults in our params dict, otherwise it just contains values from the document

- :raises: ValueError if the document is invalid + :raises: **ValueError** if the document is invalid """

super(NetworkStatusDocumentV3, self).__init__(raw_content) @@ -489,7 +491,7 @@ class NetworkStatusDocumentV3(NetworkStatusDocument):

:param int method: consensus-method to check for

- :returns: True if we meet the given consensus-method, and False otherwise + :returns: **True** if we meet the given consensus-method, and **False** otherwise """

return self._header.meets_consensus_method(method) @@ -780,9 +782,9 @@ def _check_for_missing_and_disallowed_fields(header, entries, fields):

:param _DocumentHeader header: document header :param dict entries: ordered keyword/value mappings of the header or footer - :param list fields: expected field attributes (either HEADER_STATUS_DOCUMENT_FIELDS or FOOTER_STATUS_DOCUMENT_FIELDS) + :param list fields: expected field attributes (either **HEADER_STATUS_DOCUMENT_FIELDS** or **FOOTER_STATUS_DOCUMENT_FIELDS**)

- :raises: ValueError if we're missing mandatory fields or have fiels we shouldn't + :raises: **ValueError** if we're missing mandatory fields or have fiels we shouldn't """

missing_fields, disallowed_fields = [], [] @@ -810,9 +812,9 @@ def _check_for_misordered_fields(entries, expected): are ignored).

:param dict entries: ordered keyword/value mappings of the header or footer - :param list expected: ordered list of expected fields (either HEADER_FIELDS or FOOTER_FIELDS) + :param list expected: ordered list of expected fields (either **HEADER_FIELDS** or **FOOTER_FIELDS**)

- :raises: ValueError if entries aren't properly ordered + :raises: **ValueError** if entries aren't properly ordered """

# Earlier validation has ensured that our fields either belong to our @@ -880,11 +882,13 @@ class DirectoryAuthority(stem.descriptor.Descriptor): :var str contact: ***** contact information

**Consensus Attributes:** + :var str vote_digest: ***** digest of the authority that contributed to the consensus

**Vote Attributes:** + :var str legacy_dir_key: fingerprint of and obsolete identity key - :var :class:`stem.descriptor.networkstatus.KeyCertificate` key_certificate: ***** authority's key certificate + :var stem.descriptor.networkstatus.KeyCertificate key_certificate: ***** authority's key certificate

***** mandatory attribute """ @@ -925,9 +929,9 @@ class DirectoryAuthority(stem.descriptor.Descriptor):

:param str content: descriptor content :param bool validate: checks validity if True - :param bool is_vote: True if this is for a vote, False if it's for a consensus + :param bool is_vote: **True** if this is for a vote, **False** if it's for a consensus

- :raises: ValueError if a validity check fails + :raises: **ValueError** if a validity check fails """

# separate the directory authority entry from its key certificate @@ -1091,9 +1095,9 @@ class KeyCertificate(stem.descriptor.Descriptor): Parses the given content and applies the attributes.

:param str content: descriptor content - :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 """

entries = stem.descriptor._get_descriptor_components(content, validate) @@ -1194,7 +1198,7 @@ class KeyCertificate(stem.descriptor.Descriptor): """ Returns any unrecognized lines.

- :returns: a list of unrecognized lines + :returns: **list** of unrecognized lines """

return self._unrecognized_lines @@ -1213,9 +1217,9 @@ class DocumentSignature(object): :var str identity: fingerprint of the authority that made the signature :var str key_digest: digest of the signing key :var str signature: document signature - :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 """

def __init__(self, method, identity, key_digest, signature, validate = True):