[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]

[tor-commits] [stem/master] Revised API docs for stem.util.conf



commit a30d89064f857e355019dbd70a37997abe475699
Author: Damian Johnson <atagar@xxxxxxxxxxxxxx>
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



_______________________________________________
tor-commits mailing list
tor-commits@xxxxxxxxxxxxxxxxxxxx
https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-commits