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

[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

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

28 Oct '12

commit ec185b901de8829f12c7e0c1778f079e444ce14a Author: Damian Johnson <atagar(a)torproject.org> Date: Sat Oct 27 17:26:35 2012 -0700 Revised API docs for stem.connection --- docs/api.rst | 14 ++- docs/api/connection.rst | 5 + docs/contents.rst | 8 +- stem/connection.py | 252 ++++++++++++++++++++++++++++------------------ 4 files changed, 173 insertions(+), 106 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index e35a29a..65fa524 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -1,11 +1,17 @@ API === -Types ------ +Controller +---------- -* `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. +* **Core** + + * `stem.connection <api/connection.html>`_ - Connection and authentication to the Tor control port or socket. + +* **Types** + + * `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 ----------- diff --git a/docs/api/connection.rst b/docs/api/connection.rst new file mode 100644 index 0000000..115ba26 --- /dev/null +++ b/docs/api/connection.rst @@ -0,0 +1,5 @@ +Connection +========== + +.. automodule:: stem.connection + diff --git a/docs/contents.rst b/docs/contents.rst index 1be4021..467a122 100644 --- a/docs/contents.rst +++ b/docs/contents.rst @@ -8,18 +8,20 @@ Contents download tutorial + api/connection + api/exit_policy api/version - api/descriptor/export - api/descriptor/reader - api/descriptor/descriptor api/descriptor/server_descriptor api/descriptor/extrainfo_descriptor api/descriptor/networkstatus api/descriptor/router_status_entry + api/descriptor/export + api/descriptor/reader + api/util/conf api/util/connection api/util/enum diff --git a/stem/connection.py b/stem/connection.py index 6f32972..85b318a 100644 --- a/stem/connection.py +++ b/stem/connection.py @@ -1,14 +1,15 @@ """ -Functions for connecting and authenticating to the tor process. Most commonly -you'll either want the 'connect_*' or 'authenticate' function. +Functions for connecting and authenticating to the tor process. -The 'connect_*' functions give an easy, one line method for getting an -authenticated control connection. This is handy for CLI applications and the -python interactive interpretor, but does several things that makes it -undesirable for applications (uses stdin/stdout, suppresses exceptions, etc). +The :func:`~stem.connection.connect_port` and +:func:`~stem.connection.connect_socket_file` functions give an easy, one line +method for getting an authenticated control connection. This is handy for CLI +applications and the python interactive interpretor, but does several things +that makes it undesirable for applications (uses stdin/stdout, suppresses +exceptions, etc). -The 'authenticate' function, however, gives easy but fine-grained control over -the authentication process. For instance... +The :func:`~stem.connection.authenticate` function, however, gives easy but +fine-grained control over the authentication process. For instance... :: @@ -108,13 +109,14 @@ def connect_port(control_addr = "127.0.0.1", control_port = 9051, password = Non Convenience function for quickly getting a control connection. This is very handy for debugging or CLI setup, handling setup and prompting for a password if necessary (and none is provided). If any issues arise this prints a - description of the problem and returns None. + description of the problem and returns **None**. :param str control_addr: ip address of the controller :param int control_port: port number of the controller :param str password: passphrase to authenticate to the socket :param str chroot_path: path prefix if in a chroot environment - :param Class controller: BaseController subclass to be returned, this provides a ControlSocket if None + :param Class controller: :class:`~stem.control.BaseController` subclass to be + returned, this provides a :class:`~stem.socket.ControlSocket` if **None** :returns: authenticated control connection, the type based on the controller argument """ @@ -130,12 +132,13 @@ def connect_port(control_addr = "127.0.0.1", control_port = 9051, password = Non def connect_socket_file(socket_path = "/var/run/tor/control", password = None, chroot_path = None, controller = stem.control.Controller): """ Convenience function for quickly getting a control connection. For more - information see the connect_port function. + information see the :func:`~stem.connection.connect_port` function. :param str socket_path: path where the control socket is located :param str password: passphrase to authenticate to the socket :param str chroot_path: path prefix if in a chroot environment - :param Class controller: BaseController subclass to be returned, this provides a ControlSocket if None + :param Class controller: :class:`~stem.control.BaseController` subclass to be + returned, this provides a :class:`~stem.socket.ControlSocket` if **None** :returns: authenticated control connection, the type based on the controller argument """ @@ -155,7 +158,8 @@ def _connect(control_socket, password, chroot_path, controller): :param stem.socket.ControlSocket control_socket: socket being authenticated to :param str password: passphrase to authenticate to the socket :param str chroot_path: path prefix if in a chroot environment - :param Class controller: BaseController subclass to be returned, this provides a ControlSocket if None + :param Class controller: :class:`~stem.control.BaseController` subclass to be + returned, this provides a :class:`~stem.socket.ControlSocket` if **None** :returns: authenticated control connection, the type based on the controller argument """ @@ -187,87 +191,93 @@ def authenticate(controller, password = None, chroot_path = None, protocolinfo_r All exceptions are subclasses of AuthenticationFailure so, in practice, callers should catch the types of authentication failure that they care - about, then have a AuthenticationFailure catch-all at the end. + about, then have a :class:`~stem.connection.AuthenticationFailure` catch-all + at the end. - This can authenticate to either a :class:`stem.control.BaseController` or - :class:`stem.socket.ControlSocket`. + This can authenticate to either a :class:`~stem.control.BaseController` or + :class:`~stem.socket.ControlSocket`. :param controller: tor controller or socket to be authenticated - :param str password: passphrase to present to the socket if it uses password authentication (skips password auth if None) + :param str password: passphrase to present to the socket if it uses password + authentication (skips password auth if **None**) :param str chroot_path: path prefix if in a chroot environment - :param stem.response.protocolinfo.ProtocolInfoResponse protocolinfo_response: tor protocolinfo response, this is retrieved on our own if None + :param stem.response.protocolinfo.ProtocolInfoResponse protocolinfo_response: + tor protocolinfo response, this is retrieved on our own if **None** - :raises: If all attempts to authenticate fails then this will raise a :class:`stem.connection.AuthenticationFailure` subclass. Since this may try multiple authentication methods it may encounter multiple exceptions. If so then the exception this raises is prioritized as follows... + :raises: If all attempts to authenticate fails then this will raise a + :class:`~stem.connection.AuthenticationFailure` subclass. Since this may + try multiple authentication methods it may encounter multiple exceptions. + If so then the exception this raises is prioritized as follows... - * :class:`stem.connection.IncorrectSocketType` + * :class:`~stem.connection.IncorrectSocketType` The controller does not speak the tor control protocol. Most often this happened because the user confused the SocksPort or ORPort with the ControlPort. - * :class:`stem.connection.UnrecognizedAuthMethods` + * :class:`~stem.connection.UnrecognizedAuthMethods` All of the authentication methods tor will accept are new and unrecognized. Please upgrade stem and, if that doesn't work, file a ticket on 'trac.torproject.org' and I'd be happy to add support. - * :class:`stem.connection.MissingPassword` + * :class:`~stem.connection.MissingPassword` We were unable to authenticate but didn't attempt password authentication because none was provided. You should prompt the user for a password and try again via 'authenticate_password'. - * :class:`stem.connection.IncorrectPassword` + * :class:`~stem.connection.IncorrectPassword` We were provided with a password but it was incorrect. - * :class:`stem.connection.IncorrectCookieSize` + * :class:`~stem.connection.IncorrectCookieSize` Tor allows for authentication by reading it a cookie file, but that file is the wrong size to be an authentication cookie. - * :class:`stem.connection.UnreadableCookieFile` + * :class:`~stem.connection.UnreadableCookieFile` Tor allows for authentication by reading it a cookie file, but we can't read that file (probably due to permissions). - * **\***:class:`stem.connection.IncorrectCookieValue` + * **\***:class:`~stem.connection.IncorrectCookieValue` Tor allows for authentication by reading it a cookie file, but rejected the contents of that file. - * **\***:class:`stem.connection.AuthChallengeUnsupported` + * **\***:class:`~stem.connection.AuthChallengeUnsupported` Tor doesn't recognize the AUTHCHALLENGE command. This is probably a Tor version prior to SAFECOOKIE being implement, but this exception shouldn't arise because we won't attempt SAFECOOKIE auth unless Tor claims to support it. - * **\***:class:`stem.connection.UnrecognizedAuthChallengeMethod` + * **\***:class:`~stem.connection.UnrecognizedAuthChallengeMethod` Tor couldn't recognize the AUTHCHALLENGE method Stem sent to it. This shouldn't happen at all. - * **\***:class:`stem.connection.InvalidClientNonce` + * **\***:class:`~stem.connection.InvalidClientNonce` Tor says that the client nonce provided by Stem during the AUTHCHALLENGE process is invalid. - * **\***:class:`stem.connection.AuthSecurityFailure` + * **\***:class:`~stem.connection.AuthSecurityFailure` Nonce value provided by the server was invalid. - * **\***:class:`stem.connection.OpenAuthRejected` + * **\***:class:`~stem.connection.OpenAuthRejected` Tor says that it allows for authentication without any credentials, but then rejected our authentication attempt. - * **\***:class:`stem.connection.MissingAuthInfo` + * **\***:class:`~stem.connection.MissingAuthInfo` Tor provided us with a PROTOCOLINFO reply that is technically valid, but missing the information we need to authenticate. - * **\***:class:`stem.connection.AuthenticationFailure` + * **\***:class:`~stem.connection.AuthenticationFailure` There are numerous other ways that authentication could have failed including socket failures, malformed controller responses, etc. These @@ -278,8 +288,8 @@ def authenticate(controller, password = None, chroot_path = None, protocolinfo_r to treat these as errors. If you have a use case where this commonly happens, please file a ticket on 'trac.torproject.org'. - In the future new :class:`stem.connection.AuthenticationFailure` subclasses - may be added to allow for better error handling. + In the future new :class:`~stem.connection.AuthenticationFailure` + subclasses may be added to allow for better error handling. """ if not protocolinfo_response: @@ -390,17 +400,20 @@ def authenticate_none(controller, suppress_ctl_errors = True): If authentication fails tor will disconnect and we'll make a best effort attempt to re-establish the connection. This may not succeed, so check - is_alive() before using the socket further. + :func:`~stem.socket.ControlSocket.is_alive` before using the socket further. - This can authenticate to either a :class:`stem.control.BaseController` or - :class:`stem.socket.ControlSocket`. + This can authenticate to either a :class:`~stem.control.BaseController` or + :class:`~stem.socket.ControlSocket`. - *For general usage use the authenticate() function instead.* + For general usage use the :func:`~stem.connection.authenticate` function + instead. :param controller: tor controller or socket to be authenticated - :param bool suppress_ctl_errors: reports raised :class:`stem.socket.ControllerError` as authentication rejection if True, otherwise they're re-raised + :param bool suppress_ctl_errors: reports raised + :class:`~stem.socket.ControllerError` as authentication rejection if + **True**, otherwise they're re-raised - :raises: :class:`stem.connection.OpenAuthRejected` if the empty authentication credentials aren't accepted + :raises: :class:`~stem.connection.OpenAuthRejected` if the empty authentication credentials aren't accepted """ try: @@ -426,25 +439,31 @@ def authenticate_password(controller, password, suppress_ctl_errors = True): If authentication fails tor will disconnect and we'll make a best effort attempt to re-establish the connection. This may not succeed, so check - is_alive() before using the socket further. + :func:`~stem.socket.ControlSocket.is_alive` before using the socket further. - If you use this function directly, rather than authenticate(), we may - mistakenly raise a PasswordAuthRejected rather than IncorrectPassword. This - is because we rely on tor's error messaging which is liable to change in - future versions (`ticket <https://trac.torproject.org/4817>`_). + If you use this function directly, rather than + :func:`~stem.connection.authenticate`, we may mistakenly raise a + PasswordAuthRejected rather than IncorrectPassword. This is because we rely + on tor's error messaging which is liable to change in future versions + (`ticket <https://trac.torproject.org/4817>`_). - This can authenticate to either a :class:`stem.control.BaseController` or - :class:`stem.socket.ControlSocket`. + This can authenticate to either a :class:`~stem.control.BaseController` or + :class:`~stem.socket.ControlSocket`. - *For general usage use the authenticate() function instead.* + For general usage use the :func:`~stem.connection.authenticate` function + instead. :param controller: tor controller or socket to be authenticated :param str password: passphrase to present to the socket - :param bool suppress_ctl_errors: reports raised :class:`stem.socket.ControllerError` as authentication rejection if True, otherwise they're re-raised + :param bool suppress_ctl_errors: reports raised + :class:`~stem.socket.ControllerError` as authentication rejection if + **True**, otherwise they're re-raised :raises: - * :class:`stem.connection.PasswordAuthRejected` if the socket doesn't accept password authentication - * :class:`stem.connection.IncorrectPassword` if the authentication credentials aren't accepted + * :class:`~stem.connection.PasswordAuthRejected` if the socket doesn't + accept password authentication + * :class:`~stem.connection.IncorrectPassword` if the authentication + credentials aren't accepted """ # Escapes quotes. Tor can include those in the password hash, in which case @@ -483,32 +502,42 @@ def authenticate_cookie(controller, cookie_path, suppress_ctl_errors = True): validation that this is a cookie before presenting the contents to the socket. - The IncorrectCookieSize and UnreadableCookieFile exceptions take precedence + The :class:`~stem.connection.IncorrectCookieSize` and + :class:`~stem.connection.UnreadableCookieFile` exceptions take precedence over the other types. If authentication fails tor will disconnect and we'll make a best effort attempt to re-establish the connection. This may not succeed, so check - is_alive() before using the socket further. + :func:`~stem.socket.ControlSocket.is_alive` before using the socket further. - If you use this function directly, rather than authenticate(), we may - mistakenly raise a CookieAuthRejected rather than IncorrectCookieValue. This - is because we rely on tor's error messaging which is liable to change in - future versions (`ticket <https://trac.torproject.org/4817>`_). + If you use this function directly, rather than + :func:`~stem.connection.authenticate`, we may mistakenly raise a + :class:`~stem.connection.CookieAuthRejected` rather than + :class:`~stem.connection.IncorrectCookieValue`. This is because we rely on + tor's error messaging which is liable to change in future versions (`ticket + <https://trac.torproject.org/4817>`_). - This can authenticate to either a :class:`stem.control.BaseController` or - :class:`stem.socket.ControlSocket`. + This can authenticate to either a :class:`~stem.control.BaseController` or + :class:`~stem.socket.ControlSocket`. - *For general usage use the authenticate() function instead.* + For general usage use the :func:`~stem.connection.authenticate` function + instead. :param controller: tor controller or socket to be authenticated :param str cookie_path: path of the authentication cookie to send to tor - :param bool suppress_ctl_errors: reports raised :class:`stem.socket.ControllerError` as authentication rejection if True, otherwise they're re-raised + :param bool suppress_ctl_errors: reports raised + :class:`~stem.socket.ControllerError` as authentication rejection if + **True**, otherwise they're re-raised :raises: - * :class:`stem.connection.IncorrectCookieSize` if the cookie file's size is wrong - * :class:`stem.connection.UnreadableCookieFile` if the cookie file doesn't exist or we're unable to read it - * :class:`stem.connection.CookieAuthRejected` if cookie authentication is attempted but the socket doesn't accept it - * :class:`stem.connection.IncorrectCookieValue` if the cookie file's value is rejected + * :class:`~stem.connection.IncorrectCookieSize` if the cookie file's size + is wrong + * :class:`~stem.connection.UnreadableCookieFile` if the cookie file doesn't + exist or we're unable to read it + * :class:`~stem.connection.CookieAuthRejected` if cookie authentication is + attempted but the socket doesn't accept it + * :class:`stem.connection.IncorrectCookieValue` if the cookie file's value + is rejected """ cookie_data = _read_cookie(cookie_path, False) @@ -551,36 +580,51 @@ def authenticate_safecookie(controller, cookie_path, suppress_ctl_errors = True) 2. generate a hash digest using the challenge received in the first step, and use it to authenticate the controller - The IncorrectCookieSize and UnreadableCookieFile exceptions take - precedence over the other exception types. + The :class:`~stem.connection.IncorrectCookieSize` and + :class:`~stem.connection.UnreadableCookieFile` exceptions take precedence + over the other exception types. - The AuthChallengeUnsupported, UnrecognizedAuthChallengeMethod, - InvalidClientNonce and CookieAuthRejected exceptions are next in the order of - precedence. Depending on the reason, one of these is raised if the first + The :class:`~stem.connection.AuthChallengeUnsupported`, + :class:`~stem.connection.UnrecognizedAuthChallengeMethod`, + :class:`~stem.connection.InvalidClientNonce` and + :class:`~stem.connection.CookieAuthRejected` exceptions are next in the order + of precedence. Depending on the reason, one of these is raised if the first (AUTHCHALLENGE) step fails. - In the second (AUTHENTICATE) step, IncorrectCookieValue or - CookieAuthRejected maybe raised. + In the second (AUTHENTICATE) step, + :class:`~stem.connection.IncorrectCookieValue` or + :class:`~stem.connection.CookieAuthRejected` maybe raised. If authentication fails tor will disconnect and we'll make a best effort attempt to re-establish the connection. This may not succeed, so check - is_alive() before using the socket further. + :func:`~stem.socket.ControlSocket.is_alive` before using the socket further. - For general usage use the authenticate() function instead. + For general usage use the :func:`~stem.connection.authenticate` function + instead. :param controller: tor controller or socket to be authenticated :param str cookie_path: path of the authentication cookie to send to tor - :param bool suppress_ctl_errors: reports raised :class:`stem.socket.ControllerError` as authentication rejection if True, otherwise they're re-raised + :param bool suppress_ctl_errors: reports raised + :class:`~stem.socket.ControllerError` as authentication rejection if + **True**, otherwise they're re-raised :raises: - * :class:`stem.connection.IncorrectCookieSize` if the cookie file's size is wrong - * :class:`stem.connection.UnreadableCookieFile` if the cookie file doesn't exist or we're unable to read it - * :class:`stem.connection.CookieAuthRejected` if cookie authentication is attempted but the socket doesn't accept it - * :class:`stem.connection.IncorrectCookieValue` if the cookie file's value is rejected - * :class:`stem.connection.UnrecognizedAuthChallengeMethod` if the Tor client fails to recognize the AuthChallenge method - * :class:`stem.connection.AuthChallengeUnsupported` if AUTHCHALLENGE is unimplemented, or if unable to parse AUTHCHALLENGE response - * :class:`stem.connection.AuthSecurityFailure` if AUTHCHALLENGE's response looks like a security attack - * :class:`stem.connection.InvalidClientNonce` if stem's AUTHCHALLENGE client nonce is rejected for being invalid + * :class:`~stem.connection.IncorrectCookieSize` if the cookie file's size + is wrong + * :class:`~stem.connection.UnreadableCookieFile` if the cookie file doesn't + exist or we're unable to read it + * :class:`~stem.connection.CookieAuthRejected` if cookie authentication is + attempted but the socket doesn't accept it + * :class:`~stem.connection.IncorrectCookieValue` if the cookie file's value + is rejected + * :class:`~stem.connection.UnrecognizedAuthChallengeMethod` if the Tor + client fails to recognize the AuthChallenge method + * :class:`~stem.connection.AuthChallengeUnsupported` if AUTHCHALLENGE is + unimplemented, or if unable to parse AUTHCHALLENGE response + * :class:`~stem.connection.AuthSecurityFailure` if AUTHCHALLENGE's response + looks like a security attack + * :class:`~stem.connection.InvalidClientNonce` if stem's AUTHCHALLENGE + client nonce is rejected for being invalid """ cookie_data = _read_cookie(cookie_path, True) @@ -661,16 +705,18 @@ def get_protocolinfo(controller): path is relative then we'll make an attempt (which may not work) to correct this (`ticket <https://trac.torproject.org/1101>`_). - This can authenticate to either a :class:`stem.control.BaseController` or - :class:`stem.socket.ControlSocket`. + This can authenticate to either a :class:`~stem.control.BaseController` or + :class:`~stem.socket.ControlSocket`. :param controller: tor controller or socket to be queried - :returns: :class:`stem.response.protocolinfo.ProtocolInfoResponse` provided by tor + :returns: :class:`~stem.response.protocolinfo.ProtocolInfoResponse` provided by tor :raises: - * :class:`stem.socket.ProtocolError` if the PROTOCOLINFO response is malformed - * :class:`stem.socket.SocketError` if problems arise in establishing or using the socket + * :class:`~stem.socket.ProtocolError` if the PROTOCOLINFO response is + malformed + * :class:`~stem.socket.SocketError` if problems arise in establishing or + using the socket """ try: @@ -715,7 +761,8 @@ def get_protocolinfo(controller): def _msg(controller, message): """ - Sends and receives a message with either a ControlSocket or BaseController. + Sends and receives a message with either a + :class:`~stem.socket.ControlSocket` or :class:`~stem.control.BaseController`. """ if isinstance(controller, stem.socket.ControlSocket): @@ -729,11 +776,14 @@ def _read_cookie(cookie_path, is_safecookie): Provides the contents of a given cookie file. :param str cookie_path: absolute path of the cookie file - :param bool is_safecookie: True if this was for SAFECOOKIE authentication, False if for COOKIE + :param bool is_safecookie: **True** if this was for SAFECOOKIE + authentication, **False** if for COOKIE :raises: - * :class:`stem.connection.UnreadableCookieFile` if the cookie file is unreadable - * :class:`stem.connection.IncorrectCookieSize` if the cookie size is incorrect (not 32 bytes) + * :class:`~stem.connection.UnreadableCookieFile` if the cookie file is + unreadable + * :class:`~stem.connection.IncorrectCookieSize` if the cookie size is + incorrect (not 32 bytes) """ if not os.path.exists(cookie_path): @@ -765,8 +815,8 @@ def _read_cookie(cookie_path, is_safecookie): def _expand_cookie_path(protocolinfo_response, pid_resolver, pid_resolution_arg): """ Attempts to expand a relative cookie path with the given pid resolver. This - leaves the cookie_path alone if it's already absolute, None, or the system - calls fail. + leaves the cookie_path alone if it's already absolute, **None**, or the + system calls fail. """ cookie_path = protocolinfo_response.cookie_path @@ -795,7 +845,8 @@ class AuthenticationFailure(Exception): """ Base error for authentication failures. - :var stem.socket.ControlMessage auth_response: AUTHENTICATE response from the control socket, None if one wasn't received + :var stem.socket.ControlMessage auth_response: AUTHENTICATE response from the + control socket, **None** if one wasn't received """ def __init__(self, message, auth_response = None): @@ -839,8 +890,10 @@ class CookieAuthFailed(AuthenticationFailure): Failure to authenticate with an authentication cookie. :param str cookie_path: location of the authentication cookie we attempted - :param bool is_safecookie: True if this was for SAFECOOKIE authentication, False if for COOKIE - :param stem.response.ControlMessage auth_response: reply to our authentication attempt + :param bool is_safecookie: **True** if this was for SAFECOOKIE + authentication, **False** if for COOKIE + :param stem.response.ControlMessage auth_response: reply to our + authentication attempt """ def __init__(self, message, cookie_path, is_safecookie, auth_response = None): @@ -903,7 +956,8 @@ class NoAuthCookie(MissingAuthInfo): """ PROTOCOLINFO response supports cookie auth but doesn't have its path. - :param bool is_safecookie: True if this was for SAFECOOKIE authentication, False if for COOKIE + :param bool is_safecookie: **True** if this was for SAFECOOKIE + authentication, **False** if for COOKIE """ def __init__(self, message, is_safecookie):

1 0