commit 2c4e518adf545633e05fc97bba4718f9aebe3396 Author: Damian Johnson atagar@torproject.org 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: