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

[stem/master] Line wrapping pydoc clauses
by atagar＠torproject.org 28 Oct '12

28 Oct '12

commit 670334b61dddec3b53ab5ea47d80149a81795e54 Author: Damian Johnson <atagar(a)torproject.org> Date: Sat Oct 27 10:08:44 2012 -0700 Line wrapping pydoc clauses I had been avoiding line wraps in :var:, :param:, and :return: entries to avoid confusing the spinx compiler but on reflection it's output is uneffected when we indent the following line. Just wrapping the lines that were really unweildy rather than going for a strict eighty character width. Sorry lines-of-code-must-be-shorter-than-my-iphone-screen zelots. --- stem/descriptor/__init__.py | 12 ++++-- stem/descriptor/export.py | 12 ++++-- stem/descriptor/extrainfo_descriptor.py | 22 +++++++--- stem/descriptor/networkstatus.py | 62 ++++++++++++++++++++---------- stem/descriptor/reader.py | 35 +++++++++++------ stem/descriptor/server_descriptor.py | 19 ++++++--- stem/exit_policy.py | 13 ++++-- stem/version.py | 3 +- 8 files changed, 119 insertions(+), 59 deletions(-) diff --git a/stem/descriptor/__init__.py b/stem/descriptor/__init__.py index a6aac75..edf4009 100644 --- a/stem/descriptor/__init__.py +++ b/stem/descriptor/__init__.py @@ -179,7 +179,8 @@ def _read_until_keywords(keywords, descriptor_file, inclusive = False, ignore_fi :param str,list keywords: keyword(s) we want to read until :param file descriptor_file: file with the descriptor content :param bool inclusive: includes the line with the keyword if True - :param bool ignore_first: doesn't check if the first line read has one of the given keywords + :param bool ignore_first: doesn't check if the first line read has one of the + given keywords :param bool skip: skips buffering content, returning None :param int end_position: end if we reach this point in the file @@ -233,7 +234,8 @@ def _get_pseudo_pgp_block(remaining_contents): :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: @@ -273,8 +275,10 @@ def _get_descriptor_components(raw_contents, validate, extra_keywords = ()): else in server descriptors the order does not matter. :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 list extra_keywords: entity keywords to put into a separate listing with ordering intact + :param bool validate: checks the validity of the descriptor's content if + True, skips these checks otherwise + :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' diff --git a/stem/descriptor/export.py b/stem/descriptor/export.py index f000a6d..3b71455 100644 --- a/stem/descriptor/export.py +++ b/stem/descriptor/export.py @@ -24,10 +24,12 @@ 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: either a :class:`~stem.descriptor.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 @@ -43,10 +45,12 @@ 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: either a :class:`~stem.descriptor.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 diff --git a/stem/descriptor/extrainfo_descriptor.py b/stem/descriptor/extrainfo_descriptor.py index 4f5d562..026b59b 100644 --- a/stem/descriptor/extrainfo_descriptor.py +++ b/stem/descriptor/extrainfo_descriptor.py @@ -122,9 +122,11 @@ 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 :class:`~stem.descriptor.extrainfo_descriptor.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** @@ -149,7 +151,8 @@ 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 """ @@ -180,7 +183,9 @@ 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:** @@ -268,7 +273,8 @@ 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): @@ -278,7 +284,8 @@ 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 """ @@ -790,7 +797,8 @@ class RelayExtraInfoDescriptor(ExtraInfoDescriptor): class BridgeExtraInfoDescriptor(ExtraInfoDescriptor): """ - Bridge extra-info descriptor (`bridge 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): diff --git a/stem/descriptor/networkstatus.py b/stem/descriptor/networkstatus.py index 61319e3..d78a2c6 100644 --- a/stem/descriptor/networkstatus.py +++ b/stem/descriptor/networkstatus.py @@ -36,7 +36,7 @@ constructor. Router entries are assigned to its 'routers' attribute... for router in consensus.routers: print router.nickname -* :func:`stem.descriptor.parse_file` +* :func:`stem.descriptor.networkstatus.parse_file` Alternatively, the :func:`~stem.descriptor.networkstatus.parse_file` function provides an iterator for a document's routers. Those routers refer to a 'thin' @@ -172,14 +172,17 @@ 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** + * **ValueError** if the document_version is unrecognized or the contents is + malformed and validate is **True** * **IOError** if the file can't be read """ @@ -237,7 +240,8 @@ class NetworkStatusDocumentV2(NetworkStatusDocument): Version 2 network status document. These have been deprecated and are no longer generated by Tor. - :var tuple routers: :class:`~stem.descriptor.router_status_entry.RouterStatusEntryV2` contained in the document + :var tuple routers: :class:`~stem.descriptor.router_status_entry.RouterStatusEntryV2` + contained in the document :var int version: **\*** document version @@ -256,7 +260,8 @@ class NetworkStatusDocumentV2(NetworkStatusDocument): :var str signing_authority: **\*** name of the authority signing the document :var str signature: **\*** authority's signature for the document - **\*** 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_content, validate = True): @@ -396,24 +401,30 @@ class NetworkStatusDocumentV3(NetworkStatusDocument): """ Version 3 network status document. This could be either a vote or consensus. - :var tuple routers: :class:`~stem.descriptor.router_status_entry.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_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 - :var int vote_delay: **\*** number of seconds allowed for collecting votes from all authorities - :var int dist_delay: **\*** number of seconds allowed for collecting signatures from all authorities + :var int vote_delay: **\*** number of seconds allowed for collecting votes + from all authorities + :var int dist_delay: **\*** number of seconds allowed for collecting + signatures from all authorities :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 :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 + :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:** @@ -425,7 +436,8 @@ class NetworkStatusDocumentV3(NetworkStatusDocument): :var list consensus_methods: list of ints for the supported method versions :var datetime published: time when the document was published - **\*** 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_content, validate = True, default_params = True): @@ -434,7 +446,8 @@ class NetworkStatusDocumentV3(NetworkStatusDocument): :param str raw_content: raw network status document data :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 + :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 """ @@ -782,7 +795,8 @@ 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 """ @@ -812,7 +826,8 @@ 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 """ @@ -888,7 +903,8 @@ class DirectoryAuthority(stem.descriptor.Descriptor): **Vote Attributes:** :var str legacy_dir_key: fingerprint of and obsolete identity key - :var stem.descriptor.networkstatus.KeyCertificate key_certificate: **\*** authority's key certificate + :var stem.descriptor.networkstatus.KeyCertificate key_certificate: **\*** + authority's key certificate **\*** mandatory attribute """ @@ -898,7 +914,8 @@ class DirectoryAuthority(stem.descriptor.Descriptor): Parse a directory authority entry in a v3 network status document. :param str raw_content: raw directory authority entry information - :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 :param bool is_vote: True if this is for a vote, False if it's for a consensus :raises: ValueError if the descriptor data is invalid @@ -929,7 +946,8 @@ 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 """ @@ -1067,7 +1085,8 @@ class KeyCertificate(stem.descriptor.Descriptor): :var datetime expires: **\*** time after which this key becomes invalid :var str signing_key: **\*** directory server's public signing key :var str crosscert: signature made using certificate's signing key - :var str certification: **\*** signature of this key certificate signed with the identity key + :var str certification: **\*** signature of this key certificate signed with + the identity key **\*** mandatory attribute """ @@ -1213,7 +1232,8 @@ class DocumentSignature(object): """ Directory signature of a v3 network status document. - :var str method: method used to make the signature, this only appears in microdescriptor consensuses + :var str method: method used to make the signature, this only appears in + microdescriptor consensuses :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 diff --git a/stem/descriptor/reader.py b/stem/descriptor/reader.py index e3d29c5..de525d1 100644 --- a/stem/descriptor/reader.py +++ b/stem/descriptor/reader.py @@ -1,7 +1,8 @@ """ Utilities for reading descriptors from local directories and archives. This is -mostly done through the :class:`~stem.descriptor.reader.DescriptorReader` class, which is an iterator for the -descriptor data in a series of destinations. For example... +mostly done through the :class:`~stem.descriptor.reader.DescriptorReader` +class, which is an iterator for the descriptor data in a series of +destinations. For example... :: @@ -99,7 +100,8 @@ class AlreadyRead(FileSkipped): Already read a file with this 'last modified' timestamp or later. :param int last_modified: unix timestamp for when the file was last modified - :param int last_modified_when_read: unix timestamp for the modification time when we last read this file + :param int last_modified_when_read: unix timestamp for the modification time + when we last read this file """ def __init__(self, last_modified, last_modified_when_read): @@ -134,7 +136,8 @@ class ReadFailed(FileSkipped): """ An IOError occured while trying to read the file. - :param IOError exception: issue that arose when reading the file, **None** if this arose due to the file not being present + :param IOError exception: issue that arose when reading the file, **None** if + this arose due to the file not being present """ def __init__(self, read_exception): @@ -155,7 +158,8 @@ def load_processed_files(path): :param str path: location to load the processed files dictionary from - :returns: **dict** of 'path (str) => last modified unix timestamp (int)' mappings + :returns: **dict** of 'path (**str**) => last modified unix timestamp + (**int**)' mappings :raises: * **IOError** if unable to read the file @@ -229,9 +233,12 @@ class DescriptorReader(object): :func:`~stem.descriptor.reader.save_processed_files` functions instead. :param str,list target: path or list of paths for files or directories to be read from - :param bool follow_links: determines if we'll follow symlinks when traversing directories (requires python 2.6) - :param int buffer_size: descriptors we'll buffer before waiting for some to be read, this is unbounded if zero - :param str persistence_path: if set we will load and save processed file listings from this path, errors are ignored + :param bool follow_links: determines if we'll follow symlinks when traversing + directories (requires python 2.6) + :param int buffer_size: descriptors we'll buffer before waiting for some to + be read, this is unbounded if zero + :param str persistence_path: if set we will load and save processed file + listings from this path, errors are ignored """ def __init__(self, target, follow_links = False, buffer_size = 100, persistence_path = None): @@ -277,7 +284,8 @@ class DescriptorReader(object): method. Each run resets this to only the files that were present during that run. - :returns: **dict** with the absolute paths and unix timestamp for the last modified times of the files we have processed + :returns: **dict** with the absolute paths and unix timestamp for the last + modified times of the files we have processed """ # make sure that we only provide back absolute paths @@ -289,7 +297,8 @@ class DescriptorReader(object): with a newly created :class:`~stem.descriptor.reader.DescriptorReader` to pre-populate the listing of descriptor files that we have seen. - :param dict processed_files: mapping of absolute paths (**str**) to unix timestamps for the last modified time (**int**) + :param dict processed_files: mapping of absolute paths (**str**) to unix + timestamps for the last modified time (**int**) """ self._processed_files = dict(processed_files) @@ -303,7 +312,8 @@ class DescriptorReader(object): my_listener(path, exception) - :param functor listener: functor to be notified of files that are skipped to read errors or because they couldn't be parsed as valid descriptor data + :param functor listener: functor to be notified of files that are skipped + to read errors or because they couldn't be parsed as valid descriptor data """ self._skip_listeners.append(listener) @@ -313,7 +323,8 @@ class DescriptorReader(object): Provides the number of descriptors that are waiting to be iterated over. This is limited to the buffer_size that we were constructed with. - :returns: **int** for the estimated number of currently enqueued descriptors, this is not entirely reliable + :returns: **int** for the estimated number of currently enqueued + descriptors, this is not entirely reliable """ return self._unreturned_descriptors.qsize() diff --git a/stem/descriptor/server_descriptor.py b/stem/descriptor/server_descriptor.py index 4095a62..80df7bc 100644 --- a/stem/descriptor/server_descriptor.py +++ b/stem/descriptor/server_descriptor.py @@ -73,7 +73,8 @@ 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 @@ -156,7 +157,9 @@ 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 +171,8 @@ 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,7 +186,8 @@ 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 @@ -570,7 +575,8 @@ class ServerDescriptor(stem.descriptor.Descriptor): class RelayDescriptor(ServerDescriptor): """ - Server descriptor (`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 @@ -718,7 +724,8 @@ 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: diff --git a/stem/exit_policy.py b/stem/exit_policy.py index 1c47bb5..00133d7 100644 --- a/stem/exit_policy.py +++ b/stem/exit_policy.py @@ -72,7 +72,8 @@ class ExitPolicy(object): is, in effect, just a list of :class:`~stem.exit_policy.ExitPolicyRule` entries. - :param list rules: **str** or :class:`~stem.exit_policy.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): @@ -98,7 +99,9 @@ class ExitPolicy(object): 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 + :param bool is_allowed_default: + :meth:`~stem.exit_policy.ExitPolicy.can_exit_to` default when no rules + apply """ self._is_allowed_default = is_allowed_default @@ -255,7 +258,8 @@ 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 """ @@ -341,7 +345,8 @@ 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) diff --git a/stem/version.py b/stem/version.py index 42f6c16..42ef062 100644 --- a/stem/version.py +++ b/stem/version.py @@ -93,7 +93,8 @@ class Version(object): :var int micro: micro version :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 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

1 0

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

28 Oct '12

commit 15ff02a5d2d654fb6afd6791d635ee2421f1b604 Author: Damian Johnson <atagar(a)torproject.org> Date: Sat Oct 27 15:14:26 2012 -0700 Revised API docs for stem.util.connection --- docs/api.rst | 3 +++ docs/contents.rst | 1 + docs/util/connection.rst | 5 +++++ stem/util/connection.py | 26 +++++++++++++------------- 4 files changed, 22 insertions(+), 13 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index f92a84a..01c929d 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -11,11 +11,13 @@ 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. * `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. @@ -23,5 +25,6 @@ Utilities --------- * `stem.util.conf <util/conf.html>`_ - Configuration file handling. +* `stem.util.connection <util/connection.html>`_ - Connection and IP related utilities. * `stem.util.enum <util/enum.html>`_ - Enumeration class. diff --git a/docs/contents.rst b/docs/contents.rst index 90b1af6..4cfbe21 100644 --- a/docs/contents.rst +++ b/docs/contents.rst @@ -21,5 +21,6 @@ Contents types/version util/conf + util/connection util/enum diff --git a/docs/util/connection.rst b/docs/util/connection.rst new file mode 100644 index 0000000..63e3b96 --- /dev/null +++ b/docs/util/connection.rst @@ -0,0 +1,5 @@ +Connection Utilities +==================== + +.. automodule:: stem.util.connection + diff --git a/stem/util/connection.py b/stem/util/connection.py index 02201bb..104ad5c 100644 --- a/stem/util/connection.py +++ b/stem/util/connection.py @@ -36,7 +36,7 @@ def is_valid_ip_address(address): :param str address: string to be checked - :returns: True if input is a valid IPv4 address, False otherwise + :returns: **True** if input is a valid IPv4 address, **False** otherwise """ if not isinstance(address, str): return False @@ -60,7 +60,7 @@ def is_valid_ipv6_address(address, allow_brackets = False): :param str address: string to be checked :param bool allow_brackets: ignore brackets which form '[address]' - :returns: True if input is a valid IPv6 address, False otherwise + :returns: **True** if input is a valid IPv6 address, **False** otherwise """ if allow_brackets: @@ -93,7 +93,7 @@ def is_valid_port(entry, allow_zero = False): :param list,str,int entry: string, integer or list to be checked :param bool allow_zero: accept port number of zero (reserved by defintion) - :returns: True if input is an integer and within the valid port range, False otherwise + :returns: **True** if input is an integer and within the valid port range, **False** otherwise """ if isinstance(entry, list): @@ -129,7 +129,7 @@ def expand_ipv6_address(address): :param str address: IPv6 address to be expanded - :raises: ValueError if the address can't be expanded due to being malformed + :raises: **ValueError** if the address can't be expanded due to being malformed """ if not is_valid_ipv6_address(address): @@ -158,9 +158,9 @@ def get_mask(bits): :param int bits: number of bits to be converted - :returns: str with the subnet mask representation for this many bits + :returns: **str** with the subnet mask representation for this many bits - :raises: ValueError if given a number of bits outside the range of 0-32 + :raises: **ValueError** if given a number of bits outside the range of 0-32 """ if bits > 32 or bits < 0: @@ -182,9 +182,9 @@ def get_masked_bits(mask): :param str mask: mask to be converted - :returns: int with the number of bits represented by the mask + :returns: **int** with the number of bits represented by the mask - :raises: ValueError if the mask is invalid or can't be converted + :raises: **ValueError** if the mask is invalid or can't be converted """ if not is_valid_ip_address(mask): @@ -206,9 +206,9 @@ def get_mask_ipv6(bits): :param int bits: number of bits to be converted - :returns: str with the subnet mask representation for this many bits + :returns: **str** with the subnet mask representation for this many bits - :raises: ValueError if given a number of bits outside the range of 0-128 + :raises: **ValueError** if given a number of bits outside the range of 0-128 """ if bits > 128 or bits < 0: @@ -239,9 +239,9 @@ def get_address_binary(address): """ Provides the binary value for an IPv4 or IPv6 address. - :returns: str with the binary prepresentation of this address + :returns: **str** with the binary prepresentation of this address - :raises: ValueError if address is neither an IPv4 nor IPv6 address + :raises: **ValueError** if address is neither an IPv4 nor IPv6 address """ if is_valid_ip_address(address): @@ -271,7 +271,7 @@ def cryptovariables_equal(x, y): :param str x: string to be compared. :param str y: the other string to be compared. - :returns: True if both strings are equal, False otherwise. + :returns: **True** if both strings are equal, **False** otherwise. """ return (hmac_sha256(CRYPTOVARIABLE_EQUALITY_COMPARISON_NONCE, x) ==

1 0

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

28 Oct '12

commit a30d89064f857e355019dbd70a37997abe475699 Author: Damian Johnson <atagar(a)torproject.org> Date: Sat Oct 27 14:02:09 2012 -0700 Revised API docs for stem.util.conf The utility's header was pretty sucky so rewrote it to better exemplify how this module should be used. --- docs/api.rst | 1 + docs/contents.rst | 1 + docs/util/conf.rst | 5 + stem/descriptor/networkstatus.py | 10 +- stem/descriptor/router_status_entry.py | 8 +- stem/exit_policy.py | 2 +- stem/util/conf.py | 220 ++++++++++++++++++++++---------- stem/util/enum.py | 4 +- 8 files changed, 172 insertions(+), 79 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index bb0d293..f92a84a 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -22,5 +22,6 @@ Descriptors Utilities --------- +* `stem.util.conf <util/conf.html>`_ - Configuration file handling. * `stem.util.enum <util/enum.html>`_ - Enumeration class. diff --git a/docs/contents.rst b/docs/contents.rst index 52cb6f4..90b1af6 100644 --- a/docs/contents.rst +++ b/docs/contents.rst @@ -20,5 +20,6 @@ Contents types/exit_policy types/version + util/conf util/enum diff --git a/docs/util/conf.rst b/docs/util/conf.rst new file mode 100644 index 0000000..15ce123 --- /dev/null +++ b/docs/util/conf.rst @@ -0,0 +1,5 @@ +Configuration File Handling +=========================== + +.. automodule:: stem.util.conf + diff --git a/stem/descriptor/networkstatus.py b/stem/descriptor/networkstatus.py index d78a2c6..a3eed1f 100644 --- a/stem/descriptor/networkstatus.py +++ b/stem/descriptor/networkstatus.py @@ -60,12 +60,12 @@ memory usage and upfront runtime. parse_file - parses a network status file, providing an iterator for its routers - NetworkStatusDocument - Network status document. - |- NetworkStatusDocumentV2 - Version 2 network status document. - +- NetworkStatusDocumentV3 - Version 3 network status document. + NetworkStatusDocument - Network status document + |- NetworkStatusDocumentV2 - Version 2 network status document + +- NetworkStatusDocumentV3 - Version 3 network status document - DocumentSignature - Signature of a document by a directory authority. - DirectoryAuthority - Directory authority as defined in a v3 network status document. + DocumentSignature - Signature of a document by a directory authority + DirectoryAuthority - Directory authority as defined in a v3 network status document """ import datetime diff --git a/stem/descriptor/router_status_entry.py b/stem/descriptor/router_status_entry.py index df0562c..dfa26fe 100644 --- a/stem/descriptor/router_status_entry.py +++ b/stem/descriptor/router_status_entry.py @@ -10,10 +10,10 @@ sources... :: - RouterStatusEntry - Common parent for router status entries. - |- RouterStatusEntryV2 - Entry for a network status v2 document. - |- RouterStatusEntryV3 - Entry for a network status v3 document. - +- RouterStatusEntryMicroV3 - Entry for a microdescriptor flavored v3 document. + RouterStatusEntry - Common parent for router status entries + |- RouterStatusEntryV2 - Entry for a network status v2 document + |- RouterStatusEntryV3 - Entry for a network status v3 document + +- RouterStatusEntryMicroV3 - Entry for a microdescriptor flavored v3 document """ import base64 diff --git a/stem/exit_policy.py b/stem/exit_policy.py index 00133d7..dc50c6e 100644 --- a/stem/exit_policy.py +++ b/stem/exit_policy.py @@ -35,7 +35,7 @@ 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 diff --git a/stem/util/conf.py b/stem/util/conf.py index 9781370..7bf157a 100644 --- a/stem/util/conf.py +++ b/stem/util/conf.py @@ -1,8 +1,15 @@ """ -This provides handlers for specially formatted configuration files. Entries are -expected to consist of simple key/value pairs, and anything after "#" is -stripped as a comment. Excess whitespace is trimmed and empty lines are -ignored. For instance: +Handlers for text configuration files. Configurations are simple string to +string mappings, with the configuration files using the following rules... + +* the key/value is separated by a space +* anything after a "#" is ignored as a comment +* excess whitespace is trimmed +* empty lines are ignored +* multi-line values can be defined by following the key with lines starting + with a '|' + +For instance... :: @@ -11,44 +18,108 @@ ignored. For instance: user.password yabba1234 # here's an inline comment user.notes takes a fancy to pepperjack chese blankEntry.example + + msg.greeting + |Multi-line message exclaiming of the + |wonder and awe that is pepperjack! -would be loaded as four entries, the last one's value being an empty string. -Mulit-line entries can be defined my providing an entry followed by lines with -a '|' prefix. For instance... +... would be loaded as... :: - msg.greeting - |This is a multi-line message - |exclaiming about the wonders - |and awe that is pepperjack! + config = { + "user.name": "Galen", + "user.password": "yabba1234", + "user.notes": "takes a fancy to pepperjack chese", + "blankEntry.example": "", + "msg.greeting": "Multi-line message exclaiming of the\\nwonder and awe that is pepperjack!", + } -The Config class acts as a central store for configuration values. Users of -this store have their own dictionaries of config key/value pairs that provide -three things... +Configurations are loaded or saved via the :class:`~stem.util.conf.Config` +class. The :class:`~stem.util.conf.Config` can be be used directly with its +:func:`~stem.util.conf.Config.get` and :func:`~stem.util.conf.Config.set` +methods, but usually modules will want a local dictionary with just the +configurations that it cares about. This can be done a couple ways... - 1. Default values for the configuration keys in case they're either undefined - or of the wrong type. - 2. Types that we should attempt to cast the configuration values to. - 3. An easily accessable container for getting the config values. +* **Independent Dictionary** -There are many ways of using the Config class but the most common ones are... +To simply get a dictionary that has configurations use the +:func:`~stem.util.conf.Config.synchronize` method. This takes as an argument +a dictionary with the default values. -* Call config_dict to get a dictionary that's always synced with a Config. +For instance, lets say that you had a file at '/home/atagar/user_config' +with... -* Make a dictionary and call synchronize() to bring it into sync with the - Config. This does not keep it in sync as the Config changes. See the Config - class' pydocs for an example. +:: + + username waddle_doo + permissions.ssh true + some.extra.stuff foobar -* Just call the Config's get() or get_value() methods directly. +... then run... + +:: + + >>> from stem.util.conf import get_config + >>> my_module_config = { + ... "username": "default", + ... "permissions.ssh": False, + ... "permissions.sudo": False, + ... } + + >>> config = get_config("user_config") + >>> config.load("/home/atagar/user_config") + >>> config.synchronize(my_module_config) + + >>> print my_module_config + {'username': 'waddle_doo', 'permissions.sudo': False, 'permissions.ssh': True} + +The configuration file just contains string mappings, but the +:class:`~stem.util.conf.Config` attempts to convert those values to be the same +types as the dictionary's defaults. For more information on how type inferences +work see the :func:`~stem.util.conf.Config.get` method. + +* **Linked Dictionary** + +Alternatively you can get a read-only dictionary that stays in sync with the +:class:`~stem.util.conf.Config` by using the +:func:`~stem.util.conf.config_dict` function... + +:: + + >>> # Make a dictionary that watches the 'user_config' configuration for changes. + + >>> from stem.util.conf import config_dict + >>> my_module_config = config_dict("user_config", { + ... "username": "default", + ... "permissions.ssh": False, + ... "permissions.sudo": False, + ... }) + >>> print my_module_config + {'username': 'default', 'permissions.sudo': False, 'permissions.ssh': False} + + >>> # Something (maybe another module) loads the config, causing the + >>> # my_module_config above to be updated. + + >>> from stem.util.conf import get_config + >>> config = get_config("user_config") + >>> config.load("/home/atagar/user_config") + + >>> print my_module_config + {'username': 'waddle_doo', 'permissions.sudo': False, 'permissions.ssh': True} + + >>> config.set('username', 'ness') + >>> print my_module_config + {'username': 'ness', 'permissions.sudo': False, 'permissions.ssh': True} **Module Overview:** :: config_dict - provides a dictionary that's kept synchronized with a config - get_config - Singleton for getting configurations - Config - Custom configuration. + get_config - singleton for getting configurations + + Config - Custom configuration |- load - reads a configuration file |- save - writes the current configuration to a file |- clear - empties our loaded configuration contents @@ -72,7 +143,7 @@ import stem.util.log as log CONFS = {} # mapping of identifier to singleton instances of configs -class SyncListener(object): +class _SyncListener(object): def __init__(self, config_dict, interceptor): self.config_dict = config_dict self.interceptor = interceptor @@ -91,8 +162,9 @@ class SyncListener(object): def config_dict(handle, conf_mappings, handler = None): """ Makes a dictionary that stays synchronized with a configuration. The process - for staying in sync is similar to the Config class' synchronize() method, - only changing the dictionary's values if we're able to cast to the same type. + for staying in sync is similar to the :class:`~stem.util.conf.Config` class' + :func:`~stem.util.conf.Config.synchronize` method, only changing the + dictionary's values if we're able to cast to the same type. If a handler is provided then this is called just prior to assigning new values to the config_dict. The handler function is expected to accept the @@ -106,7 +178,7 @@ def config_dict(handle, conf_mappings, handler = None): """ selected_config = get_config(handle) - selected_config.add_listener(SyncListener(conf_mappings, handler).update) + selected_config.add_listener(_SyncListener(conf_mappings, handler).update) return conf_mappings def get_config(handle): @@ -170,17 +242,22 @@ class Config(object): # Replaces the contents of ssh_config with the values from the user's # config file if... - # - the key is present in the config file - # - we're able to convert the configuration file's value to the same type + # + # * the key is present in the config file + # * we're able to convert the configuration file's value to the same type # as what's in the mapping (see the Config.get() method for how these # type inferences work) # - # For instance in this case the login values are left alone (because they - # aren't in the user's config file), and the 'destination.port' is also - # left with the value of 22 because we can't turn "blarg" into an - # integer. + # For instance in this case... + # + # * the login values are left alone because they aren't in the user's + # config file + # + # * the 'destination.port' is also left with the value of 22 because we + # can't turn "blarg" into an integer # # The other values are replaced, so ssh_config now becomes... + # # {"login.user": "atagar", # "login.password": "pepperjack_is_awesome!", # "destination.ip": "1.2.3.4", @@ -194,10 +271,6 @@ class Config(object): """ def __init__(self): - """ - Creates a new configuration instance. - """ - self._path = None # location we last loaded from or saved to self._contents = {} # configuration key/value pairs self._raw_contents = [] # raw contents read from configuration file @@ -214,11 +287,13 @@ class Config(object): Reads in the contents of the given path, adding its configuration values to our current contents. - :param str path: file path to be loaded + :param str path: file path to be loaded, this uses the last loaded path if + not provided :raises: - * IOError if we fail to read the file (it doesn't exist, insufficient permissions, etc) - * ValueError if we don't have a default path and none was provided + * **IOError** if we fail to read the file (it doesn't exist, insufficient + permissions, etc) + * **ValueError** if no path was provided and we've never been provided one """ if path: @@ -267,12 +342,12 @@ class Config(object): def save(self, path = None): """ - Saves configuration contents to the config file or to the path - specified. If a path is provided then it replaces the configuration - location that we track. + Saves configuration contents to disk. If a path is provided then it + replaces the configuration location that we track. :param str path: location to be saved to - :raises: ValueError if we don't have a default path and none was provided + + :raises: **ValueError** if no path was provided and we've never been provided one """ if path: @@ -311,10 +386,11 @@ class Config(object): * we can't convert our value to be the same type as the default_value For more information about how we convert types see our - :func:`stem.util.conf.Config.get` method. + :func:`~stem.util.conf.Config.get` method. :param dict conf_mappings: configuration key/value mappings to be revised - :param dict limits: mappings of limits on numeric values, expected to be of the form "configKey -> min" or "configKey -> (min, max)" + :param dict limits: mappings of limits on numeric values, expected to be of + the form "configKey -> min" or "configKey -> (min, max)" """ if limits is None: limits = {} @@ -338,11 +414,11 @@ class Config(object): def add_listener(self, listener, backfill = True): """ - Registers the given function to be notified of configuration updates. - Listeners are expected to be functors which accept (config, key). + Registers the function to be notified of configuration updates. Listeners + are expected to be functors which accept (config, key). :param functor listener: function to be notified when our configuration is changed - :param bool backfill: calls the function with our current values if true + :param bool backfill: calls the function with our current values if **True** """ with self._contents_lock: @@ -354,7 +430,7 @@ class Config(object): def clear_listeners(self): """ - Removes any attached listeners. + Removes all attached listeners. """ self._listeners = [] @@ -363,7 +439,7 @@ class Config(object): """ Provides all keys in the currently loaded configuration. - :returns: list if strings for the configuration keys we've loaded + :returns: **list** if strings for the configuration keys we've loaded """ return self._contents.keys() @@ -371,9 +447,11 @@ class Config(object): def unused_keys(self): """ Provides the configuration keys that have never been provided to a caller - via the get, get_value, or synchronize methods. + via the :func:`~stem.util.conf.Config.get`, + :func:`~stem.util.conf.Config.get_value`, or + :func:`~stem.util.conf.Config.synchronize` methods. - :returns: set of configuration keys we've loaded but have never been requested + :returns: **set** of configuration keys we've loaded but have never been requested """ return set(self.keys()).difference(self._requested_keys) @@ -385,7 +463,8 @@ class Config(object): :param str key: key for the configuration mapping :param str,list value: value we're setting the mapping to - :param bool overwrite: replaces the previous value if true, otherwise the values are appended + :param bool overwrite: replaces the previous value if **True**, otherwise + the values are appended """ with self._contents_lock: @@ -483,9 +562,11 @@ class Config(object): :param str key: config setting to be fetched :param object default: value provided if no such key exists - :param bool multiple: provides back a list of all values if true, otherwise this returns the last loaded configuration value + :param bool multiple: provides back a list of all values if **True**, + otherwise this returns the last loaded configuration value - :returns: string or list of string configuration values associated with the given key, providing the default if no such key exists + :returns: **str** or **list** of string configuration values associated + with the given key, providing the default if no such key exists """ with self._contents_lock: @@ -506,11 +587,14 @@ class Config(object): Fetches the given key as a comma separated value. :param str key: config setting to be fetched, last if multiple exists - :param object default: value provided if no such key exists or doesn't match the count - :param int count: if set then the default is returned when the number of elements doesn't match this value - :param str sub_key: handle the configuration entry as a dictionary and use this key within it - - :returns: list with the stripped values + :param object default: value provided if no such key exists or doesn't + match the count + :param int count: if set then the default is returned when the number of + elements doesn't match this value + :param str sub_key: handle the configuration entry as a dictionary and use + this key within it + + :returns: **list** with the stripped values """ if sub_key: conf_value = self.get(key, {}).get(sub_key) @@ -539,13 +623,15 @@ class Config(object): values aren't integers or don't follow the given constraints. :param str key: config setting to be fetched, last if multiple exists - :param object default: value provided if no such key exists, doesn't match the count, values aren't all integers, or doesn't match the bounds + :param object default: value provided if no such key exists, doesn't match + the count, values aren't all integers, or doesn't match the bounds :param int count: checks that the number of values matches this if set :param int min_value: checks that all values are over this if set :param int max_value: checks that all values are under this if set - :param str sub_key: handle the configuration entry as a dictionary and use this key within it + :param str sub_key: handle the configuration entry as a dictionary and use + this key within it - :returns: list with the stripped values + :returns: **list** with the stripped values """ conf_comp = self.get_str_csv(key, default, count, sub_key) diff --git a/stem/util/enum.py b/stem/util/enum.py index 9941de4..42ca7ea 100644 --- a/stem/util/enum.py +++ b/stem/util/enum.py @@ -26,9 +26,9 @@ constructed as simple type listings... :: - UppercaseEnum - Provides an enum instance with capitalized values. + UppercaseEnum - Provides an enum instance with capitalized values - Enum - Provides a basic, ordered enumeration. + Enum - Provides a basic, ordered enumeration |- keys - string representation of our enum keys |- index_of - indice of an enum value |- next - provides the enum after a given enum value

1 0

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

28 Oct '12

commit e4014bd0e70fc3af567f6e762d585127141279e6 Author: Damian Johnson <atagar(a)torproject.org> Date: Sat Oct 27 15:21:30 2012 -0700 Revised API docs for stem.util.str_tools --- docs/api.rst | 1 + docs/contents.rst | 1 + docs/util/str_tools.rst | 5 +++++ stem/util/str_tools.py | 21 +++++++++++---------- 4 files changed, 18 insertions(+), 10 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index 01c929d..3296228 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -27,4 +27,5 @@ Utilities * `stem.util.conf <util/conf.html>`_ - Configuration file handling. * `stem.util.connection <util/connection.html>`_ - Connection and IP related utilities. * `stem.util.enum <util/enum.html>`_ - Enumeration class. +* `stem.util.str_tools <util/str_tools.html>`_ - String utilities. diff --git a/docs/contents.rst b/docs/contents.rst index 4cfbe21..f937e77 100644 --- a/docs/contents.rst +++ b/docs/contents.rst @@ -23,4 +23,5 @@ Contents util/conf util/connection util/enum + util/str_tools diff --git a/docs/util/str_tools.rst b/docs/util/str_tools.rst new file mode 100644 index 0000000..4e15def --- /dev/null +++ b/docs/util/str_tools.rst @@ -0,0 +1,5 @@ +String Utilities +================ + +.. automodule:: stem.util.str_tools + diff --git a/stem/util/str_tools.py b/stem/util/str_tools.py index e0a6d3e..f444760 100644 --- a/stem/util/str_tools.py +++ b/stem/util/str_tools.py @@ -85,9 +85,9 @@ def get_size_label(byte_count, decimal = 0, is_long = False, is_bytes = True): :param int byte_count: number of bytes to be converted :param int decimal: number of decimal digits to be included :param bool is_long: expands units label - :param bool is_bytes: provides units in bytes if true, bits otherwise + :param bool is_bytes: provides units in bytes if **True**, bits otherwise - :returns: str with human readable representation of the size + :returns: **str** with human readable representation of the size """ if is_bytes: return _get_label(SIZE_UNITS_BYTES, byte_count, decimal, is_long) @@ -118,7 +118,7 @@ def get_time_label(seconds, decimal = 0, is_long = False): :param int decimal: number of decimal digits to be included :param bool is_long: expands units label - :returns: str with human readable representation of the time + :returns: **str** with human readable representation of the time """ return _get_label(TIME_UNITS, seconds, decimal, is_long) @@ -140,7 +140,7 @@ def get_time_labels(seconds, is_long = False): :param int seconds: number of seconds to be converted :param bool is_long: expands units label - :returns: list of strings with human readable representations of the time + :returns: **list** of strings with human readable representations of the time """ time_labels = [] @@ -167,9 +167,9 @@ def get_short_time_label(seconds): :param int seconds: number of seconds to be converted - :returns: str with the short representation for the time + :returns: **str** with the short representation for the time - :raises: ValueError if the input is negative + :raises: **ValueError** if the input is negative """ if seconds < 0: @@ -207,9 +207,9 @@ def parse_short_time_label(label): :param str label: time entry to be parsed - :returns: int with the number of seconds represented by the label + :returns: **int** with the number of seconds represented by the label - :raises: ValueError if input is malformed + :raises: **ValueError** if input is malformed """ days, hours, minutes, seconds = '0', '0', '0', '0' @@ -240,10 +240,11 @@ def _get_label(units, count, decimal, is_long): Provides label corresponding to units of the highest significance in the provided set. This rounds down (ie, integer truncation after visible units). - :param tuple units: type of units to be used for conversion, containing (count_per_unit, short_label, long_label) + :param tuple units: type of units to be used for conversion, containing + (count_per_unit, short_label, long_label) :param int count: number of base units being converted :param int decimal: decimal precision of label - :param bool is_long: uses the long label if true, short label otherwise + :param bool is_long: uses the long label if **True&&, short label otherwise """ # formatted string for the requested number of digits

1 0

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

28 Oct '12

commit 9217bb1b4bfe07235604cd2ac94d41995b8cbd33 Author: Damian Johnson <atagar(a)torproject.org> Date: Sat Oct 27 15:28:28 2012 -0700 Revised API docs for stem.util.log --- docs/api.rst | 1 + docs/contents.rst | 1 + docs/util/log.rst | 5 +++++ stem/util/log.py | 10 +++++----- 4 files changed, 12 insertions(+), 5 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index 3296228..7a2392a 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -27,5 +27,6 @@ Utilities * `stem.util.conf <util/conf.html>`_ - Configuration file handling. * `stem.util.connection <util/connection.html>`_ - Connection and IP related utilities. * `stem.util.enum <util/enum.html>`_ - Enumeration class. +* `stem.util.log <util/log.html>`_ - Logging utilities. * `stem.util.str_tools <util/str_tools.html>`_ - String utilities. diff --git a/docs/contents.rst b/docs/contents.rst index f937e77..3cc8928 100644 --- a/docs/contents.rst +++ b/docs/contents.rst @@ -23,5 +23,6 @@ Contents util/conf util/connection util/enum + util/log util/str_tools diff --git a/docs/util/log.rst b/docs/util/log.rst new file mode 100644 index 0000000..1b7e2b1 --- /dev/null +++ b/docs/util/log.rst @@ -0,0 +1,5 @@ +Logging +======= + +.. automodule:: stem.util.log + diff --git a/stem/util/log.py b/stem/util/log.py index 9caa462..b9dd988 100644 --- a/stem/util/log.py +++ b/stem/util/log.py @@ -79,7 +79,7 @@ def get_logger(): """ Provides the stem logger. - :return: logging.Logger for stem + :return: **logging.Logger** for stem """ return LOGGER @@ -88,7 +88,7 @@ def logging_level(runlevel): """ Translates a runlevel into the value expected by the logging module. - :param Runlevel runlevel: runlevel to be returned, no logging if None + :param Runlevel runlevel: runlevel to be returned, no logging if **None** """ if runlevel: return LOG_VALUES[runlevel] @@ -112,7 +112,7 @@ def log(runlevel, message): """ Logs a message at the given runlevel. - :param Runlevel runlevel: runlevel to log the message at, logging is skipped if None + :param Runlevel runlevel: runlevel to log the message at, logging is skipped if **None** :param str message: message to be logged """ @@ -125,10 +125,10 @@ def log_once(message_id, runlevel, message): been logged then this is a no-op. :param str message_id: unique message identifier to deduplicate on - :param Runlevel runlevel: runlevel to log the message at, logging is skipped if None + :param Runlevel runlevel: runlevel to log the message at, logging is skipped if **None** :param str message: message to be logged - :returns: True if we log the message, False otherwise + :returns: **True** if we log the message, **False** otherwise """ if not runlevel or message_id in DEDUPLICATION_MESSAGE_IDS:

1 0

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

28 Oct '12

commit cc37ede99703c0db0a34a3b3125339af473fe810 Author: Damian Johnson <atagar(a)torproject.org> Date: Sat Oct 27 15:35:37 2012 -0700 Revised API docs for stem.util.proc --- docs/api.rst | 1 + docs/contents.rst | 1 + docs/util/proc.rst | 5 +++++ stem/util/proc.py | 37 ++++++++++++++++++++----------------- 4 files changed, 27 insertions(+), 17 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index 7a2392a..0078810 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -28,5 +28,6 @@ Utilities * `stem.util.connection <util/connection.html>`_ - Connection and IP related utilities. * `stem.util.enum <util/enum.html>`_ - Enumeration class. * `stem.util.log <util/log.html>`_ - Logging utilities. +* `stem.util.proc <util/proc.html>`_ - Tools to read a process' proc contents. * `stem.util.str_tools <util/str_tools.html>`_ - String utilities. diff --git a/docs/contents.rst b/docs/contents.rst index 3cc8928..5d900c1 100644 --- a/docs/contents.rst +++ b/docs/contents.rst @@ -24,5 +24,6 @@ Contents util/connection util/enum util/log + util/proc util/str_tools diff --git a/docs/util/proc.rst b/docs/util/proc.rst new file mode 100644 index 0000000..c5224a8 --- /dev/null +++ b/docs/util/proc.rst @@ -0,0 +1,5 @@ +Proc Utilities +============== + +.. automodule:: stem.util.proc + diff --git a/stem/util/proc.py b/stem/util/proc.py index a57e351..5315167 100644 --- a/stem/util/proc.py +++ b/stem/util/proc.py @@ -48,7 +48,7 @@ def is_available(): """ Checks if proc information is available on this platform. - :returns: bool that's True if proc contents exist on this platform, False otherwise + :returns: **True** if proc contents exist on this platform, **False** otherwise """ global IS_PROC_AVAILABLE @@ -74,9 +74,9 @@ def get_system_start_time(): """ Provides the unix time (seconds since epoch) when the system started. - :returns: float for the unix time of when the system started + :returns: **float** for the unix time of when the system started - :raises: IOError if it can't be determined + :raises: **IOError** if it can't be determined """ global SYS_START_TIME @@ -98,9 +98,9 @@ def get_physical_memory(): """ Provides the total physical memory on the system in bytes. - :returns: int for the bytes of physical memory this system has + :returns: **int** for the bytes of physical memory this system has - :raises: IOError if it can't be determined + :raises: **IOError** if it can't be determined """ global SYS_PHYSICAL_MEMORY @@ -124,9 +124,9 @@ def get_cwd(pid): :param int pid: process id of the process to be queried - :returns: str with the path of the workign direcctory for the process + :returns: **str** with the path of the workign direcctory for the process - :raises: IOError if it can't be determined + :raises: **IOError** if it can't be determined """ start_time, parameter = time.time(), "cwd" @@ -149,9 +149,9 @@ def get_uid(pid): :param int pid: process id of the process to be queried - :returns: int with the user id for the owner of the process + :returns: **int** with the user id for the owner of the process - :raises: IOError if it can't be determined + :raises: **IOError** if it can't be determined """ start_time, parameter = time.time(), "uid" @@ -173,9 +173,10 @@ def get_memory_usage(pid): :param int pid: process id of the process to be queried - :returns: tuple of two ints with the memory usage of the process, of the form ``(resident_size, virtual_size)`` + :returns: **tuple** of two ints with the memory usage of the process, of the + form **(resident_size, virtual_size)** - :raises: IOError if it can't be determined + :raises: **IOError** if it can't be determined """ # checks if this is the kernel process @@ -208,9 +209,9 @@ def get_stats(pid, *stat_types): :param int pid: process id of the process to be queried :param Stat stat_types: information to be provided back - :returns: tuple with all of the requested statistics as strings + :returns: **tuple** with all of the requested statistics as strings - :raises: IOError if it can't be determined + :raises: **IOError** if it can't be determined """ if CLOCK_TICKS is None: @@ -268,9 +269,11 @@ def get_connections(pid): :param int pid: process id of the process to be queried - :returns: A listing of connection tuples of the form ``[(local_ipAddr1, local_port1, foreign_ipAddr1, foreign_port1), ...]`` (IP addresses are strings and ports are ints) + :returns: A listing of connection tuples of the form **[(local_ipAddr1, + local_port1, foreign_ipAddr1, foreign_port1), ...]** (IP addresses are + strings and ports are ints) - :raises: IOError if it can't be determined + :raises: **IOError** if it can't be determined """ if pid == 0: return [] @@ -341,7 +344,7 @@ def _decode_proc_address_encoding(addr): :param str addr: proc address entry to be decoded - :returns: tuple of the form ``(addr, port)``, with addr as a string and port an int + :returns: **tuple** of the form **(addr, port)**, with addr as a string and port an int """ ip, port = addr.split(':') @@ -388,7 +391,7 @@ def _get_lines(file_path, line_prefixes, parameter): :returns: mapping of prefixes to the matching line - :raises: IOError if unable to read the file or can't find all of the prefixes + :raises: **IOError** if unable to read the file or can't find all of the prefixes """ try:

1 0

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

28 Oct '12

commit d2a3acff92383ea95602acd4382cf648b5693da4 Author: Damian Johnson <atagar(a)torproject.org> Date: Sat Oct 27 15:42:02 2012 -0700 Revised API docs for stem.util.system --- docs/api.rst | 1 + docs/contents.rst | 1 + docs/util/system.rst | 5 +++++ stem/util/system.py | 40 +++++++++++++++++++++++----------------- 4 files changed, 30 insertions(+), 17 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index 0078810..9a9cc0d 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -30,4 +30,5 @@ Utilities * `stem.util.log <util/log.html>`_ - Logging utilities. * `stem.util.proc <util/proc.html>`_ - Tools to read a process' proc contents. * `stem.util.str_tools <util/str_tools.html>`_ - String utilities. +* `stem.util.system <util/system.html>`_ - Tools related to the local system. diff --git a/docs/contents.rst b/docs/contents.rst index 5d900c1..c2eb3a5 100644 --- a/docs/contents.rst +++ b/docs/contents.rst @@ -26,4 +26,5 @@ Contents util/log util/proc util/str_tools + util/system diff --git a/docs/util/system.rst b/docs/util/system.rst new file mode 100644 index 0000000..95cabb5 --- /dev/null +++ b/docs/util/system.rst @@ -0,0 +1,5 @@ +System Utilities +================ + +.. automodule:: stem.util.system + diff --git a/stem/util/system.py b/stem/util/system.py index 798f5ff..6c2be06 100644 --- a/stem/util/system.py +++ b/stem/util/system.py @@ -1,7 +1,7 @@ """ Helper functions for working with the underlying system. These are mostly os dependent, only working on linux, osx, and bsd. In almost all cases they're -best-effort, providing None if the lookup fails. +best-effort, providing **None** if the lookup fails. **Module Overview:** @@ -54,7 +54,7 @@ def is_windows(): """ Checks if we are running on Windows. - :returns: bool to indicate if we're on Windows + :returns: **bool** to indicate if we're on Windows """ return platform.system() == "Windows" @@ -63,7 +63,7 @@ def is_mac(): """ Checks if we are running on Mac OSX. - :returns: bool to indicate if we're on a Mac + :returns: **bool** to indicate if we're on a Mac """ return platform.system() == "Darwin" @@ -73,7 +73,7 @@ def is_bsd(): Checks if we are within the BSD family of operating systems. This presently recognizes Macs, FreeBSD, and OpenBSD but may be expanded later. - :returns: bool to indicate if we're on a BSD OS + :returns: **bool** to indicate if we're on a BSD OS """ return platform.system() in ("Darwin", "FreeBSD", "OpenBSD") @@ -88,9 +88,10 @@ def is_available(command, cached=True): PATH so this lookup will fail for them. :param str command: command to search for - :param bool cached: makes use of available cached results if True + :param bool cached: makes use of available cached results if **True** - :returns: True if an executable we can use by that name exists in the PATH, False otherwise + :returns: **True** if an executable we can use by that name exists in the + PATH, **False** otherwise """ if " " in command: command = command.split(" ")[0] @@ -116,7 +117,8 @@ def is_running(command): :param str command: process name to be checked - :returns: True if the process is running, False if it's not among ps results, and None if ps can't be queried + :returns: **True** if the process is running, **False** if it's not among ps + results, and **None** if ps can't be queried """ # Linux and the BSD families have different variants of ps. Guess based on @@ -166,7 +168,7 @@ def get_pid_by_name(process_name): :param str process_name: process name for which to fetch the pid - :returns: int with the process id, None if it can't be determined + :returns: **int** with the process id, **None** if it can't be determined """ # attempts to resolve using pgrep, failing if: @@ -275,7 +277,7 @@ def get_pid_by_port(port): :param int port: port where the process we're looking for is listening - :returns: int with the process id, None if it can't be determined + :returns: **int** with the process id, **None** if it can't be determined """ # attempts to resolve using netstat, failing if: @@ -387,7 +389,7 @@ def get_pid_by_open_file(path): :param str path: location of the socket file to query against - :returns: int with the process id, None if it can't be determined + :returns: **int** with the process id, **None** if it can't be determined """ # resolves using lsof which works on both Linux and BSD, only failing if: @@ -416,7 +418,8 @@ def get_cwd(pid): Provices the working directory of the given process. :param int pid: process id of the process to be queried - :returns: str with the absolute path for the process' present working directory, None if it can't be determined + :returns: **str** with the absolute path for the process' present working + directory, **None** if it can't be determined """ # try fetching via the proc contents if it's available @@ -481,7 +484,7 @@ def get_bsd_jail_id(pid): :param int pid: process id of the jail id to be queried - :returns: int for the jail id, zero if this can't be determined + :returns: **int** for the jail id, zero if this can't be determined """ # Output when called from a FreeBSD jail or when Tor isn't jailed: @@ -513,9 +516,10 @@ def expand_path(path, cwd = None): unix-specific and paths never have an ending slash. :param str path: path to be expanded - :param str cwd: current working directory to expand relative paths with, our process' if this is None + :param str cwd: current working directory to expand relative paths with, our + process' if this is **None** - :returns: str of the path expanded to be an absolute path + :returns: **str** of the path expanded to be an absolute path """ if is_windows(): @@ -554,11 +558,13 @@ def call(command, suppress_exc = True): are not permitted. :param str command: command to be issued - :param bool suppress_exc: if True then None is returned on failure, otherwise this raises the exception + :param bool suppress_exc: if **True** then **None** is returned on failure, + otherwise this raises the exception - :returns: list with the lines of output from the command, None in case of failure if suppress_exc is True + :returns: **list** with the lines of output from the command, **None** in + case of failure if suppress_exc is **True** - :raises: OSError if this fails and suppress_exc is False + :raises: **OSError** if this fails and suppress_exc is **False** """ try:

1 0

[stem/master] Collecting API stubs under a directory
by atagar＠torproject.org 28 Oct '12

28 Oct '12

commit 4167d59d8fa9d72656381dec39c6a7315176ebed Author: Damian Johnson <atagar(a)torproject.org> Date: Sat Oct 27 16:57:34 2012 -0700 Collecting API stubs under a directory Moving all the autodoc stubs under an api directory to keep things tidy. --- docs/api.rst | 36 +++++++++++++------------- docs/api/descriptor/descriptor.rst | 5 +++ docs/api/descriptor/export.rst | 5 +++ docs/api/descriptor/extrainfo_descriptor.rst | 5 +++ docs/api/descriptor/networkstatus.rst | 5 +++ docs/api/descriptor/reader.rst | 5 +++ docs/api/descriptor/router_status_entry.rst | 5 +++ docs/api/descriptor/server_descriptor.rst | 5 +++ docs/api/exit_policy.rst | 5 +++ docs/api/util/conf.rst | 5 +++ docs/api/util/connection.rst | 5 +++ docs/api/util/enum.rst | 5 +++ docs/api/util/log.rst | 5 +++ docs/api/util/proc.rst | 5 +++ docs/api/util/str_tools.rst | 5 +++ docs/api/util/system.rst | 5 +++ docs/api/util/term.rst | 5 +++ docs/api/util/tor_tools.rst | 5 +++ docs/api/version.rst | 5 +++ docs/contents.rst | 36 +++++++++++++------------- docs/descriptor/descriptor.rst | 5 --- docs/descriptor/export.rst | 5 --- docs/descriptor/extrainfo_descriptor.rst | 5 --- docs/descriptor/networkstatus.rst | 5 --- docs/descriptor/reader.rst | 5 --- docs/descriptor/router_status_entry.rst | 5 --- docs/descriptor/server_descriptor.rst | 5 --- docs/types/exit_policy.rst | 5 --- docs/types/version.rst | 5 --- docs/util/conf.rst | 5 --- docs/util/connection.rst | 5 --- docs/util/enum.rst | 5 --- docs/util/log.rst | 5 --- docs/util/proc.rst | 5 --- docs/util/str_tools.rst | 5 --- docs/util/system.rst | 5 --- docs/util/term.rst | 5 --- docs/util/tor_tools.rst | 5 --- 38 files changed, 126 insertions(+), 126 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index 2351775..e35a29a 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -4,33 +4,33 @@ 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. +* `stem.exit_policy <api/exit_policy.html>`_ - Relay policy for the destinations it will or won't allow traffic to. +* `stem.version <api/version.html>`_ - Tor versions that can be compared to determine Tor's capablilites. 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. - * `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 <api/descriptor/descriptor.html>`_ - Base class for descriptors. + * `stem.descriptor.server_descriptor <api/descriptor/server_descriptor.html>`_ - Relay and bridge server descriptors. + * `stem.descriptor.extrainfo_descriptor <api/descriptor/extrainfo_descriptor.html>`_ - Relay and bridge extrainfo descriptors. + * `stem.descriptor.networkstatus <api/descriptor/networkstatus.html>`_ - Network status documents which make up the Tor consensus. + * `stem.descriptor.router_status_entry <api/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. +* `stem.descriptor.reader <api/descriptor/reader.html>`_ - Reads and parses descriptor files from disk. +* `stem.descriptor.export <api/descriptor/export.html>`_ - Exports descriptors to other formats. Utilities --------- -* `stem.util.conf <util/conf.html>`_ - Configuration file handling. -* `stem.util.connection <util/connection.html>`_ - Connection and IP related utilities. -* `stem.util.enum <util/enum.html>`_ - Enumeration class. -* `stem.util.log <util/log.html>`_ - Logging utilities. -* `stem.util.proc <util/proc.html>`_ - Tools to read a process' proc contents. -* `stem.util.str_tools <util/str_tools.html>`_ - String utilities. -* `stem.util.system <util/system.html>`_ - Tools related to the local system. -* `stem.util.term <util/term.html>`_ - Tools for interacting with the terminal. -* `stem.util.tor_tools <util/tor_tools.html>`_ - Helper functions for working with tor. +* `stem.util.conf <api/util/conf.html>`_ - Configuration file handling. +* `stem.util.connection <api/util/connection.html>`_ - Connection and IP related utilities. +* `stem.util.enum <api/util/enum.html>`_ - Enumeration class. +* `stem.util.log <api/util/log.html>`_ - Logging utilities. +* `stem.util.proc <api/util/proc.html>`_ - Tools to read a process' proc contents. +* `stem.util.str_tools <api/util/str_tools.html>`_ - String utilities. +* `stem.util.system <api/util/system.html>`_ - Tools related to the local system. +* `stem.util.term <api/util/term.html>`_ - Tools for interacting with the terminal. +* `stem.util.tor_tools <api/util/tor_tools.html>`_ - Helper functions for working with tor. diff --git a/docs/api/descriptor/descriptor.rst b/docs/api/descriptor/descriptor.rst new file mode 100644 index 0000000..0273b53 --- /dev/null +++ b/docs/api/descriptor/descriptor.rst @@ -0,0 +1,5 @@ +Descriptor +========== + +.. automodule:: stem.descriptor.__init__ + diff --git a/docs/api/descriptor/export.rst b/docs/api/descriptor/export.rst new file mode 100644 index 0000000..a39e777 --- /dev/null +++ b/docs/api/descriptor/export.rst @@ -0,0 +1,5 @@ +Descriptor Exporter +=================== + +.. automodule:: stem.descriptor.export + diff --git a/docs/api/descriptor/extrainfo_descriptor.rst b/docs/api/descriptor/extrainfo_descriptor.rst new file mode 100644 index 0000000..1356dae --- /dev/null +++ b/docs/api/descriptor/extrainfo_descriptor.rst @@ -0,0 +1,5 @@ +Extrainfo Descriptor +==================== + +.. automodule:: stem.descriptor.extrainfo_descriptor + diff --git a/docs/api/descriptor/networkstatus.rst b/docs/api/descriptor/networkstatus.rst new file mode 100644 index 0000000..44b8bb3 --- /dev/null +++ b/docs/api/descriptor/networkstatus.rst @@ -0,0 +1,5 @@ +Network Status Documents +======================== + +.. automodule:: stem.descriptor.networkstatus + diff --git a/docs/api/descriptor/reader.rst b/docs/api/descriptor/reader.rst new file mode 100644 index 0000000..89c1a69 --- /dev/null +++ b/docs/api/descriptor/reader.rst @@ -0,0 +1,5 @@ +Descriptor Reader +================= + +.. automodule:: stem.descriptor.reader + diff --git a/docs/api/descriptor/router_status_entry.rst b/docs/api/descriptor/router_status_entry.rst new file mode 100644 index 0000000..90b2b01 --- /dev/null +++ b/docs/api/descriptor/router_status_entry.rst @@ -0,0 +1,5 @@ +Router Status Entries +===================== + +.. automodule:: stem.descriptor.router_status_entry + diff --git a/docs/api/descriptor/server_descriptor.rst b/docs/api/descriptor/server_descriptor.rst new file mode 100644 index 0000000..c46f391 --- /dev/null +++ b/docs/api/descriptor/server_descriptor.rst @@ -0,0 +1,5 @@ +Server Descriptor +================= + +.. automodule:: stem.descriptor.server_descriptor + diff --git a/docs/api/exit_policy.rst b/docs/api/exit_policy.rst new file mode 100644 index 0000000..2963fa8 --- /dev/null +++ b/docs/api/exit_policy.rst @@ -0,0 +1,5 @@ +Exit Policy +=========== + +.. automodule:: stem.exit_policy + diff --git a/docs/api/util/conf.rst b/docs/api/util/conf.rst new file mode 100644 index 0000000..15ce123 --- /dev/null +++ b/docs/api/util/conf.rst @@ -0,0 +1,5 @@ +Configuration File Handling +=========================== + +.. automodule:: stem.util.conf + diff --git a/docs/api/util/connection.rst b/docs/api/util/connection.rst new file mode 100644 index 0000000..63e3b96 --- /dev/null +++ b/docs/api/util/connection.rst @@ -0,0 +1,5 @@ +Connection Utilities +==================== + +.. automodule:: stem.util.connection + diff --git a/docs/api/util/enum.rst b/docs/api/util/enum.rst new file mode 100644 index 0000000..b00dca4 --- /dev/null +++ b/docs/api/util/enum.rst @@ -0,0 +1,5 @@ +Enumerations +============ + +.. automodule:: stem.util.enum + diff --git a/docs/api/util/log.rst b/docs/api/util/log.rst new file mode 100644 index 0000000..1b7e2b1 --- /dev/null +++ b/docs/api/util/log.rst @@ -0,0 +1,5 @@ +Logging +======= + +.. automodule:: stem.util.log + diff --git a/docs/api/util/proc.rst b/docs/api/util/proc.rst new file mode 100644 index 0000000..c5224a8 --- /dev/null +++ b/docs/api/util/proc.rst @@ -0,0 +1,5 @@ +Proc Utilities +============== + +.. automodule:: stem.util.proc + diff --git a/docs/api/util/str_tools.rst b/docs/api/util/str_tools.rst new file mode 100644 index 0000000..4e15def --- /dev/null +++ b/docs/api/util/str_tools.rst @@ -0,0 +1,5 @@ +String Utilities +================ + +.. automodule:: stem.util.str_tools + diff --git a/docs/api/util/system.rst b/docs/api/util/system.rst new file mode 100644 index 0000000..95cabb5 --- /dev/null +++ b/docs/api/util/system.rst @@ -0,0 +1,5 @@ +System Utilities +================ + +.. automodule:: stem.util.system + diff --git a/docs/api/util/term.rst b/docs/api/util/term.rst new file mode 100644 index 0000000..d9223f4 --- /dev/null +++ b/docs/api/util/term.rst @@ -0,0 +1,5 @@ +Terminal Utilities +================== + +.. automodule:: stem.util.term + diff --git a/docs/api/util/tor_tools.rst b/docs/api/util/tor_tools.rst new file mode 100644 index 0000000..87eb2af --- /dev/null +++ b/docs/api/util/tor_tools.rst @@ -0,0 +1,5 @@ +Tor Utilities +============= + +.. automodule:: stem.util.tor_tools + diff --git a/docs/api/version.rst b/docs/api/version.rst new file mode 100644 index 0000000..ad9e875 --- /dev/null +++ b/docs/api/version.rst @@ -0,0 +1,5 @@ +Version +======= + +.. automodule:: stem.version + diff --git a/docs/contents.rst b/docs/contents.rst index 58230b3..1be4021 100644 --- a/docs/contents.rst +++ b/docs/contents.rst @@ -8,25 +8,25 @@ Contents download tutorial - descriptor/export - descriptor/reader + api/exit_policy + api/version - descriptor/descriptor - descriptor/server_descriptor - descriptor/extrainfo_descriptor - descriptor/networkstatus - descriptor/router_status_entry + api/descriptor/export + api/descriptor/reader - types/exit_policy - types/version + api/descriptor/descriptor + api/descriptor/server_descriptor + api/descriptor/extrainfo_descriptor + api/descriptor/networkstatus + api/descriptor/router_status_entry - util/conf - util/connection - util/enum - util/log - util/proc - util/str_tools - util/system - util/term - util/tor_tools + api/util/conf + api/util/connection + api/util/enum + api/util/log + api/util/proc + api/util/str_tools + api/util/system + api/util/term + api/util/tor_tools diff --git a/docs/descriptor/descriptor.rst b/docs/descriptor/descriptor.rst deleted file mode 100644 index 0273b53..0000000 --- a/docs/descriptor/descriptor.rst +++ /dev/null @@ -1,5 +0,0 @@ -Descriptor -========== - -.. automodule:: stem.descriptor.__init__ - diff --git a/docs/descriptor/export.rst b/docs/descriptor/export.rst deleted file mode 100644 index a39e777..0000000 --- a/docs/descriptor/export.rst +++ /dev/null @@ -1,5 +0,0 @@ -Descriptor Exporter -=================== - -.. automodule:: stem.descriptor.export - diff --git a/docs/descriptor/extrainfo_descriptor.rst b/docs/descriptor/extrainfo_descriptor.rst deleted file mode 100644 index 1356dae..0000000 --- a/docs/descriptor/extrainfo_descriptor.rst +++ /dev/null @@ -1,5 +0,0 @@ -Extrainfo Descriptor -==================== - -.. automodule:: stem.descriptor.extrainfo_descriptor - diff --git a/docs/descriptor/networkstatus.rst b/docs/descriptor/networkstatus.rst deleted file mode 100644 index 44b8bb3..0000000 --- a/docs/descriptor/networkstatus.rst +++ /dev/null @@ -1,5 +0,0 @@ -Network Status Documents -======================== - -.. automodule:: stem.descriptor.networkstatus - diff --git a/docs/descriptor/reader.rst b/docs/descriptor/reader.rst deleted file mode 100644 index 89c1a69..0000000 --- a/docs/descriptor/reader.rst +++ /dev/null @@ -1,5 +0,0 @@ -Descriptor Reader -================= - -.. automodule:: stem.descriptor.reader - diff --git a/docs/descriptor/router_status_entry.rst b/docs/descriptor/router_status_entry.rst deleted file mode 100644 index 90b2b01..0000000 --- a/docs/descriptor/router_status_entry.rst +++ /dev/null @@ -1,5 +0,0 @@ -Router Status Entries -===================== - -.. automodule:: stem.descriptor.router_status_entry - diff --git a/docs/descriptor/server_descriptor.rst b/docs/descriptor/server_descriptor.rst deleted file mode 100644 index c46f391..0000000 --- a/docs/descriptor/server_descriptor.rst +++ /dev/null @@ -1,5 +0,0 @@ -Server Descriptor -================= - -.. automodule:: stem.descriptor.server_descriptor - diff --git a/docs/types/exit_policy.rst b/docs/types/exit_policy.rst deleted file mode 100644 index 2963fa8..0000000 --- a/docs/types/exit_policy.rst +++ /dev/null @@ -1,5 +0,0 @@ -Exit Policy -=========== - -.. automodule:: stem.exit_policy - diff --git a/docs/types/version.rst b/docs/types/version.rst deleted file mode 100644 index ad9e875..0000000 --- a/docs/types/version.rst +++ /dev/null @@ -1,5 +0,0 @@ -Version -======= - -.. automodule:: stem.version - diff --git a/docs/util/conf.rst b/docs/util/conf.rst deleted file mode 100644 index 15ce123..0000000 --- a/docs/util/conf.rst +++ /dev/null @@ -1,5 +0,0 @@ -Configuration File Handling -=========================== - -.. automodule:: stem.util.conf - diff --git a/docs/util/connection.rst b/docs/util/connection.rst deleted file mode 100644 index 63e3b96..0000000 --- a/docs/util/connection.rst +++ /dev/null @@ -1,5 +0,0 @@ -Connection Utilities -==================== - -.. automodule:: stem.util.connection - diff --git a/docs/util/enum.rst b/docs/util/enum.rst deleted file mode 100644 index b00dca4..0000000 --- a/docs/util/enum.rst +++ /dev/null @@ -1,5 +0,0 @@ -Enumerations -============ - -.. automodule:: stem.util.enum - diff --git a/docs/util/log.rst b/docs/util/log.rst deleted file mode 100644 index 1b7e2b1..0000000 --- a/docs/util/log.rst +++ /dev/null @@ -1,5 +0,0 @@ -Logging -======= - -.. automodule:: stem.util.log - diff --git a/docs/util/proc.rst b/docs/util/proc.rst deleted file mode 100644 index c5224a8..0000000 --- a/docs/util/proc.rst +++ /dev/null @@ -1,5 +0,0 @@ -Proc Utilities -============== - -.. automodule:: stem.util.proc - diff --git a/docs/util/str_tools.rst b/docs/util/str_tools.rst deleted file mode 100644 index 4e15def..0000000 --- a/docs/util/str_tools.rst +++ /dev/null @@ -1,5 +0,0 @@ -String Utilities -================ - -.. automodule:: stem.util.str_tools - diff --git a/docs/util/system.rst b/docs/util/system.rst deleted file mode 100644 index 95cabb5..0000000 --- a/docs/util/system.rst +++ /dev/null @@ -1,5 +0,0 @@ -System Utilities -================ - -.. automodule:: stem.util.system - diff --git a/docs/util/term.rst b/docs/util/term.rst deleted file mode 100644 index d9223f4..0000000 --- a/docs/util/term.rst +++ /dev/null @@ -1,5 +0,0 @@ -Terminal Utilities -================== - -.. automodule:: stem.util.term - diff --git a/docs/util/tor_tools.rst b/docs/util/tor_tools.rst deleted file mode 100644 index 87eb2af..0000000 --- a/docs/util/tor_tools.rst +++ /dev/null @@ -1,5 +0,0 @@ -Tor Utilities -============= - -.. automodule:: stem.util.tor_tools -

