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: