More comments + a script to list default settings validators

lodel/plugin/__init__.py

@@ -4,10 +4,39 @@
 #
 # @section howto_writeplugin_basicstruct Plugin basic structure
 # A plugins is a python package that have to contains 3 files :
-# - <code>__init__.py</code>
-# - <code>main.py</code> ( defined in @ref lodel.plugin.plugins.MAIN_NAME )
-# - <code>confspec.py</code> ( defined in @ref lodel.plugin.plugins.CONFSPEC_NAME )
+#- <code>__init__.py</code>
+#- <code>main.py</code> ( defined in @ref lodel.plugin.plugins.MAIN_FILENAME )
+#- <code>confspec.py</code> ( defined in
+#@ref lodel.plugin.plugins.CONFSPEC_FILENAME )
 #
+# There is an example plugin in @ref plugins/dummy
+#
+# @subsection howto_writreplugin_confspec Plugin configuration specification
+# First of all a good practice is to preffix all plugin specific configuration
+# key with <code>lodel2.plugin.PLUGIN_NAME</code>.
+#
+# A configuration specification is a dict containing dict containing
+# tupe(DEFAULT_VALUE, VALIDATOR). The first level dict keys are sections, and
+# the dictionnary contained in it contains conf keys. More information on 
+# validators : @ref lodel.settings.validator
+# 
+# @subsubsection howto_writreplugin_confspec_example Example :
+#
+#A confspec that matches this peace of configuration file
+#<pre>
+#[lodel2.plugin.fooplugin]
+#hello = ...
+#foo = ...
+#bar = ...
+#</pre>
+#would be
+#<pre>
+#{
+#   'lodel2.plugin.fooplugin': {
+#                                   'foo': ...,
+#                                   'bar': ...,
+#                                   'hello': ..., } }
+#</pre>
 # 
 
 from .hooks import LodelHook

lodel/settings/__init__.py

@@ -1,7 +1,17 @@
 #-*- coding: utf-8 -*-
 
 ## @package lodel.settings Lodel2 settings package
-# 
+#
+# @par Configuration files
+# The configurations files are in ini format (thank's python ConfigParser...).
+# To know how the settings are validated and specified see
+# @ref lodel.settings.validator and @ref howto_writeplugin_basicstruct
+# The configuration is divided in two parts :
+#- a global configuration file that contains
+# - the path to the lodel2 lib directory
+# - the paths of directories containing plugins
+#- a conf.d directories containing multiple configuration files
+#  
 # @par Bootstrap/load/use in lodel instance
 # To use Settings in production you have to write a loader that will bootstrap
 # the Settings class allowing @ref lodel.settings.__init__.py to expose a copy

lodel/settings/settings.py

@@ -14,20 +14,7 @@ from lodel.settings.settings_loader import SettingsLoader
 
 ## @package lodel.settings.settings Lodel2 settings module
 #
-# Handles configuration load/parse/check.
-#
-# @subsection Configuration load process
-#
-# The configuration load process is not trivial. In fact loaded plugins are 
-# able to add their own options. But the list of plugins to load and the 
-# plugins options are in the same file, the instance configuration file.
-#
-# @subsection Configuration specification
-#
-# Configuration specification is divided in 2 parts :
-# - default values
-# - value validation/cast (see @ref Lodel.settings.validator.ConfValidator )
-# 
+# Contains the class that handles the namedtuple tree of settings
 
 ##@brief A default python system lib path
 PYTHON_SYS_LIB_PATH = '/usr/local/lib/python{major}.{minor}/'.format(
@@ -82,6 +69,8 @@ class Settings(object):
     instance = None
     
     ##@brief Should be called only by the boostrap classmethod
+    # @param conf_file str : Path to the global lodel2 configuration file
+    # @param conf_dir str : Path to the conf directory
     def __init__(self, conf_file = '/etc/lodel2/lodel2.conf', conf_dir = 'conf.d'):
         self.__confs = dict()
         self.__conf_dir = conf_dir

lodel/settings/validator.py

@@ -9,6 +9,8 @@ import copy
 ## @package lodel.settings.validator Lodel2 settings validators/cast module
 #
 # Validator are registered in the SettingValidator class.
+# @note to get a list of registered default validators just run
+# <pre>$ python scripts/settings_validator.py</pre>
 
 class SettingsValidationError(Exception):
     pass
@@ -100,12 +102,13 @@ class SettingValidator(object):
 
     
     ## @return a list of registered validators
+    @classmethod
     def validators_list_str(cls):
         result = ''
-        for name in cls._validators:
-            result += "\t%s" % name
-            if name in self._description and self._description[name] is not None:
-                result += "\t: %s" % self._description[name]
+        for name in sorted(cls._validators.keys()):
+            result += "\t%016s" % name
+            if name in cls._description and cls._description[name] is not None:
+                result += ": %s" % cls._description[name]
             result += "\n"
         return result
 

scripts/settings_validator.py

@@ -0,0 +1,6 @@
+#-*- coding: utf-8 -*-
+import sys
+import os, os.path
+sys.path.append(os.path.dirname(os.getcwd()+'/..'))
+from lodel.settings.validator import SettingValidator
+print(SettingValidator.validators_list_str())