1 0

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

28 Oct '12

commit 8459d01c2ce4feb9c661e9bf958da5169eae58a3 Author: Damian Johnson <atagar(a)torproject.org> Date: Sat Oct 27 15:53:41 2012 -0700 Revised API docs for stem.util.tor_tools --- docs/api.rst | 1 + docs/contents.rst | 1 + docs/util/tor_tools.rst | 5 +++++ stem/util/tor_tools.py | 14 +++++++++++--- 4 files changed, 18 insertions(+), 3 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index e63c2c2..2351775 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -32,4 +32,5 @@ Utilities * `stem.util.str_tools <util/str_tools.html>`_ - String utilities. * `stem.util.system <util/system.html>`_ - Tools related to the local system. * `stem.util.term <util/term.html>`_ - Tools for interacting with the terminal. +* `stem.util.tor_tools <util/tor_tools.html>`_ - Helper functions for working with tor. diff --git a/docs/contents.rst b/docs/contents.rst index 560c14a..58230b3 100644 --- a/docs/contents.rst +++ b/docs/contents.rst @@ -28,4 +28,5 @@ Contents util/str_tools util/system util/term + util/tor_tools diff --git a/docs/util/tor_tools.rst b/docs/util/tor_tools.rst new file mode 100644 index 0000000..87eb2af --- /dev/null +++ b/docs/util/tor_tools.rst @@ -0,0 +1,5 @@ +Tor Utilities +============= + +.. automodule:: stem.util.tor_tools + diff --git a/stem/util/tor_tools.py b/stem/util/tor_tools.py index a651445..c70fbce 100644 --- a/stem/util/tor_tools.py +++ b/stem/util/tor_tools.py @@ -1,5 +1,13 @@ """ Miscellaneous utility functions for working with tor. + +**Module Overview:** + +:: + + is_valid_fingerprint - checks if a string is a valid tor relay fingerprint + is_valid_nickname - checks if a string is a valid tor relay nickname + is_hex_digits - checks if a string is only made up of hex digits """ import re @@ -26,7 +34,7 @@ def is_valid_fingerprint(entry, check_prefix = False): :param str entry: string to be checked :param bool check_prefix: checks for a '$' prefix - :returns: True if the string could be a relay fingerprint, False otherwise. + :returns: **True** if the string could be a relay fingerprint, **False** otherwise """ if not isinstance(entry, str): @@ -43,7 +51,7 @@ def is_valid_nickname(entry): :param str entry: string to be checked - :returns: True if the string could be a nickname, False otherwise. + :returns: **True** if the string could be a nickname, **False** otherwise """ if not isinstance(entry, str): @@ -59,7 +67,7 @@ def is_hex_digits(entry, count): :param str entry: string to be checked :param int count: number of hex digits to be checked for - :returns: True if the string matches this number + :returns: **True** if the string matches this number """ return bool(re.match("^%s{%i}$" % (HEX_DIGIT, count), entry))

1 0

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

28 Oct '12

commit 6de23cdc3fb45eb9493c9d3819585f414fecb9cf Author: Damian Johnson <atagar(a)torproject.org> Date: Sat Oct 27 15:49:06 2012 -0700 Revised API docs for stem.util.term --- docs/api.rst | 1 + docs/contents.rst | 1 + docs/util/term.rst | 5 +++++ stem/util/term.py | 27 +++++++++++++++++++++++++-- 4 files changed, 32 insertions(+), 2 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index 9a9cc0d..e63c2c2 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -31,4 +31,5 @@ Utilities * `stem.util.proc <util/proc.html>`_ - Tools to read a process' proc contents. * `stem.util.str_tools <util/str_tools.html>`_ - String utilities. * `stem.util.system <util/system.html>`_ - Tools related to the local system. +* `stem.util.term <util/term.html>`_ - Tools for interacting with the terminal. diff --git a/docs/contents.rst b/docs/contents.rst index c2eb3a5..560c14a 100644 --- a/docs/contents.rst +++ b/docs/contents.rst @@ -27,4 +27,5 @@ Contents util/proc util/str_tools util/system + util/term diff --git a/docs/util/term.rst b/docs/util/term.rst new file mode 100644 index 0000000..d9223f4 --- /dev/null +++ b/docs/util/term.rst @@ -0,0 +1,5 @@ +Terminal Utilities +================== + +.. automodule:: stem.util.term + diff --git a/stem/util/term.py b/stem/util/term.py index 556b481..1c97989 100644 --- a/stem/util/term.py +++ b/stem/util/term.py @@ -1,5 +1,26 @@ """ Utilities for working with the terminal. + +**Module Overview:** + +:: + + Color - enumeration for terminal colors + |- BLACK + |- BLUE + |- CYAN + |- GREEN + |- MAGENTA + |- RED + |- WHITE + +- YELLOW + + Attr - enumeration of terminal text attributes + |- BOLD + |- HILIGHT + +- UNDERLINE + + format - wrap text with ANSI for the given colors or attributes """ import stem.util.enum @@ -30,9 +51,11 @@ def format(msg, *attr): * `colorama <http://pypi.python.org/pypi/colorama>`_ :param str msg: string to be formatted - :param str attr: text attributes, this can be Color, BgColor, or Attr enums and are case insensitive (so strings like "red" are fine) + :param str attr: text attributes, this can be Color, BgColor, or Attr enums + and are case insensitive (so strings like "red" are fine) - :returns: string wrapped with ANSI escape encodings, starting with the given attributes and ending with a reset + :returns: **str** wrapped with ANSI escape encodings, starting with the given + attributes and ending with a reset """ # if we have reset sequences in the message then apply our attributes

1 0