Docstrings for the pecan.configuration module.

pecan/configuration.py

@@ -10,12 +10,30 @@ class ConfigDict(dict):
     pass
 
 class Config(object):
+    '''
+    Base class for Pecan configurations.
+    '''
+    
     def __init__(self, conf_dict={}, filename=''):
+        '''
+        Create a Pecan configuration object from a dictionary or a 
+        filename.
+        
+        :param conf_dict: A python dictionary to use for the configuration.
+        :param filename: A filename to use for the configuration.
+        '''
+        
         self.__values__ = {}
         self.__file__ = filename
         self.update(conf_dict)
 
     def update(self, conf_dict):
+        '''
+        Updates this configuration with a dictionary.
+        
+        :param conf_dict: A python dictionary to update this configuration with.
+        '''
+        
         if isinstance(conf_dict, dict):
             iterator = conf_dict.iteritems()
         else:
@@ -33,6 +51,12 @@ class Config(object):
                 self[k] = conf_dict[k]
 
     def update_with_module(self, module):
+        '''
+        Updates this configuration with a module.
+        
+        :param module: The module to update this configuration with. Either a string or the module itself.
+        '''
+        
         self.update(conf_from_module(module))
 
     def __getattr__(self, name):
@@ -67,6 +91,12 @@ class Config(object):
         return 'Config(%s)' % str(self.__values__)
 
 def conf_from_module(module):
+    '''
+    Creates a configuration dictionary from a module.
+    
+    :param module: The module, either as a string or the module itself.
+    '''
+    
     if isinstance(module, str):
         module = import_module(module)
 
@@ -76,6 +106,12 @@ def conf_from_module(module):
 
 
 def conf_from_file(filepath):
+    '''
+    Creates a configuration dictionary from a file.
+    
+    :param filepath: The path to the file.
+    '''
+    
     abspath = os.path.abspath(os.path.expanduser(filepath))
     conf_dict = {}
 
@@ -86,6 +122,12 @@ def conf_from_file(filepath):
 
 
 def conf_from_dict(conf_dict):
+    '''
+    Creates a configuration dictionary from a dictionary.
+    
+    :param conf_dict: The configuration dictionary.
+    '''
+    
     conf = Config(filename=conf_dict.get('__file__', ''))
 
     for k,v in conf_dict.iteritems():
@@ -99,6 +141,12 @@ def conf_from_dict(conf_dict):
 
 
 def import_module(conf):
+    '''
+    Imports the a configuration as a module.
+    
+    :param conf: The string to the configuration. Automatically strips off ".py" file extensions.
+    '''
+    
     if conf.endswith('.py'):
         conf = conf[:-3]
     
@@ -119,12 +167,23 @@ def import_module(conf):
 
 
 def initconf():
+    '''
+    Initializes the default configuration and exposes it at ``pecan.configuration.conf``,
+    which is also exposed at ``pecan.conf``.
+    '''
+    
     import default_config
     conf = conf_from_module(default_config)
     return conf
 
 
 def set_config(name):
+    '''
+    Updates the global configuration from a path or filename.
+    
+    :param name: Path or filename, as a string.
+    '''
+    
     if '/' in name:
         _runtime_conf.update(conf_from_file(name))
     else: