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