diff doc/introduction.rst @ 139:c87b0dc54e1d

Allow custom configuration filename extensions and custom loaders that can handle custom configuration file syntax styles
author Franz Glasner <hg@dom66.de>
date Fri, 06 Apr 2018 22:28:45 +0200
parents 2f2e819e8d17
children fc2bd73f9e98
line wrap: on
line diff
--- a/doc/introduction.rst	Fri Apr 06 09:42:17 2018 +0200
+++ b/doc/introduction.rst	Fri Apr 06 22:28:45 2018 +0200
@@ -156,7 +156,7 @@
     value2 = config.getvar_s("tree1.tree2.key4")
 
 
-The filenames of the configuration files must have the extensions
+By default filenames of the configuration files must have the extensions
 (case-insensitively):
 
   ``.py``
@@ -325,3 +325,29 @@
 
 expands to something like ``CPYTHON`` when using the standard Python
 interpreter written in C.
+
+
+Custom filename extensions and custom loaders
+---------------------------------------------
+
+If you want to have custom configuration file extensions and/or custom loaders
+for custom configuration files you have various possibilities:
+
+  Associate an additional new extension (e.g. ".conf") with an
+  existing configuration file style (e.g. YAML)::
+
+    configmix.set_loader(".conf", configmix.default_loaders[".yml"])
+
+  Allow only files with extension ".cfg" in INI-style::
+
+    configmix.clear_loader()
+    configmix.set_loader(".cfg", configmix.default_loders[".ini"])
+
+  Just a new configuration file style::
+
+    def my_custom_loader(filename):
+        ...
+        return some_dict_alike
+
+    configmix.clear_loader()
+    configmix.set_loader(".my.configuration", my_custom_loader)