From 6fb04a69fb4587cfd6b0b4b19e42fb802af1d61c Mon Sep 17 00:00:00 2001
From: Yann <yann.weber@openedition.org>
Date: Wed, 25 May 2016 15:08:00 +0200
Subject: [PATCH] Documentation on datasources plugins + confspec updates in
 validator.py

+ a new validator named 'string', it tries to cast the conf value using str()
---
 lodel/settings/validator.py          | 15 ++++++
 plugins/dummy_datasource/__init__.py |  0
 plugins/dummy_datasource/confspec.py | 81 ++++++++++++++++++++++++++++
 3 files changed, 96 insertions(+)
 create mode 100644 plugins/dummy_datasource/__init__.py
 create mode 100644 plugins/dummy_datasource/confspec.py

diff --git a/lodel/settings/validator.py b/lodel/settings/validator.py
index 6b3c5e9..dff275d 100644
--- a/lodel/settings/validator.py
+++ b/lodel/settings/validator.py
@@ -183,6 +183,12 @@ def none_val(value):
         return None
     raise SettingsValidationError("This settings cannot be set in configuration file")
 
+def str_val(value):
+    try:
+        str(value)
+    except Exception as e:
+        raise SettingsValidationError("Not able to convert value to string : " + str(e))
+
 #
 #   Default validators registration
 #
@@ -197,6 +203,11 @@ SettingValidator.register_validator(
                                         none_val,
                                         'Validate None')
 
+SettingValidator.register_validator(
+                                        'string',
+                                        str_val,
+                                        'Validate string values')
+
 SettingValidator.register_validator(
                                         'strip',
                                         str.strip,
@@ -294,5 +305,9 @@ LODEL2_CONF_SPECS = {
                     SettingValidator('list')),
         'editormode': ( False,
                         SettingValidator('bool')),
+    },
+    'lodel2.datasources.*': {
+            'identifier': ( None,
+                            SettingValidator('string'))
     }
 }
diff --git a/plugins/dummy_datasource/__init__.py b/plugins/dummy_datasource/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/plugins/dummy_datasource/confspec.py b/plugins/dummy_datasource/confspec.py
new file mode 100644
index 0000000..0fd430b
--- /dev/null
+++ b/plugins/dummy_datasource/confspec.py
@@ -0,0 +1,81 @@
+#-*- coding: utf-8 -*-
+
+from lodel.settings.validator import SettingValidator
+
+CONFSPEC = {}
+
+##@page lodel2_datasources Lodel2 datasources
+#
+#@par lodel2_datasources_intro Intro
+# A single lodel2 website can interact with multiple datasources. This page
+# aims to describe configuration & organisation of datasources in lodel2.
+# Each object is attached to a datasource. This association is done in the
+# editorial model, the datasource is identified by a name.
+#
+#@par Datasources declaration
+# To define a datasource you have to write something like this in confs file :
+#<pre>
+#[lodel2.datasources.DATASOURCE_NAME]
+#identifier = DATASOURCE_FAMILY.SOURCE_NAME
+#</pre>
+# See below for DATASOURCE_FAMILY & SOURCE_NAME
+#
+#@par Datasources plugins
+# Each datasource family is a plugin. For example mysql or a mongodb plugins.
+# Here is the CONFSPEC variable templates for datasources plugins
+#<pre>
+#CONFSPEC = {
+#                'lodel2.datasource.example.*' : {
+#                    'conf1' : VALIDATOR_OPTS,
+#                    'conf2' : VALIDATOR_OPTS,
+#                    ...
+#                }
+#}
+#</pre>
+#MySQL example
+#<pre>
+#CONFSPEC = {
+#                'lodel2.datasource.mysql.*' : {
+#                    'host': (   'localhost',
+#                                SettingValidator('host')),
+#                    'db_name': (    'lodel',
+#                                    SettingValidator('string')),
+#                    'username': (   None,
+#                                    SettingValidator('string')),
+#                    'password': (   None,
+#                                    SettingValidator('string')),
+#                }
+#}
+#</pre>
+#
+#@par Configuration example
+#<pre>
+# [lodel2.datasources.main]
+# identifier = mysql.Core
+# [lodel2.datasources.revues_write]
+# identifier = mysql.Revues
+# [lodel2.datasources.revues_read]
+# identifier = mysql.Revues
+# [lodel2.datasources.annuaire_persons]
+# identifier = persons_web_api.example
+# ;
+# ; Then, in the editorial model you are able to use "main", "revues_write", 
+# ; etc as datasource
+# ;
+# ; Here comes the datasources declarations
+# [lodel2.datasource.mysql.Core]
+# host = db.core.labocleo.org
+# db_name = core
+# username = foo
+# password = bar
+# ;
+# [lodel2.datasource.mysql.Revues]
+# host = revues.org
+# db_name = RO
+# username = foo
+# password = bar
+# ;
+# [lodel2.datasource.persons_web_api.example]
+# host = foo.bar
+# username = cleo
+#</pre>