October 2012 - tor-commits - lists.torproject.org

[stem/master] Only including prepared API docs
by atagar＠torproject.org 28 Oct '12

28 Oct '12

commit 0cc97d2dcc15ce227983cfc72c234bf995b4857a Author: Damian Johnson <atagar(a)torproject.org> Date: Sun Oct 21 20:04:30 2012 -0700 Only including prepared API docs Our sphinx-apidoc made it so all our pydocs were included in our built documentation. This is great, except that those documentation dumps are completely unreadable. Dropping the sphinx-apidoc call in favor of including specific autodoc pages we've prepared. Made some revisions to stem.version's documentation and including that to start. --- docs/Makefile | 2 -- docs/api.rst | 44 +++----------------------------------------- docs/conf.py | 9 --------- docs/index.rst | 4 ---- docs/types/version.rst | 5 +++++ stem/version.py | 37 +++++++++++++++++-------------------- 6 files changed, 25 insertions(+), 76 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index 22f3516..e0febbd 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -38,8 +38,6 @@ clean: @rm -f ./stem.* ./modules.rst html: - @sphinx-apidoc -f -o /tmp/stem_docs ../stem - @rsync --size-only /tmp/stem_docs/* . $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." diff --git a/docs/api.rst b/docs/api.rst index 0e71afa..3015210 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -1,46 +1,8 @@ API === -:mod:`stem.connection` ----------------------- +Types +----- -Connecting and authenticating to a Tor process. - -:mod:`stem.control` -------------------- - -Provides the :class:`~stem.control.Controller` class which, as the name implies, is used for talking with and controlling a Tor instance. As a user this is the primary class that you'll need. - -:mod:`stem.socket` ------------------- - -Base classes for communicating with a Tor control socket. - -:mod:`stem.process` -------------------- - -Used for launching Tor and managing the process. - -:mod:`stem.version` -------------------- - -Parsed versions that can be compared to the requirement for various features. - -`stem.descriptor <stem.descriptor.html>`_ ------------------------------------------ - -Utilities for working with the Tor consensus and descriptors. - -`stem.response <stem.response.html>`_ -------------------------------------- - -Parsed replies that we receive from the Tor control socket. - -`stem.util <stem.util.html>`_ ------------------------------ - -Utility functions available to stem and its users. - -.. toctree:: - :maxdepth: 2 +* `stem.version <types/version.html>`_ - Tor versions that can be compared to determine Tor's capablilites. diff --git a/docs/conf.py b/docs/conf.py index 0bdd83c..ada61ec 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -13,15 +13,6 @@ import sys, os -# Our make file calls sphinx-apidoc, but read-the-docs uses our config instead -# (so it skips that step). Calling apidoc here instead if we're being built -# there. - -on_rtd = os.environ.get('READTHEDOCS', None) == 'True' - -if on_rtd: - os.system("sphinx-apidoc -f -o . ../stem") - # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. diff --git a/docs/index.rst b/docs/index.rst index 95c1589..aa5ab03 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -21,7 +21,3 @@ Indices and tables *Last updated:* |today| - - - - diff --git a/docs/types/version.rst b/docs/types/version.rst new file mode 100644 index 0000000..ad9e875 --- /dev/null +++ b/docs/types/version.rst @@ -0,0 +1,5 @@ +Version +======= + +.. automodule:: stem.version + diff --git a/stem/version.py b/stem/version.py index 342c400..bb75c18 100644 --- a/stem/version.py +++ b/stem/version.py @@ -4,10 +4,11 @@ easily parsed and compared, for instance... :: - >>> my_version = stem.version.get_system_tor_version() + >>> from stem.version import get_system_tor_version, Requirement + >>> my_version = get_system_tor_version() >>> print my_version 0.2.1.30 - >>> my_version.meets_requirements(stem.version.Requirement.CONTROL_SOCKET) + >>> my_version.meets_requirements(Requirement.CONTROL_SOCKET) True **Module Overview:** @@ -48,9 +49,9 @@ def get_system_tor_version(tor_cmd = "tor"): :param str tor_cmd: command used to run tor - :returns: :class:`stem.version.Version` provided by the tor command + :returns: :class:`~stem.version.Version` provided by the tor command - :raises: IOError if unable to query or parse the version + :raises: **IOError** if unable to query or parse the version """ if not tor_cmd in VERSION_CACHE: @@ -90,14 +91,14 @@ class Version(object): :var int major: major version :var int minor: minor version :var int micro: micro version - :var int patch: optional patch level (None if undefined) - :var str status: optional status tag without the preceding dash such as 'alpha', 'beta-dev', etc (None if undefined) - :var str extra: optional extra information without the proceeding space nor its parentheses such as 'git-8be6058d8f31e578' (None if undefined) - :var str git_commit: optional git commit id (None if it wasn't provided) + :var int patch: patch level (**None** if undefined) + :var str status: status tag such as 'alpha' or 'beta-dev' (**None** if undefined) + :var str extra: extra information without its parentheses such as 'git-8be6058d8f31e578' (**None** if undefined) + :var str git_commit: git commit id (**None** if it wasn't provided) :param str version_str: version to be parsed - :raises: ValueError if input isn't a valid tor version + :raises: **ValueError** if input isn't a valid tor version """ def __init__(self, version_str): @@ -129,10 +130,9 @@ class Version(object): def meets_requirements(self, requirements): """ - Checks if this version meets the requirements for a given feature. - - Requirements can be either a :class:`stem.version.Version` or - :class:`stem.version.VersionRequirements`. + Checks if this version meets the requirements for a given feature. We can + be compared to either a :class:`~stem.version.Version` or + :class:`~stem.version.VersionRequirements`. :param requirements: requrirements to be checked for """ @@ -147,15 +147,14 @@ class Version(object): def __str__(self): """ - Provides the string used to construct the Version. + Provides the string used to construct the version. """ return self.version_str def __cmp__(self, other): """ - Simple comparison of versions. An undefined patch level is treated as zero - and status tags are not included in comparisions (as per the version spec). + Compares version ordering according to the spec. """ if not isinstance(other, Version): @@ -182,17 +181,15 @@ class Version(object): class VersionRequirements(object): """ - Series of version constraints that can be compared to. For instance, it + Series of version constraints that can be compared to. For instance, this allows for comparisons like 'if I'm greater than version X in the 0.2.2 series, or greater than version Y in the 0.2.3 series'. This is a logical 'or' of the series of rules. """ - def __init__(self, rule = None): + def __init__(self): self.rules = [] - - if rule: self.greater_than(rule) def greater_than(self, version, inclusive = True): """

1 0

[stem/master] Adding toctree declarations
by atagar＠torproject.org 28 Oct '12

28 Oct '12

commit 3c04eb6092371526126ef745903bb3e96782511a Author: Damian Johnson <atagar(a)torproject.org> Date: Thu Oct 25 09:17:35 2012 -0700 Adding toctree declarations Sphinx gives a warning saying "document isn't included in any toctree" if all *.rst documents aren't included in a toctree somewhere. I'm not using a toctree as our primary form of navigation so it doesn't really make sense, but it's easy enough to make a contents page off to the side that satisfies sphinx. --- docs/contents.rst | 14 ++++++++++++++ docs/index.rst | 5 +++++ 2 files changed, 19 insertions(+), 0 deletions(-) diff --git a/docs/contents.rst b/docs/contents.rst new file mode 100644 index 0000000..7565543 --- /dev/null +++ b/docs/contents.rst @@ -0,0 +1,14 @@ +Contents +======== + +.. toctree:: + :maxdepth: 2 + + api + download + tutorial + + descriptor/reader + types/exit_policy + types/version + diff --git a/docs/index.rst b/docs/index.rst index aa5ab03..edfab3f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -19,5 +19,10 @@ Indices and tables * :ref:`modindex` * :ref:`search` +.. toctree:: + :maxdepth: 1 + + contents + *Last updated:* |today|

1 0

[stem/master] Revised API docs for stem.exit_policy
by atagar＠torproject.org 28 Oct '12

28 Oct '12

commit d00d2ac5a4679a428358f06242cb0980660bb100 Author: Damian Johnson <atagar(a)torproject.org> Date: Sun Oct 21 21:26:26 2012 -0700 Revised API docs for stem.exit_policy --- docs/api.rst | 1 + docs/types/exit_policy.rst | 5 +++ stem/exit_policy.py | 77 +++++++++++++++++++++++-------------------- stem/version.py | 4 +- 4 files changed, 49 insertions(+), 38 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index 3015210..b0531b0 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -4,5 +4,6 @@ API Types ----- +* `stem.exit_policy <types/exit_policy.html>`_ - Relay policy for the destinations it will or won't allow traffic to. * `stem.version <types/version.html>`_ - Tor versions that can be compared to determine Tor's capablilites. diff --git a/docs/types/exit_policy.rst b/docs/types/exit_policy.rst new file mode 100644 index 0000000..2963fa8 --- /dev/null +++ b/docs/types/exit_policy.rst @@ -0,0 +1,5 @@ +Exit Policy +=========== + +.. automodule:: stem.exit_policy + diff --git a/stem/exit_policy.py b/stem/exit_policy.py index 0337a6b..1c47bb5 100644 --- a/stem/exit_policy.py +++ b/stem/exit_policy.py @@ -4,7 +4,8 @@ exiting to a destination is permissable or not. For instance... :: - >>> policy = stem.exit_policy.ExitPolicy("accept *:80", "accept *:443", "reject *:*") + >>> from stem.exit_policy import ExitPolicy, MicrodescriptorExitPolicy + >>> policy = ExitPolicy("accept *:80", "accept *:443", "reject *:*") >>> print policy accept *:80, accept *:443, reject *:* >>> print policy.summary() @@ -12,16 +13,17 @@ exiting to a destination is permissable or not. For instance... >>> policy.can_exit_to("75.119.206.243", 80) True - >>> policy = stem.exit_policy.MicrodescriptorExitPolicy("accept 80,443") + >>> policy = MicrodescriptorExitPolicy("accept 80,443") >>> print policy accept 80,443 - >>> policy.check("75.119.206.243", 80) + >>> policy.can_exit_to("75.119.206.243", 80) True :: ExitPolicy - Exit policy for a Tor relay | + MicrodescriptorExitPolicy - Microdescriptor exit policy + |- set_default_allowed - sets the can_exit_to response when no rules match |- can_exit_to - check if exiting to this destination is allowed or not |- is_exiting_allowed - check if any exiting is allowed |- summary - provides a short label, similar to a microdescriptor @@ -33,6 +35,11 @@ exiting to a destination is permissable or not. For instance... |- is_port_wildcard - checks if we'll accept any port |- is_match - checks if we match a given destination +- __str__ - string representation for this rule + + AddressType - Enumerations for IP address types that can be in an exit policy + |- WILDCARD - any address of either IPv4 or IPv6 + |- IPv4 - IPv4 address + +- IPv6 - IPv6 address """ import stem.util.connection @@ -62,9 +69,10 @@ AddressType = stem.util.enum.Enum(("WILDCARD", "Wildcard"), ("IPv4", "IPv4"), (" class ExitPolicy(object): """ Policy for the destinations that a relay allows or denies exiting to. This - is, in effect, simply a list of ExitPolicyRule entries. + is, in effect, just a list of :class:`~stem.exit_policy.ExitPolicyRule` + entries. - :param list rules: str or ExitPolicyRule entries that make up this policy + :param list rules: **str** or :class:`~stem.exit_policy.ExitPolicyRule` entries that make up this policy """ def __init__(self, *rules): @@ -83,17 +91,12 @@ class ExitPolicy(object): def set_default_allowed(self, is_allowed_default): """ - Generally policies end with either an 'reject *:*' or 'accept *:*' policy, - but if it doesn't then is_allowed_default will determine the default - response for our :meth:`~stem.exit_policy.ExitPolicy.can_exit_to` method. - This defaults to True because, according to the dir-spec, this is Tor's - default... - - :: + Generally policies end with either an 'reject \*:\*' or 'accept \*:\*' + policy, but if it doesn't then is_allowed_default will determine the + default response for our :meth:`~stem.exit_policy.ExitPolicy.can_exit_to` + method. - The rules are considered in order; if no rule matches, the address will - be accepted. For clarity, the last such entry SHOULD be accept *:* or - reject *:*. + Our default, and tor's, is **True**. :param bool is_allowed_default: :meth:`~stem.exit_policy.ExitPolicy.can_exit_to` default when no rules apply """ @@ -109,7 +112,7 @@ class ExitPolicy(object): :param str address: IPv4 or IPv6 address (with or without brackets) :param int port: port number - :returns: True if exiting to this destination is allowed, False otherwise + :returns: **True** if exiting to this destination is allowed, **False** otherwise """ for rule in self._rules: @@ -120,7 +123,8 @@ class ExitPolicy(object): def is_exiting_allowed(self): """ - Provides True if the policy allows exiting whatsoever, False otherwise. + Provides **True** if the policy allows exiting whatsoever, **False** + otherwise. """ rejected_ports = set() @@ -154,7 +158,7 @@ class ExitPolicy(object): >>> policy.summary() "reject 1-442, 444-1024" - :returns: str with a concise summary for our policy + :returns: **str** with a concise summary for our policy """ if self._summary_representation is None: @@ -231,8 +235,8 @@ class ExitPolicy(object): class MicrodescriptorExitPolicy(ExitPolicy): """ Exit policy provided by the microdescriptors. This is a distilled version of - a normal ExitPolicy contains, just consisting of a list of ports that are - either accepted or rejected. For instance... + a normal :class:`~stem.exit_policy.ExitPolicy` contains, just consisting of a + list of ports that are either accepted or rejected. For instance... :: @@ -241,7 +245,7 @@ class MicrodescriptorExitPolicy(ExitPolicy): Since these policies are a subset of the exit policy information (lacking IP ranges) clients can only use them to guess if a relay will accept traffic or - not. To quote the dir-spec (section 3.2.1)... + not. To quote the `dir-spec <https://gitweb.torproject.org/torspec.git/blob/HEAD:/dir-spec.txt>`_ (section 3.2.1)... :: @@ -251,7 +255,7 @@ class MicrodescriptorExitPolicy(ExitPolicy): wrong, in which case they'll have to try elsewhere. :var set ports: ports that this policy includes - :var bool is_accept: True if these are ports that we accept, False if they're ports that we reject + :var bool is_accept: **True** if these are ports that we accept, **False** if they're ports that we reject :param str policy: policy string that describes this policy """ @@ -322,7 +326,8 @@ class ExitPolicyRule(object): form complete policies that describe where a relay will and will not allow traffic to exit. - The format of these rules are formally described in the dir-spec as an + The format of these rules are formally described in the `dir-spec + <https://gitweb.torproject.org/torspec.git/blob/HEAD:/dir-spec.txt>`_ as an "exitpattern". Note that while these are similar to tor's man page entry for ExitPolicies, it's not the exact same. An exitpattern is better defined and scricter in what it'll accept. For instance, ports are not optional and it @@ -336,14 +341,14 @@ class ExitPolicyRule(object): :var AddressType address_type: type of address that we have :var str address: address that this rule is for :var str mask: subnet mask for the address (ex. "255.255.255.0") - :var int masked_bits: number of bits the subnet mask represents, None if the mask can't have a bit representation + :var int masked_bits: number of bits the subnet mask represents, **None** if the mask can't have a bit representation :var int min_port: lower end of the port range that we include (inclusive) :var int max_port: upper end of the port range that we include (inclusive) :param str rule: exit policy rule to be parsed - :raises: ValueError if input isn't a valid tor exit policy rule + :raises: **ValueError** if input isn't a valid tor exit policy rule """ def __init__(self, rule): @@ -393,36 +398,36 @@ class ExitPolicyRule(object): def is_address_wildcard(self): """ - True if we'll match against any address, False otherwise. Note that this - may be different from matching against a /0 because policies can contain - both IPv4 and IPv6 addresses (so 0.0.0.0/0 won't match against an IPv6 - address). + **True** if we'll match against any address, **False** otherwise. Note that + this may be different from matching against a /0 because policies can + contain both IPv4 and IPv6 addresses (so 0.0.0.0/0 won't match against an + IPv6 address). - :returns: bool for if our address matching is a wildcard + :returns: **bool** for if our address matching is a wildcard """ return self.address_type == AddressType.WILDCARD def is_port_wildcard(self): """ - True if we'll match against any port, False otherwise. + **True** if we'll match against any port, **False** otherwise. - :returns: bool for if our port matching is a wildcard + :returns: **bool** for if our port matching is a wildcard """ return self.min_port in (0, 1) and self.max_port == 65535 def is_match(self, address = None, port = None): """ - True if we match against the given destination, False otherwise. If the - address or port is omitted then that'll only match against a wildcard. + **True** if we match against the given destination, **False** otherwise. If + the address or port is omitted then that'll only match against a wildcard. :param str address: IPv4 or IPv6 address (with or without brackets) :param int port: port number - :returns: bool indicating if we match against this destination + :returns: **bool** indicating if we match against this destination - :raises: ValueError if provided with a malformed address or port + :raises: **ValueError** if provided with a malformed address or port """ # validate our input and check if the argumement doens't match our address type diff --git a/stem/version.py b/stem/version.py index bb75c18..42f6c16 100644 --- a/stem/version.py +++ b/stem/version.py @@ -17,7 +17,7 @@ easily parsed and compared, for instance... get_system_tor_version - gets the version of our system's tor installation - Version - Tor versioning information. + Version - Tor versioning information |- meets_requirements - checks if this version meets the given requirements |- __str__ - string representation +- __cmp__ - compares with another Version @@ -27,7 +27,7 @@ easily parsed and compared, for instance... |- less_than - adds rule that matches if we're less than a version +- in_range - adds rule that matches if we're within a given version range - Requirement - Enumerations for the version requirements of features. + Requirement - Enumerations for the version requirements of features |- AUTH_SAFECOOKIE - 'SAFECOOKIE' authentication method |- GETINFO_CONFIG_TEXT - 'GETINFO config-text' query |- TORRC_CONTROL_SOCKET - 'ControlSocket <path>' config option

1 0

[stem/master] Revised API docs for stem.descriptor.export
by atagar＠torproject.org 28 Oct '12

28 Oct '12

commit 4b528c5e75bea5892a63ed5d63d3135d46971503 Author: Damian Johnson <atagar(a)torproject.org> Date: Thu Oct 25 09:37:01 2012 -0700 Revised API docs for stem.descriptor.export --- docs/api.rst | 1 + docs/contents.rst | 2 ++ docs/descriptor/export.rst | 5 +++++ stem/descriptor/export.py | 25 ++++++++++++++++--------- stem/descriptor/reader.py | 18 +++++++++--------- 5 files changed, 33 insertions(+), 18 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index 0dfe441..25e870b 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -11,4 +11,5 @@ 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. diff --git a/docs/contents.rst b/docs/contents.rst index 7565543..c40ada6 100644 --- a/docs/contents.rst +++ b/docs/contents.rst @@ -8,7 +8,9 @@ Contents download tutorial + descriptor/export descriptor/reader + types/exit_policy types/version diff --git a/docs/descriptor/export.rst b/docs/descriptor/export.rst new file mode 100644 index 0000000..a39e777 --- /dev/null +++ b/docs/descriptor/export.rst @@ -0,0 +1,5 @@ +Descriptor Exporter +=================== + +.. automodule:: stem.descriptor.export + diff --git a/stem/descriptor/export.py b/stem/descriptor/export.py index 16a148d..f000a6d 100644 --- a/stem/descriptor/export.py +++ b/stem/descriptor/export.py @@ -1,5 +1,12 @@ """ -Utilities for exporting descriptors to other formats. +Toolkit for exporting descriptors to other formats. + +**Module Overview:** + +:: + + export_csv - Exports descriptors to a CSV + export_csv_file - Writes exported CSV output to a file """ import csv @@ -17,13 +24,13 @@ def export_csv(descriptors, included_fields = (), excluded_fields = (), header = labelled with a header row. Either 'included_fields' or 'excluded_fields' can be used for more granular control over its attributes and the order. - :param Descriptor,list descriptors: descriptor or list of descriptors to be exported + :param Descriptor,list descriptors: either a :class:`~stem.descriptor.Descriptor` or list of descriptors to be exported :param list included_fields: attributes to include in the csv :param list excluded_fields: attributes to exclude from the csv - :param bool header: if True then the first line will be a comma separated list of the attribute names + :param bool header: if **True** then the first line will be a comma separated list of the attribute names - :returns: str of the CSV for the descriptors, one per line - :raises: ValueError if descriptors contain more than one descriptor type + :returns: **str** of the CSV for the descriptors, one per line + :raises: **ValueError** if descriptors contain more than one descriptor type """ output_buffer = cStringIO.StringIO() @@ -36,13 +43,13 @@ def export_csv_file(output_file, descriptors, included_fields = (), excluded_fie written directly to a file. :param file output_file: file to be written to - :param Descriptor,list descriptors: descriptor or list of descriptors to be exported + :param Descriptor,list descriptors: either a :class:`~stem.descriptor.Descriptor` or list of descriptors to be exported :param list included_fields: attributes to include in the csv :param list excluded_fields: attributes to exclude from the csv - :param bool header: if True then the first line will be a comma separated list of the attribute names + :param bool header: if **True** then the first line will be a comma separated list of the attribute names - :returns: str of the CSV for the descriptors, one per line - :raises: ValueError if descriptors contain more than one descriptor type + :returns: **str** of the CSV for the descriptors, one per line + :raises: **ValueError** if descriptors contain more than one descriptor type """ if isinstance(descriptors, stem.descriptor.Descriptor): diff --git a/stem/descriptor/reader.py b/stem/descriptor/reader.py index 809015a..e3d29c5 100644 --- a/stem/descriptor/reader.py +++ b/stem/descriptor/reader.py @@ -52,10 +52,10 @@ and picks up where it left off if ran again... :: - load_processed_files - Loads a listing of processed files. - save_processed_files - Saves a listing of processed files. + load_processed_files - Loads a listing of processed files + save_processed_files - Saves a listing of processed files - DescriptorReader - Iterator for descriptor data on the local file system. + DescriptorReader - Iterator for descriptor data on the local file system |- get_processed_files - provides the listing of files that we've processed |- set_processed_files - sets our tracking of the files we have processed |- register_skip_listener - adds a listener that's notified of skipped files @@ -64,12 +64,12 @@ and picks up where it left off if ran again... |- __enter__ / __exit__ - manages the descriptor reader thread in the context +- __iter__ - iterates over descriptor data in unread files - FileSkipped - Base exception for a file that was skipped. - |- AlreadyRead - We've already read a file with this last modified timestamp. - |- ParsingFailure - Contents can't be parsed as descriptor data. - |- UnrecognizedType - File extension indicates non-descriptor data. - +- ReadFailed - Wraps an error that was raised while reading the file. - +- FileMissing - File does not exist. + FileSkipped - Base exception for a file that was skipped + |- AlreadyRead - We've already read a file with this last modified timestamp + |- ParsingFailure - Contents can't be parsed as descriptor data + |- UnrecognizedType - File extension indicates non-descriptor data + +- ReadFailed - Wraps an error that was raised while reading the file + +- FileMissing - File does not exist """ from __future__ import with_statement

1 0

[stem/master] Revised API docs for stem.descriptor.networkstatus
by atagar＠torproject.org 28 Oct '12

28 Oct '12

commit 29f500874cb90aa6d9c3626a609dfc957950590f Author: Damian Johnson <atagar(a)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):

1 0

[stem/master] Revised API docs for stem.descriptor.server_descriptor
by atagar＠torproject.org 28 Oct '12

28 Oct '12

commit 2c4e518adf545633e05fc97bba4718f9aebe3396 Author: Damian Johnson <atagar(a)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:

1 0

[stem/master] Revised API docs for stem.descriptor
by atagar＠torproject.org 28 Oct '12

28 Oct '12

commit 6925f6147120b645338f20abb8597d7b7787cf31 Author: Damian Johnson <atagar(a)torproject.org> Date: Thu Oct 25 18:31:02 2012 -0700 Revised API docs for stem.descriptor --- docs/api.rst | 2 ++ docs/contents.rst | 2 ++ docs/descriptor/descriptor.rst | 5 +++++ stem/descriptor/__init__.py | 16 ++++++++-------- 4 files changed, 17 insertions(+), 8 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index 25e870b..0e6d35a 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -13,3 +13,5 @@ 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. +* `stem.descriptor <descriptor/descriptor.html>`_ - Base class for descriptors. + diff --git a/docs/contents.rst b/docs/contents.rst index c40ada6..3026ccc 100644 --- a/docs/contents.rst +++ b/docs/contents.rst @@ -11,6 +11,8 @@ Contents descriptor/export descriptor/reader + descriptor/descriptor + types/exit_policy types/version diff --git a/docs/descriptor/descriptor.rst b/docs/descriptor/descriptor.rst new file mode 100644 index 0000000..0273b53 --- /dev/null +++ b/docs/descriptor/descriptor.rst @@ -0,0 +1,5 @@ +Descriptor +========== + +.. automodule:: stem.descriptor.__init__ + diff --git a/stem/descriptor/__init__.py b/stem/descriptor/__init__.py index 9d33ab7..a6aac75 100644 --- a/stem/descriptor/__init__.py +++ b/stem/descriptor/__init__.py @@ -60,8 +60,8 @@ def parse_file(path, descriptor_file): :returns: iterator for :class:`stem.descriptor.Descriptor` instances in the file :raises: - * TypeError if we can't match the contents of the file to a descriptor type - * IOError if unable to read from the descriptor_file + * **TypeError** if we can't match the contents of the file to a descriptor type + * **IOError** if unable to read from the descriptor_file """ import stem.descriptor.server_descriptor @@ -149,7 +149,7 @@ class Descriptor(object): """ Provides the absolute path that we loaded this descriptor from. - :returns: str with the absolute path of the descriptor source + :returns: **str** with the absolute path of the descriptor source """ return self._path @@ -160,7 +160,7 @@ class Descriptor(object): not know how to process. This is most common due to new descriptor fields that this library does not yet know how to process. Patches welcome! - :returns: list of lines of unrecognized content + :returns: **list** of lines of unrecognized content """ raise NotImplementedError @@ -183,7 +183,7 @@ def _read_until_keywords(keywords, descriptor_file, inclusive = False, ignore_fi :param bool skip: skips buffering content, returning None :param int end_position: end if we reach this point in the file - :returns: list with the lines until we find one of the keywords + :returns: **list** with the lines until we find one of the keywords """ content = None if skip else [] @@ -231,9 +231,9 @@ def _get_pseudo_pgp_block(remaining_contents): :param list remaining_contents: lines to be checked for a public key block - :returns: str with the armor wrapped contents or None if it doesn't exist + :returns: **str** with the armor wrapped contents or None if it doesn't exist - :raises: ValueError if the contents starts with a key block but it's malformed (for instance, if it lacks an ending line) + :raises: **ValueError** if the contents starts with a key block but it's malformed (for instance, if it lacks an ending line) """ if not remaining_contents: @@ -277,7 +277,7 @@ def _get_descriptor_components(raw_contents, validate, extra_keywords = ()): :param list extra_keywords: entity keywords to put into a separate listing with ordering intact :returns: - collections.OrderedDict with the 'keyword => (value, pgp key) entries' + **collections.OrderedDict** with the 'keyword => (value, pgp key) entries' mappings. If a extra_keywords was provided then this instead provides a two value tuple, the second being a list of those entries. """

1 0

[stem/master] Revised API docs for stem.descriptor.extrainfo_descriptor
by atagar＠torproject.org 28 Oct '12

28 Oct '12

commit 934a475cb1e07126847acdbe1166abf1d48128c1 Author: Damian Johnson <atagar(a)torproject.org> Date: Sat Oct 27 08:19:06 2012 -0700 Revised API docs for stem.descriptor.extrainfo_descriptor --- docs/api.rst | 1 + docs/contents.rst | 1 + docs/descriptor/extrainfo_descriptor.rst | 5 +++ stem/descriptor/extrainfo_descriptor.py | 54 +++++++++++++++--------------- 4 files changed, 34 insertions(+), 27 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index 5306a20..711f9d4 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -13,6 +13,7 @@ Descriptors * **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.extrainfo_descriptor <descriptor/extrainfo_descriptor.html>`_ - Relay and bridge extrainfo descriptors. * **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 9fcb296..90d61d1 100644 --- a/docs/contents.rst +++ b/docs/contents.rst @@ -13,6 +13,7 @@ Contents descriptor/descriptor descriptor/server_descriptor + descriptor/extrainfo_descriptor types/exit_policy types/version diff --git a/docs/descriptor/extrainfo_descriptor.rst b/docs/descriptor/extrainfo_descriptor.rst new file mode 100644 index 0000000..1356dae --- /dev/null +++ b/docs/descriptor/extrainfo_descriptor.rst @@ -0,0 +1,5 @@ +Extrainfo Descriptor +==================== + +.. automodule:: stem.descriptor.extrainfo_descriptor + diff --git a/stem/descriptor/extrainfo_descriptor.py b/stem/descriptor/extrainfo_descriptor.py index d66ea87..4f5d562 100644 --- a/stem/descriptor/extrainfo_descriptor.py +++ b/stem/descriptor/extrainfo_descriptor.py @@ -4,16 +4,17 @@ their server descriptor is published and have a similar format. However, unlike server descriptors these don't contain information that Tor clients require to function and as such aren't fetched by default. -Defined in section 2.2 of the dir-spec, extra-info descriptors contain -interesting but non-vital information such as usage statistics. These documents -cannot be requested of bridges. +Defined in section 2.2 of the `dir-spec +<https://gitweb.torproject.org/torspec.git/blob/HEAD:/dir-spec.txt>`_, +extra-info descriptors contain interesting but non-vital information such as +usage statistics. Tor clients cannot request these documents for bridges. Extra-info descriptors are available from a few sources... * if you have 'DownloadExtraInfo 1' in your torrc... - * control port via 'GETINFO extra-info/digest/*' queries - * the 'cached-extrainfo' file in tor's data directory + * control port via 'GETINFO extra-info/digest/\*' queries + * the 'cached-extrainfo' file in tor's data directory * tor metrics, at https://metrics.torproject.org/data.html * directory authorities and mirrors via their DirPort @@ -121,13 +122,13 @@ def parse_file(descriptor_file, validate = True): Iterates over the extra-info 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 ExtraInfoDescriptor instances in the file + :returns: iterator for :class:`~stem.descriptor.extrainfo_descriptor.ExtraInfoDescriptor` 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 """ while True: @@ -148,9 +149,9 @@ def _parse_timestamp_and_interval(keyword, content): :param str keyword: line's keyword :param str content: line content to be parsed - :returns: tuple of the form ``(timestamp (datetime), interval (int), remaining content (str))`` + :returns: **tuple** of the form (timestamp (**datetime**), interval (**int**), remaining content (**str**)) - :raises: ValueError if the content is malformed + :raises: **ValueError** if the content is malformed """ line = "%s %s" % (keyword, content) @@ -179,7 +180,7 @@ class ExtraInfoDescriptor(stem.descriptor.Descriptor): :var str fingerprint: **\*** identity key fingerprint :var datetime published: **\*** time in GMT when this descriptor was made :var str geoip_db_digest: sha1 of geoIP database file - :var dict transport: **\*** mapping of transport methods to their (address, port, args) tuple, these usually appeear on bridges in which case all of those are None + :var dict transport: **\*** mapping of transport methods to their (address, port, args) tuple, these usually appeear on bridges in which case all of those are **None** **Bi-directional connection usage:** @@ -220,18 +221,18 @@ class ExtraInfoDescriptor(stem.descriptor.Descriptor): :var dict dir_v2_requests: mapping of locales to rounded count of requests :var dict dir_v3_requests: mapping of locales to rounded count of requests - :var dict dir_v2_responses: mapping of DirResponses to their rounded count - :var dict dir_v3_responses: mapping of DirResponses to their rounded count + :var dict dir_v2_responses: mapping of **DirResponses** to their rounded count + :var dict dir_v3_responses: mapping of **DirResponses** to their rounded count :var dict dir_v2_responses_unknown: mapping of unrecognized statuses to their count :var dict dir_v3_responses_unknown: mapping of unrecognized statuses to their count - :var dict dir_v2_direct_dl: mapping of DirStats to measurement over DirPort - :var dict dir_v3_direct_dl: mapping of DirStats to measurement over DirPort + :var dict dir_v2_direct_dl: mapping of **DirStats** to measurement over DirPort + :var dict dir_v3_direct_dl: mapping of **DirStats** to measurement over DirPort :var dict dir_v2_direct_dl_unknown: mapping of unrecognized stats to their measurement :var dict dir_v3_direct_dl_unknown: mapping of unrecognized stats to their measurement - :var dict dir_v2_tunneled_dl: mapping of DirStats to measurement over ORPort - :var dict dir_v3_tunneled_dl: mapping of DirStats to measurement over ORPort + :var dict dir_v2_tunneled_dl: mapping of **DirStats** to measurement over ORPort + :var dict dir_v3_tunneled_dl: mapping of **DirStats** to measurement over ORPort :var dict dir_v2_tunneled_dl_unknown: mapping of unrecognized stats to their measurement :var dict dir_v3_tunneled_dl_unknown: mapping of unrecognized stats to their measurement @@ -267,7 +268,7 @@ class ExtraInfoDescriptor(stem.descriptor.Descriptor): :var datetime geoip_start_time: replaced by bridge_stats_end (deprecated) :var dict geoip_client_origins: replaced by bridge_ips (deprecated) - **\*** 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): @@ -277,9 +278,9 @@ class ExtraInfoDescriptor(stem.descriptor.Descriptor): either improve performance or be accepting of malformed data. :param str raw_contents: extra-info content provided by the relay - :param bool validate: checks the validity of the extra-info descriptor if True, skips these checks otherwise + :param bool validate: checks the validity of the extra-info descriptor if **True**, skips these checks otherwise - :raises: ValueError if the contents is malformed and validate is True + :raises: **ValueError** if the contents is malformed and validate is True """ super(ExtraInfoDescriptor, self).__init__(raw_contents) @@ -391,7 +392,7 @@ class ExtraInfoDescriptor(stem.descriptor.Descriptor): :param dict entries: descriptor contents to be applied :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(): @@ -728,7 +729,7 @@ class ExtraInfoDescriptor(stem.descriptor.Descriptor): Provides the hex encoded sha1 of our content. This value is part of the server descriptor 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 ExtraInfoDescriptor subclass") @@ -745,12 +746,12 @@ class ExtraInfoDescriptor(stem.descriptor.Descriptor): class RelayExtraInfoDescriptor(ExtraInfoDescriptor): """ Relay extra-info descriptor, constructed from data such as that provided by - "GETINFO extra-info/digest/*", cached descriptors, and metrics + "GETINFO extra-info/digest/\*", cached descriptors, and metrics (`specification <https://gitweb.torproject.org/torspec.git/blob/HEAD:/dir-spec.txt>`_). :var str signature: **\*** signature for this extrainfo 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): @@ -789,8 +790,7 @@ class RelayExtraInfoDescriptor(ExtraInfoDescriptor): class BridgeExtraInfoDescriptor(ExtraInfoDescriptor): """ - Bridge extra-info descriptor (`specification <https://metrics.torproject.org/formats.html#bridgedesc>`_) - + Bridge extra-info descriptor (`bridge descriptor specification <https://metrics.torproject.org/formats.html#bridgedesc>`_) """ def __init__(self, raw_contents, validate = True):

1 0

[stem/master] Revised API docs for stem.descriptor.router_status_entry
by atagar＠torproject.org 28 Oct '12

28 Oct '12

commit 8ee4c14fe0784c82637f7d3bb0b6d496c44717c9 Author: Damian Johnson <atagar(a)torproject.org> Date: Sat Oct 27 10:23:51 2012 -0700 Revised API docs for stem.descriptor.router_status_entry --- docs/api.rst | 1 + docs/contents.rst | 1 + docs/descriptor/router_status_entry.rst | 5 +++ stem/descriptor/router_status_entry.py | 53 ++++++++++++++++++------------ 4 files changed, 39 insertions(+), 21 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index b329c5a..637c634 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -15,6 +15,7 @@ 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. + * `stem.descriptor.router_status_entry <descriptor/router_status_entry.html>`_ - Relay entries within a network status document. * **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 6cbf63a..b142114 100644 --- a/docs/contents.rst +++ b/docs/contents.rst @@ -15,6 +15,7 @@ Contents descriptor/server_descriptor descriptor/extrainfo_descriptor descriptor/networkstatus + descriptor/router_status_entry types/exit_policy types/version diff --git a/docs/descriptor/router_status_entry.rst b/docs/descriptor/router_status_entry.rst new file mode 100644 index 0000000..90b2b01 --- /dev/null +++ b/docs/descriptor/router_status_entry.rst @@ -0,0 +1,5 @@ +Router Status Entries +===================== + +.. automodule:: stem.descriptor.router_status_entry + diff --git a/stem/descriptor/router_status_entry.py b/stem/descriptor/router_status_entry.py index a46d006..df0562c 100644 --- a/stem/descriptor/router_status_entry.py +++ b/stem/descriptor/router_status_entry.py @@ -3,7 +3,7 @@ Parsing for router status entries, the information for individual routers within a network status document. This information is provided from a few sources... -* control port via 'GETINFO ns/*' and 'GETINFO md/*' queries +* control port via 'GETINFO ns/\*' and 'GETINFO md/\*' queries * router entries in a network status document, like the cached-consensus **Module Overview:** @@ -32,19 +32,22 @@ def parse_file(document_file, validate, entry_class, entry_keyword = "r", start_ Either a end_position or section_end_keywords must be provided. :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 validate: checks the validity of the document's contents if + **True**, skips these checks otherwise :param class entry_class: class to construct instance for :param str entry_keyword: first keyword for the entry instances :param int start_position: start of the section, default is the current position :param int end_position: end of the section - :param tuple section_end_keywords: keyword(s) that deliminate the end of the section if no end_position was provided - :param tuple extra_args: extra arguments for the entry_class (after the content and validate flag) + :param tuple section_end_keywords: keyword(s) that deliminate the end of the + section if no end_position was provided + :param tuple extra_args: extra arguments for the entry_class (after the + content and validate flag) :returns: iterator over entry_class instances :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 """ if start_position is None: @@ -76,7 +79,8 @@ class RouterStatusEntry(stem.descriptor.Descriptor): :var list flags: **\*** list of status flags - :var stem.version.Version version: parsed version of tor, this is None if the relay's using a new versioning scheme + :var stem.version.Version version: parsed version of tor, this is **None** if + the relay's using a new versioning scheme :var str version_line: versioning information reported by the relay """ @@ -86,9 +90,10 @@ class RouterStatusEntry(stem.descriptor.Descriptor): :param str content: router descriptor content to be parsed :param NetworkStatusDocument document: document this descriptor came from - :param bool validate: checks the validity of the content if True, skips these checks otherwise + :param bool validate: checks the validity of the content if **True**, skips + these checks otherwise - :raises: ValueError if the descriptor data is invalid + :raises: **ValueError** if the descriptor data is invalid """ super(RouterStatusEntry, self).__init__(content) @@ -118,9 +123,9 @@ class RouterStatusEntry(stem.descriptor.Descriptor): Parses the given content and applies the attributes. :param dict entries: keyword => (value, pgp key) entries - :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 """ for keyword, values in entries.items(): @@ -140,7 +145,7 @@ class RouterStatusEntry(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(): @@ -200,7 +205,8 @@ class RouterStatusEntryV2(RouterStatusEntry): :var str digest: **\*** router's digest - **\*** 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, content, validate = True, document = None): @@ -244,13 +250,16 @@ class RouterStatusEntryV3(RouterStatusEntry): :var int bandwidth: bandwidth claimed by the relay (in kb/s) :var int measured: bandwith measured to be available by the relay - :var list unrecognized_bandwidth_entries: **\*** bandwidth weighting information that isn't yet recognized + :var list unrecognized_bandwidth_entries: **\*** bandwidth weighting + information that isn't yet recognized :var stem.exit_policy.MicrodescriptorExitPolicy exit_policy: router's exit policy - :var list microdescriptor_hashes: tuples of two values, the list of consensus methods for generting a set of digests and the 'algorithm => digest' mappings + :var list microdescriptor_hashes: tuples of two values, the list of consensus + methods for generting a set of digests and the 'algorithm => digest' mappings - **\*** 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, content, validate = True, document = None): @@ -309,11 +318,13 @@ class RouterStatusEntryMicroV3(RouterStatusEntry): :var int bandwidth: bandwidth claimed by the relay (in kb/s) :var int measured: bandwith measured to be available by the relay - :var list unrecognized_bandwidth_entries: **\*** bandwidth weighting information that isn't yet recognized + :var list unrecognized_bandwidth_entries: **\*** bandwidth weighting + information that isn't yet recognized :var str digest: **\*** router's base64 encoded router microdescriptor digest - **\*** 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, content, validate = True, document = None): @@ -535,11 +546,11 @@ def _decode_fingerprint(identity, validate): 'A7569A83B5706AB1B1A9CB52EFF7D2D32E4553EB' :param str identity: encoded fingerprint from the consensus - :param bool validate: checks validity if True + :param bool validate: checks validity if **True** - :returns: str with the uppercase hex encoding of the relay's fingerprint + :returns: **str** with the uppercase hex encoding of the relay's fingerprint - :raises: ValueError if the result isn't a valid fingerprint + :raises: **ValueError** if the result isn't a valid fingerprint """ # trailing equal signs were stripped from the identity

1 0

[stem/master] Revised API docs for stem.util.enum
by atagar＠torproject.org 28 Oct '12

28 Oct '12

commit 907fb84cbc11d054718ba045ac7028676f4c1746 Author: Damian Johnson <atagar(a)torproject.org> Date: Sat Oct 27 10:37:21 2012 -0700 Revised API docs for stem.util.enum --- docs/api.rst | 9 ++++++--- docs/contents.rst | 2 ++ docs/util/enum.rst | 5 +++++ stem/util/enum.py | 36 ++++++++++++++++++++---------------- 4 files changed, 33 insertions(+), 19 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index 637c634..bb0d293 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -16,8 +16,11 @@ 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. * `stem.descriptor.router_status_entry <descriptor/router_status_entry.html>`_ - Relay entries within a network status document. +* `stem.descriptor.reader <descriptor/reader.html>`_ - Reads and parses descriptor files from disk. +* `stem.descriptor.export <descriptor/export.html>`_ - Exports descriptors to other formats. -* **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. +Utilities +--------- + +* `stem.util.enum <util/enum.html>`_ - Enumeration class. diff --git a/docs/contents.rst b/docs/contents.rst index b142114..52cb6f4 100644 --- a/docs/contents.rst +++ b/docs/contents.rst @@ -20,3 +20,5 @@ Contents types/exit_policy types/version + util/enum + diff --git a/docs/util/enum.rst b/docs/util/enum.rst new file mode 100644 index 0000000..b00dca4 --- /dev/null +++ b/docs/util/enum.rst @@ -0,0 +1,5 @@ +Enumerations +============ + +.. automodule:: stem.util.enum + diff --git a/stem/util/enum.py b/stem/util/enum.py index 72c4443..9941de4 100644 --- a/stem/util/enum.py +++ b/stem/util/enum.py @@ -1,20 +1,22 @@ """ Basic enumeration, providing ordered types for collections. These can be -constructed as simple type listings, ie: +constructed as simple type listings... :: - >>> insects = Enum("ANT", "WASP", "LADYBUG", "FIREFLY") + >>> from stem.util import enum + >>> insects = enum.Enum("ANT", "WASP", "LADYBUG", "FIREFLY") >>> insects.ANT 'Ant' >>> tuple(insects) ('Ant', 'Wasp', 'Ladybug', 'Firefly') -with overwritten string counterparts: +... or with overwritten string counterparts... :: - >>> pets = Enum(("DOG", "Skippy"), "CAT", ("FISH", "Nemo")) + >>> from stem.util import enum + >>> pets = enum.Enum(("DOG", "Skippy"), "CAT", ("FISH", "Nemo")) >>> pets.DOG 'Skippy' >>> pets.CAT @@ -25,6 +27,7 @@ with overwritten string counterparts: :: UppercaseEnum - Provides an enum instance with capitalized values. + Enum - Provides a basic, ordered enumeration. |- keys - string representation of our enum keys |- index_of - indice of an enum value @@ -38,19 +41,20 @@ import stem.util.str_tools def UppercaseEnum(*args): """ - Provides an Enum instance where the values are identical to the keys. Since - the keys are uppercase by convention this means the values are too. For - instance... + Provides an :class:`~stem.util.enum.Enum` instance where the values are + identical to the keys. Since the keys are uppercase by convention this means + the values are too. For instance... :: - >>> runlevels = UppercaseEnum("DEBUG", "INFO", "NOTICE", "WARN", "ERROR") + >>> from stem.util import enum + >>> runlevels = enum.UppercaseEnum("DEBUG", "INFO", "NOTICE", "WARN", "ERROR") >>> runlevels.DEBUG 'DEBUG' :param list args: enum keys to initialize with - :returns: :class:`stem.util.Enum` instance with the given keys + :returns: :class:`~stem.util.enum.Enum` instance with the given keys """ return Enum(*[(v, v) for v in args]) @@ -82,7 +86,7 @@ class Enum(object): """ Provides an ordered listing of the enumeration keys in this set. - :returns: tuple with our enum keys + :returns: **tuple** with our enum keys """ return self._keys @@ -93,9 +97,9 @@ class Enum(object): :param str value: entry to be looked up - :returns: integer index of the given entry + :returns: **int** index of the given entry - :raises: ValueError if no such element exists + :raises: **ValueError** if no such element exists """ return self._values.index(value) @@ -108,7 +112,7 @@ class Enum(object): :returns: enum value following the given entry - :raises: ValueError if no such element exists + :raises: **ValueError** if no such element exists """ if not value in self._values: @@ -127,7 +131,7 @@ class Enum(object): :returns: enum value proceeding the given entry - :raises: ValueError if no such element exists + :raises: **ValueError** if no such element exists """ if not value in self._values: @@ -144,9 +148,9 @@ class Enum(object): :param str item: key to be looked up - :returns: str with the value for the given key + :returns: **str** with the value for the given key - :raises: ValueError if the key doesn't exist + :raises: **ValueError** if the key doesn't exist """ if item in self.__dict__:

1 0