[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]
[tor-commits] [stem/master] Revised API docs for stem.descriptor.server_descriptor
commit 2c4e518adf545633e05fc97bba4718f9aebe3396
Author: Damian Johnson <atagar@xxxxxxxxxxxxxx>
Date: Fri Oct 26 09:05:00 2012 -0700
Revised API docs for stem.descriptor.server_descriptor
---
docs/api.rst | 9 +++--
docs/contents.rst | 1 +
docs/descriptor/server_descriptor.rst | 5 +++
stem/descriptor/server_descriptor.py | 57 ++++++++++++++++++---------------
4 files changed, 43 insertions(+), 29 deletions(-)
diff --git a/docs/api.rst b/docs/api.rst
index 0e6d35a..5306a20 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -10,8 +10,11 @@ Types
Descriptors
-----------
-* `stem.descriptor.reader <descriptor/reader.html>`_ - Reads and parses descriptor files from disk.
-* `stem.descriptor.export <descriptor/export.html>`_ - Exports descriptors to other formats.
+* **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 <descriptor/descriptor.html>`_ - Base class for descriptors.
+* **Utilities**
+ * `stem.descriptor.reader <descriptor/reader.html>`_ - Reads and parses descriptor files from disk.
+ * `stem.descriptor.export <descriptor/export.html>`_ - Exports descriptors to other formats.
diff --git a/docs/contents.rst b/docs/contents.rst
index 3026ccc..9fcb296 100644
--- a/docs/contents.rst
+++ b/docs/contents.rst
@@ -12,6 +12,7 @@ Contents
descriptor/reader
descriptor/descriptor
+ descriptor/server_descriptor
types/exit_policy
types/version
diff --git a/docs/descriptor/server_descriptor.rst b/docs/descriptor/server_descriptor.rst
new file mode 100644
index 0000000..c46f391
--- /dev/null
+++ b/docs/descriptor/server_descriptor.rst
@@ -0,0 +1,5 @@
+Server Descriptor
+=================
+
+.. automodule:: stem.descriptor.server_descriptor
+
diff --git a/stem/descriptor/server_descriptor.py b/stem/descriptor/server_descriptor.py
index aa49499..4095a62 100644
--- a/stem/descriptor/server_descriptor.py
+++ b/stem/descriptor/server_descriptor.py
@@ -3,7 +3,7 @@ Parsing for Tor server descriptors, which contains the infrequently changing
information about a Tor relay (contact information, exit policy, public keys,
etc). This information is provided from a few sources...
-* control port via 'GETINFO desc/*' queries
+* control port via 'GETINFO desc/\*' queries
* the 'cached-descriptors' file in tor's data directory
* tor metrics, at https://metrics.torproject.org/data.html
* directory authorities and mirrors via their DirPort
@@ -73,13 +73,13 @@ def parse_file(descriptor_file, validate = True):
Iterates over the server 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 ServerDescriptor 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
"""
# Handler for relay descriptors
@@ -134,7 +134,7 @@ class ServerDescriptor(stem.descriptor.Descriptor):
:var str address: **\*** IPv4 address of the relay
:var int or_port: **\*** port used for relaying
- :var int socks_port: **\*** port used as client (deprecated, always None)
+ :var int socks_port: **\*** port used as client (deprecated, always **None**)
:var int dir_port: **\*** port used for descriptor mirroring
:var str platform: line with operating system and tor version
@@ -156,7 +156,7 @@ class ServerDescriptor(stem.descriptor.Descriptor):
:var bool extra_info_cache: **\*** flag if a mirror for extra-info documents
:var str extra_info_digest: hex encoded digest of our extra-info document
:var bool eventdns: flag for evdns backend (deprecated, always unset)
- :var list address_alt: alternative for our address/or_port attributes, each entry is a tuple of the form ``(address (str), port (int), is_ipv6 (bool))``
+ :var list address_alt: alternative for our address/or_port attributes, each entry is a tuple of the form (address (**str**), port (**int**), is_ipv6 (**bool**))
Deprecated, moved to extra-info descriptor...
@@ -168,7 +168,7 @@ class ServerDescriptor(stem.descriptor.Descriptor):
:var int write_history_interval: seconds per interval
:var list write_history_values: bytes written during each interval
- **\*** 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, annotations = None):
@@ -182,10 +182,10 @@ class ServerDescriptor(stem.descriptor.Descriptor):
malformed data.
:param str raw_contents: descriptor content provided by the relay
- :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
:param list annotations: lines that appeared prior to the descriptor
- :raises: ValueError if the contents is malformed and validate is True
+ :raises: **ValueError** if the contents is malformed and validate is True
"""
super(ServerDescriptor, self).__init__(raw_contents)
@@ -254,7 +254,7 @@ class ServerDescriptor(stem.descriptor.Descriptor):
Provides the hex encoded sha1 of our content. This value is part of the
network status 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 ServerDescriptor subclass")
@@ -272,7 +272,7 @@ class ServerDescriptor(stem.descriptor.Descriptor):
@downloaded-at 2012-03-18 21:18:29
@source "173.254.216.66"
- :returns: dict with the key/value pairs in our annotations
+ :returns: **dict** with the key/value pairs in our annotations
"""
if self._annotation_dict is None:
@@ -291,10 +291,11 @@ class ServerDescriptor(stem.descriptor.Descriptor):
def get_annotation_lines(self):
"""
Provides the lines of content that appeared prior to the descriptor. This
- is the same as the get_annotations() results, but with the unparsed lines
- and ordering retained.
+ is the same as the
+ :func:`~stem.descriptor.server_descriptor.ServerDescriptor.get_annotations`
+ results, but with the unparsed lines and ordering retained.
- :returns: list with the lines of annotation that came before this descriptor
+ :returns: **list** with the lines of annotation that came before this descriptor
"""
return self._annotation_lines
@@ -305,9 +306,9 @@ class ServerDescriptor(stem.descriptor.Descriptor):
them as attributes.
:param dict entries: descriptor contents to be applied
- :param bool validate: checks the validity of descriptor content if True
+ :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():
@@ -530,7 +531,7 @@ class ServerDescriptor(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():
@@ -569,13 +570,13 @@ class ServerDescriptor(stem.descriptor.Descriptor):
class RelayDescriptor(ServerDescriptor):
"""
- Server descriptor (`specification <https://gitweb.torproject.org/torspec.git/blob/HEAD:/dir-spec.txt>`_)
+ Server descriptor (`descriptor specification <https://gitweb.torproject.org/torspec.git/blob/HEAD:/dir-spec.txt>`_)
:var str onion_key: **\*** key used to encrypt EXTEND cells
:var str signing_key: **\*** relay's long-term identity key
:var str signature: **\*** signature for this 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, annotations = None):
@@ -602,7 +603,9 @@ class RelayDescriptor(ServerDescriptor):
"""
Validates that our content matches our signature.
- :returns: True if our signature matches our content, False otherwise
+ **Method implementation is incomplete, and will raise a NotImplementedError**
+
+ :returns: **True** if our signature matches our content, **False** otherwise
"""
raise NotImplementedError # TODO: finish implementing
@@ -668,8 +671,8 @@ class RelayDescriptor(ServerDescriptor):
class BridgeDescriptor(ServerDescriptor):
"""
- Bridge descriptor (`specification <https://metrics.torproject.org/formats.html#bridgedesc>`_)
-
+ Bridge descriptor (`bridge descriptor specification
+ <https://metrics.torproject.org/formats.html#bridgedesc>`_)
"""
def __init__(self, raw_contents, validate = True, annotations = None):
@@ -700,11 +703,13 @@ class BridgeDescriptor(ServerDescriptor):
def is_scrubbed(self):
"""
- Checks if we've been properly scrubbed in accordance with the bridge
- descriptor specification. Validation is a moving target so this may not
+ Checks if we've been properly scrubbed in accordance with the `bridge
+ descriptor specification
+ <https://metrics.torproject.org/formats.html#bridgedesc>`_. Validation is a
+ moving target so this may not
be fully up to date.
- :returns: True if we're scrubbed, False otherwise
+ :returns: **True** if we're scrubbed, **False** otherwise
"""
return self.get_scrubbing_issues() == []
@@ -713,7 +718,7 @@ class BridgeDescriptor(ServerDescriptor):
"""
Provides issues with our scrubbing.
- :returns: list of strings which describe issues we have with our scrubbing, this list is empty if we're properly scrubbed
+ :returns: **list** of strings which describe issues we have with our scrubbing, this list is empty if we're properly scrubbed
"""
if self._scrubbing_issues == None:
_______________________________________________
tor-commits mailing list
tor-commits@xxxxxxxxxxxxxxxxxxxx
https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-commits