Python/libs/ConfigMix: doc/introduction.rst annotate

annotate doc/introduction.rst @ 200:c6904d02beae

Doc: some wording

author	Franz Glasner <fzglas.hg@dom66.de>
date	Sun, 05 May 2019 11:36:12 +0200
parents	28e6c1413947
children	2e66178a09d8

rev	line source
94 2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	1 .. -- coding: utf-8; indent-tabs-mode: nil; --
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	2
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	3 .. _introduction:
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	4
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	5 Introduction
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	6 ============
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	7
161 4643763b39ee Docu: print a local table of contents in the introduction Franz Glasner <fzglas.hg@dom66.de> parents: 158 diff changeset	8 .. contents::
4643763b39ee Docu: print a local table of contents in the introduction Franz Glasner <fzglas.hg@dom66.de> parents: 158 diff changeset	9 :local:
4643763b39ee Docu: print a local table of contents in the introduction Franz Glasner <fzglas.hg@dom66.de> parents: 158 diff changeset	10
94 2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	11 The configurations can be read from different types of files:
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	12
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	13 - :ref:`YAML files <yaml-files>`
131 b34ad08e7198 Document the JSON files Franz Glasner <hg@dom66.de> parents: 122 diff changeset	14 - :ref:`JSON files <json-files>`
94 2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	15 - :ref:`INI files <ini-files>`
195 28e6c1413947 Added support for TOML style configuration files Franz Glasner <fzglas.hg@dom66.de> parents: 194 diff changeset	16 - :ref:`TOML files <toml-files>`
94 2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	17 - :ref:`executable Python scripts <executable-python-scripts>`
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	18
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	19
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	20 .. _yaml-files:
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	21
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	22 YAML Files
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	23 ----------
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	24
200 c6904d02beae Doc: some wording Franz Glasner <fzglas.hg@dom66.de> parents: 195 diff changeset	25 Need the :mod:`yaml` package (https://github.com/yaml/pyyaml)
c6904d02beae Doc: some wording Franz Glasner <fzglas.hg@dom66.de> parents: 195 diff changeset	26 (e.g. ``pip install pyyaml``)
94 2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	27
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	28 .. note:: All strings are returned as Unicode text strings.
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	29
134 2f2e819e8d17 Check the return type of the JSON and YAML loading functions: they must be a dict alike Franz Glasner <hg@dom66.de> parents: 133 diff changeset	30 .. note:: The root object must be a mapping and therefore decode
2f2e819e8d17 Check the return type of the JSON and YAML loading functions: they must be a dict alike Franz Glasner <hg@dom66.de> parents: 133 diff changeset	31 into a Python :class:`dict` alike. This is checked by the
2f2e819e8d17 Check the return type of the JSON and YAML loading functions: they must be a dict alike Franz Glasner <hg@dom66.de> parents: 133 diff changeset	32 implementation.
94 2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	33
97 1b4d95f60650 Build a tree-ish configuration from an INI style configuration file Franz Glasner <hg@dom66.de> parents: 94 diff changeset	34 An example is:
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file Franz Glasner <hg@dom66.de> parents: 94 diff changeset	35
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file Franz Glasner <hg@dom66.de> parents: 94 diff changeset	36 .. literalinclude:: ../tests/data/conf10.yml
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file Franz Glasner <hg@dom66.de> parents: 94 diff changeset	37 :language: yaml
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file Franz Glasner <hg@dom66.de> parents: 94 diff changeset	38
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file Franz Glasner <hg@dom66.de> parents: 94 diff changeset	39
122 21d92ff8cf31 Begin the handling of JSON-style configuration files Franz Glasner <hg@dom66.de> parents: 117 diff changeset	40 .. _json-files:
21d92ff8cf31 Begin the handling of JSON-style configuration files Franz Glasner <hg@dom66.de> parents: 117 diff changeset	41
21d92ff8cf31 Begin the handling of JSON-style configuration files Franz Glasner <hg@dom66.de> parents: 117 diff changeset	42 JSON files
21d92ff8cf31 Begin the handling of JSON-style configuration files Franz Glasner <hg@dom66.de> parents: 117 diff changeset	43 ----------
21d92ff8cf31 Begin the handling of JSON-style configuration files Franz Glasner <hg@dom66.de> parents: 117 diff changeset	44
131 b34ad08e7198 Document the JSON files Franz Glasner <hg@dom66.de> parents: 122 diff changeset	45 Read the JSON file with the help of Python's native :mod:`json` package.
b34ad08e7198 Document the JSON files Franz Glasner <hg@dom66.de> parents: 122 diff changeset	46
b34ad08e7198 Document the JSON files Franz Glasner <hg@dom66.de> parents: 122 diff changeset	47 .. note:: All strings are returned as Unicode text strings.
b34ad08e7198 Document the JSON files Franz Glasner <hg@dom66.de> parents: 122 diff changeset	48
134 2f2e819e8d17 Check the return type of the JSON and YAML loading functions: they must be a dict alike Franz Glasner <hg@dom66.de> parents: 133 diff changeset	49 .. note:: The root object must be an object and therefore decode
2f2e819e8d17 Check the return type of the JSON and YAML loading functions: they must be a dict alike Franz Glasner <hg@dom66.de> parents: 133 diff changeset	50 into a Python :class:`dict` alike. This is checked by the
2f2e819e8d17 Check the return type of the JSON and YAML loading functions: they must be a dict alike Franz Glasner <hg@dom66.de> parents: 133 diff changeset	51 implementation.
131 b34ad08e7198 Document the JSON files Franz Glasner <hg@dom66.de> parents: 122 diff changeset	52
b34ad08e7198 Document the JSON files Franz Glasner <hg@dom66.de> parents: 122 diff changeset	53 An example is:
b34ad08e7198 Document the JSON files Franz Glasner <hg@dom66.de> parents: 122 diff changeset	54
b34ad08e7198 Document the JSON files Franz Glasner <hg@dom66.de> parents: 122 diff changeset	55 .. literalinclude:: ../tests/data/conf10.json
b34ad08e7198 Document the JSON files Franz Glasner <hg@dom66.de> parents: 122 diff changeset	56 :language: js
122 21d92ff8cf31 Begin the handling of JSON-style configuration files Franz Glasner <hg@dom66.de> parents: 117 diff changeset	57
145 d44ee758e31b Some docu on comments in files Franz Glasner <hg@dom66.de> parents: 142 diff changeset	58 For comments in JSON files see section :ref:`comments`.
d44ee758e31b Some docu on comments in files Franz Glasner <hg@dom66.de> parents: 142 diff changeset	59
122 21d92ff8cf31 Begin the handling of JSON-style configuration files Franz Glasner <hg@dom66.de> parents: 117 diff changeset	60
94 2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	61 .. _ini-files:
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	62
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	63 INI Files
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	64 ---------
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	65
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	66 Read the file and all sections named in parameter `extract` are flattened
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	67 into the resulting dictionary. By default the section named ``config`` is
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	68 used.
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	69
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	70 Normally all values are returned as Unicode text strings.
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	71 But values can be annotated and therefore interpreted as other types:
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	72
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	73 ``:int:``
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	74 The value is handled in the same way as a Python :class:`int`
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	75 literal
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	76
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	77 ``:float:``
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	78 The value is interpreted as :class:`float`
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	79
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	80 ``:bool:``
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	81 The resulting value is a :class:`bool` where
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	82
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	83 ``1``, ``true``, ``yes``, ``on``
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	84 yield a Python ``True``
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	85
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	86 ``0``, ``false``, ``no``, ``off``
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	87 yield a Python ``False``
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	88
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	89 The evaluation is done case-insensitively.
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	90
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	91 .. note:: All strings are returned as Unicode text strings.
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	92
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	93 .. note:: Contrary to the behaviour of the standard Python :mod:`configparser`
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	94 module the INI file reader is case-sensitive.
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	95
97 1b4d95f60650 Build a tree-ish configuration from an INI style configuration file Franz Glasner <hg@dom66.de> parents: 94 diff changeset	96 The example INI style configuration below yields an equivalent
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file Franz Glasner <hg@dom66.de> parents: 94 diff changeset	97 configuration to the YAML configuration above:
94 2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	98
97 1b4d95f60650 Build a tree-ish configuration from an INI style configuration file Franz Glasner <hg@dom66.de> parents: 94 diff changeset	99 .. literalinclude:: ../tests/data/conf10.ini
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file Franz Glasner <hg@dom66.de> parents: 94 diff changeset	100 :language: ini
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file Franz Glasner <hg@dom66.de> parents: 94 diff changeset	101
133 05cb18c8697a FIX: Typo Franz Glasner <hg@dom66.de> parents: 132 diff changeset	102 As can be seen in this example -- INI file internal value interpolation
97 1b4d95f60650 Build a tree-ish configuration from an INI style configuration file Franz Glasner <hg@dom66.de> parents: 94 diff changeset	103 is done as in Python's standard :mod:`configparser` module.
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file Franz Glasner <hg@dom66.de> parents: 94 diff changeset	104
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file Franz Glasner <hg@dom66.de> parents: 94 diff changeset	105 This example also illustrates how INI sections are used to build a
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file Franz Glasner <hg@dom66.de> parents: 94 diff changeset	106 tree-ish configuration dictionary.
94 2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	107
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	108
195 28e6c1413947 Added support for TOML style configuration files Franz Glasner <fzglas.hg@dom66.de> parents: 194 diff changeset	109 .. _toml-files:
28e6c1413947 Added support for TOML style configuration files Franz Glasner <fzglas.hg@dom66.de> parents: 194 diff changeset	110
28e6c1413947 Added support for TOML style configuration files Franz Glasner <fzglas.hg@dom66.de> parents: 194 diff changeset	111 TOML Files
28e6c1413947 Added support for TOML style configuration files Franz Glasner <fzglas.hg@dom66.de> parents: 194 diff changeset	112 ----------
28e6c1413947 Added support for TOML style configuration files Franz Glasner <fzglas.hg@dom66.de> parents: 194 diff changeset	113
200 c6904d02beae Doc: some wording Franz Glasner <fzglas.hg@dom66.de> parents: 195 diff changeset	114 Read the TOML file with the help of the pure Python :mod:`toml`
c6904d02beae Doc: some wording Franz Glasner <fzglas.hg@dom66.de> parents: 195 diff changeset	115 package (https://github.com/uiri/toml) (e.g. ``pip install toml``).
195 28e6c1413947 Added support for TOML style configuration files Franz Glasner <fzglas.hg@dom66.de> parents: 194 diff changeset	116
28e6c1413947 Added support for TOML style configuration files Franz Glasner <fzglas.hg@dom66.de> parents: 194 diff changeset	117 All TOML features map seamingless to "ConfigMix".
28e6c1413947 Added support for TOML style configuration files Franz Glasner <fzglas.hg@dom66.de> parents: 194 diff changeset	118
28e6c1413947 Added support for TOML style configuration files Franz Glasner <fzglas.hg@dom66.de> parents: 194 diff changeset	119 The example TOML style configuration below yields an equivalent
28e6c1413947 Added support for TOML style configuration files Franz Glasner <fzglas.hg@dom66.de> parents: 194 diff changeset	120 configuration to the YAML configuration above:
28e6c1413947 Added support for TOML style configuration files Franz Glasner <fzglas.hg@dom66.de> parents: 194 diff changeset	121
28e6c1413947 Added support for TOML style configuration files Franz Glasner <fzglas.hg@dom66.de> parents: 194 diff changeset	122
28e6c1413947 Added support for TOML style configuration files Franz Glasner <fzglas.hg@dom66.de> parents: 194 diff changeset	123 .. literalinclude:: ../tests/data/conf10.toml
28e6c1413947 Added support for TOML style configuration files Franz Glasner <fzglas.hg@dom66.de> parents: 194 diff changeset	124 :language: ini
28e6c1413947 Added support for TOML style configuration files Franz Glasner <fzglas.hg@dom66.de> parents: 194 diff changeset	125
28e6c1413947 Added support for TOML style configuration files Franz Glasner <fzglas.hg@dom66.de> parents: 194 diff changeset	126
94 2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	127 .. _executable-python-scripts:
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	128
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	129 Executable Python Scripts
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	130 -------------------------
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	131
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	132 What will be exported:
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	133
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	134 1. If loading is done with the `extract` parameter only the given keys are
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	135 extracted from the script.
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	136
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	137 2. Otherwise it is checked if the scripts defines an ``__all__``
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	138 sequence. If there is one it's contents are the keys to be
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	139 extracted.
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	140
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	141 3. If there is no ``__all__`` object all names not starting with an
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	142 underscore ``_`` are found.
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	143
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	144 This is analogous to as Python modules behave when importing them with
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	145 ``from module import *``.
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	146
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	147 .. note:: The Python configuration files are evaluated with ``exec`` and not
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	148 imported.
97 1b4d95f60650 Build a tree-ish configuration from an INI style configuration file Franz Glasner <hg@dom66.de> parents: 94 diff changeset	149
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file Franz Glasner <hg@dom66.de> parents: 94 diff changeset	150 The example configuration by Python script below yields an equivalent
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file Franz Glasner <hg@dom66.de> parents: 94 diff changeset	151 configuration to the YAML configuration above:
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file Franz Glasner <hg@dom66.de> parents: 94 diff changeset	152
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file Franz Glasner <hg@dom66.de> parents: 94 diff changeset	153 .. literalinclude:: ../tests/data/conf10.py
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file Franz Glasner <hg@dom66.de> parents: 94 diff changeset	154 :language: python
114 aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	155
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	156
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	157 .. _loading-and-merging:
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	158
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	159 Loading and Merging
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	160 -------------------
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	161
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	162 Basic usage of the API is as follows in this example::
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	163
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	164 import configmix
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	165
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	166 #
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	167 # Note: With conf10 merging is rather pointless because the tree
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	168 # files # are really the same configuration. But is doesn't harm
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	169 # also here.
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	170 #
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	171 config = configmix.load("conf10.yml", "conf10.ini", "conf10.py")
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	172
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	173 # Get a -- possibly interpolated -- configuration variable's value
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	174 value1 = config.getvar_s("key1")
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	175
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	176 # Get a -- possibly interpolated -- variable from within the tree
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	177 value2 = config.getvar_s("tree1.tree2.key4")
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	178
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	179
139 c87b0dc54e1d Allow custom configuration filename extensions and custom loaders that can handle custom configuration file syntax styles Franz Glasner <hg@dom66.de> parents: 134 diff changeset	180 By default filenames of the configuration files must have the extensions
193 70c4f81ac58c FIX: Docu: Case-sensitivety of filename extension matching depends on the OS now Franz Glasner <fzglas.hg@dom66.de> parents: 190 diff changeset	181 (case-sensitivety depends on your OS):
114 aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	182
142 fc2bd73f9e98 Sort extension list in the docu Franz Glasner <hg@dom66.de> parents: 139 diff changeset	183 ``.ini``
fc2bd73f9e98 Sort extension list in the docu Franz Glasner <hg@dom66.de> parents: 139 diff changeset	184 for INI configuration files
fc2bd73f9e98 Sort extension list in the docu Franz Glasner <hg@dom66.de> parents: 139 diff changeset	185
fc2bd73f9e98 Sort extension list in the docu Franz Glasner <hg@dom66.de> parents: 139 diff changeset	186 ``.json``
fc2bd73f9e98 Sort extension list in the docu Franz Glasner <hg@dom66.de> parents: 139 diff changeset	187 for JSON configuration files
fc2bd73f9e98 Sort extension list in the docu Franz Glasner <hg@dom66.de> parents: 139 diff changeset	188
114 aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	189 ``.py``
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	190 for Python configuration files
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	191
195 28e6c1413947 Added support for TOML style configuration files Franz Glasner <fzglas.hg@dom66.de> parents: 194 diff changeset	192 ``.toml``
28e6c1413947 Added support for TOML style configuration files Franz Glasner <fzglas.hg@dom66.de> parents: 194 diff changeset	193 for TOML configuration file
28e6c1413947 Added support for TOML style configuration files Franz Glasner <fzglas.hg@dom66.de> parents: 194 diff changeset	194
114 aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	195 ``.yml`` or ``.yaml``
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	196 for YAML configuration files
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	197
115 a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	198
117 c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	199 .. _getting-values:
115 a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	200
117 c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	201 Getting configuration variables
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	202 -------------------------------
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	203
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	204 Get a -- possibly expanded -- configuration variable's value with::
115 a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	205
117 c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	206 value1 = config.getvar_s("key1")
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	207
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	208 Get a raw configuration variable's value with::
115 a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	209
117 c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	210 value1_raw = config.getvar("key1")
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	211
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	212 Because the configuration is not only a plain list of but a tree of
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	213 key-value pairs you will want to fetch them by separating the individual
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	214 level keys with a point ``.``.
115 a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	215
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	216 Looking at the example in chapter :ref:`yaml-files` -- when calling
117 c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	217 ``config.getvar_s("tree1.tree2.key4")`` you will get the value
115 a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	218 ``get this as `tree1.tree2.key4'``.
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	219
117 c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	220 This is true for both methods :py:meth:`.Configuration.getvar` and
115 a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	221 :py:meth:`.Configuration.getvar_s`.
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	222
117 c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	223 Both methods also perform :ref:`variable-expansion` and handle
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	224 :ref:`variable-namespaces`. Filtering is not supported. So -- the
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	225 variable name arguments of :py:meth:`.Configuration.getvar` and
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	226 :py:meth:`.Configuration.getvar_s` are of the form
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	227 ``[namespace:]variable``.
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	228
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	229
145 d44ee758e31b Some docu on comments in files Franz Glasner <hg@dom66.de> parents: 142 diff changeset	230 .. _comments:
d44ee758e31b Some docu on comments in files Franz Glasner <hg@dom66.de> parents: 142 diff changeset	231
d44ee758e31b Some docu on comments in files Franz Glasner <hg@dom66.de> parents: 142 diff changeset	232 Comments
d44ee758e31b Some docu on comments in files Franz Glasner <hg@dom66.de> parents: 142 diff changeset	233 --------
d44ee758e31b Some docu on comments in files Franz Glasner <hg@dom66.de> parents: 142 diff changeset	234
d44ee758e31b Some docu on comments in files Franz Glasner <hg@dom66.de> parents: 142 diff changeset	235 By default all keys beginning with ``__comment`` or ``__doc`` are
d44ee758e31b Some docu on comments in files Franz Glasner <hg@dom66.de> parents: 142 diff changeset	236 filtered out and not given to the application. This allows comments in
d44ee758e31b Some docu on comments in files Franz Glasner <hg@dom66.de> parents: 142 diff changeset	237 JSON files -- but is not restricted to JSON files only.
d44ee758e31b Some docu on comments in files Franz Glasner <hg@dom66.de> parents: 142 diff changeset	238
d44ee758e31b Some docu on comments in files Franz Glasner <hg@dom66.de> parents: 142 diff changeset	239 For all types of configuration files their respective standard comments
d44ee758e31b Some docu on comments in files Franz Glasner <hg@dom66.de> parents: 142 diff changeset	240 are allowed too.
d44ee758e31b Some docu on comments in files Franz Glasner <hg@dom66.de> parents: 142 diff changeset	241
d44ee758e31b Some docu on comments in files Franz Glasner <hg@dom66.de> parents: 142 diff changeset	242
117 c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	243 .. _variable-namespaces:
115 a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	244
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	245 Variable Namespaces
117 c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	246 -------------------
115 a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	247
117 c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	248 Currently there are 4 namespaces:
115 a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	249
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	250 1. The unnamed namespace (which is also default).
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	251
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	252 All the configuration variables are part of this namespace.
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	253
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	254 2. The namespace ``OS``
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	255
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	256 Available functions:
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	257
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	258 ``cwd``
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	259 Contains the current working directory of the process
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	260
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	261 3. The namespace ``ENV``
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	262
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	263 This namespace contains all the environment variables as they are
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	264 available from :py:data:`os.environ`.
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	265
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	266 4. The namespace ``PY``
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	267
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	268 Contains selected values from the running Python:
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	269
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	270 ``version``
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	271 The return value of :py:func:`platform.python_version`
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	272
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	273 ``version_maj_min``
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	274 Just the major and minor version of the running Python
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	275 (``.`` separated)
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	276
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	277 ``version_maj``
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	278 Just the major version of the running Python
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	279
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	280 ``implementation``
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	281 The return value of :py:func:`platform.python_implementation`
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	282
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	283
117 c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	284 Examples
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	285 ~~~~~~~~
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	286
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	287 ::
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	288
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	289 config.getvar("OS:cwd")
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	290
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	291 yields the current working directory as :py:func:`os.getcwd` does.
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	292
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	293
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	294 .. _variable-expansion:
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	295
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	296 Variable Expansion
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	297 ------------------
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	298
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	299 Configuration variable values that are read with
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	300 :py:meth:`.Configuration.getvar_s` are subject to variable
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	301 expansion. The general syntactic pattern for this is::
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	302
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	303 {{[namespace:]variable[\|filter[\|filter...]]}}
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	304
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	305 I.e.: between double curly braces an optional `namespace` name followed by
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	306 a colon ``:``, the `variable` and then zero or more filters, each one
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	307 introduced by a pipe symbol ``\|``.
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	308
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	309 Variables are expanded lately at runtime -- exactly when calling
158 ab6a48ff5235 FIX: Docu: Configuration.getvar() does not apply variable substitutions Franz Glasner <fzglas.hg@dom66.de> parents: 145 diff changeset	310 :py:meth:`.Configuration.getvar_s`,
ab6a48ff5235 FIX: Docu: Configuration.getvar() does not apply variable substitutions Franz Glasner <fzglas.hg@dom66.de> parents: 145 diff changeset	311 :py:meth:`.Configuration.substitute_variables_in_obj` or
ab6a48ff5235 FIX: Docu: Configuration.getvar() does not apply variable substitutions Franz Glasner <fzglas.hg@dom66.de> parents: 145 diff changeset	312 :py:meth:`.Configuration.expand_variable`
117 c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	313
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	314
115 a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	315 Filter functions
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	316 ~~~~~~~~~~~~~~~~
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	317
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	318 Interpolated values can be processed through a series of filter functions::
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	319
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	320 {{my.variable\|filter1\|filter2}}
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	321
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	322 Available filter functions are:
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	323
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	324 ``urlquote``
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	325
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	326 ``saslprep``
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	327
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	328 ``normpath``
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	329
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	330 ``abspath``
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	331
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	332 ``posixpath``
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	333
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	334 ``lower``
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	335
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	336 ``upper``
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	337
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	338
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	339 Examples
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	340 ~~~~~~~~
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	341
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	342 ::
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	343
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	344 {{OS:cwd\|posixpath}}
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	345
117 c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	346 expands to the current working directory as POSIX path: on Windows all
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	347 backslashes are replaced by forward slashes.
115 a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	348
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	349 ::
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	350
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	351 {{ENV:PATH}}
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	352
117 c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	353 expands to the current search path from the process environment.
115 a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	354
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	355 ::
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	356
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	357 {{PY:version}}
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	358
117 c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	359 expands to the current running Python version (e.g. ``3.6.4``).
115 a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	360
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	361 ::
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	362
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	363 {{PY::implementation\|upper}}
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	364
117 c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	365 expands to something like ``CPYTHON`` when using the standard Python
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	366 interpreter written in C.
139 c87b0dc54e1d Allow custom configuration filename extensions and custom loaders that can handle custom configuration file syntax styles Franz Glasner <hg@dom66.de> parents: 134 diff changeset	367
c87b0dc54e1d Allow custom configuration filename extensions and custom loaders that can handle custom configuration file syntax styles Franz Glasner <hg@dom66.de> parents: 134 diff changeset	368
c87b0dc54e1d Allow custom configuration filename extensions and custom loaders that can handle custom configuration file syntax styles Franz Glasner <hg@dom66.de> parents: 134 diff changeset	369 Custom filename extensions and custom loaders
c87b0dc54e1d Allow custom configuration filename extensions and custom loaders that can handle custom configuration file syntax styles Franz Glasner <hg@dom66.de> parents: 134 diff changeset	370 ---------------------------------------------
c87b0dc54e1d Allow custom configuration filename extensions and custom loaders that can handle custom configuration file syntax styles Franz Glasner <hg@dom66.de> parents: 134 diff changeset	371
c87b0dc54e1d Allow custom configuration filename extensions and custom loaders that can handle custom configuration file syntax styles Franz Glasner <hg@dom66.de> parents: 134 diff changeset	372 If you want to have custom configuration file extensions and/or custom loaders
c87b0dc54e1d Allow custom configuration filename extensions and custom loaders that can handle custom configuration file syntax styles Franz Glasner <hg@dom66.de> parents: 134 diff changeset	373 for custom configuration files you have various possibilities:
c87b0dc54e1d Allow custom configuration filename extensions and custom loaders that can handle custom configuration file syntax styles Franz Glasner <hg@dom66.de> parents: 134 diff changeset	374
c87b0dc54e1d Allow custom configuration filename extensions and custom loaders that can handle custom configuration file syntax styles Franz Glasner <hg@dom66.de> parents: 134 diff changeset	375 Associate an additional new extension (e.g. ".conf") with an
c87b0dc54e1d Allow custom configuration filename extensions and custom loaders that can handle custom configuration file syntax styles Franz Glasner <hg@dom66.de> parents: 134 diff changeset	376 existing configuration file style (e.g. YAML)::
c87b0dc54e1d Allow custom configuration filename extensions and custom loaders that can handle custom configuration file syntax styles Franz Glasner <hg@dom66.de> parents: 134 diff changeset	377
190 3d273eb13565 Doc: Adjust the example in the introduction to the new custom association style Franz Glasner <fzglas.hg@dom66.de> parents: 171 diff changeset	378 configmix.set_assoc(".conf", configmix.get_assoc(".yml"))
139 c87b0dc54e1d Allow custom configuration filename extensions and custom loaders that can handle custom configuration file syntax styles Franz Glasner <hg@dom66.de> parents: 134 diff changeset	379
171 1ff11462a5c1 The associations from filename extensions to parsers are "fnmatch" style patterns now. Franz Glasner <f.glasner@feldmann-mg.com> parents: 161 diff changeset	380 Allow only files with extension ".cfg" in INI-style -- using the default
1ff11462a5c1 The associations from filename extensions to parsers are "fnmatch" style patterns now. Franz Glasner <f.glasner@feldmann-mg.com> parents: 161 diff changeset	381 loader for INI-files::
139 c87b0dc54e1d Allow custom configuration filename extensions and custom loaders that can handle custom configuration file syntax styles Franz Glasner <hg@dom66.de> parents: 134 diff changeset	382
190 3d273eb13565 Doc: Adjust the example in the introduction to the new custom association style Franz Glasner <fzglas.hg@dom66.de> parents: 171 diff changeset	383 configmix.clear_assoc()
3d273eb13565 Doc: Adjust the example in the introduction to the new custom association style Franz Glasner <fzglas.hg@dom66.de> parents: 171 diff changeset	384 configmix.set_assoc(".cfg", configmix.get_default_assoc(".ini"))
139 c87b0dc54e1d Allow custom configuration filename extensions and custom loaders that can handle custom configuration file syntax styles Franz Glasner <hg@dom66.de> parents: 134 diff changeset	385
194 0d8dd58afc44 Docu: Enhanced the custom loader section somewhat Franz Glasner <fzglas.hg@dom66.de> parents: 193 diff changeset	386 Only a new configuration file style::
139 c87b0dc54e1d Allow custom configuration filename extensions and custom loaders that can handle custom configuration file syntax styles Franz Glasner <hg@dom66.de> parents: 134 diff changeset	387
c87b0dc54e1d Allow custom configuration filename extensions and custom loaders that can handle custom configuration file syntax styles Franz Glasner <hg@dom66.de> parents: 134 diff changeset	388 def my_custom_loader(filename):
c87b0dc54e1d Allow custom configuration filename extensions and custom loaders that can handle custom configuration file syntax styles Franz Glasner <hg@dom66.de> parents: 134 diff changeset	389 ...
c87b0dc54e1d Allow custom configuration filename extensions and custom loaders that can handle custom configuration file syntax styles Franz Glasner <hg@dom66.de> parents: 134 diff changeset	390 return some_dict_alike
c87b0dc54e1d Allow custom configuration filename extensions and custom loaders that can handle custom configuration file syntax styles Franz Glasner <hg@dom66.de> parents: 134 diff changeset	391
190 3d273eb13565 Doc: Adjust the example in the introduction to the new custom association style Franz Glasner <fzglas.hg@dom66.de> parents: 171 diff changeset	392 configmix.mode_loaders["myconfmode"] = my_custom_loader
3d273eb13565 Doc: Adjust the example in the introduction to the new custom association style Franz Glasner <fzglas.hg@dom66.de> parents: 171 diff changeset	393 configmix.clear_assoc()
3d273eb13565 Doc: Adjust the example in the introduction to the new custom association style Franz Glasner <fzglas.hg@dom66.de> parents: 171 diff changeset	394 configmix.set_assoc("*.my.configuration", "myconfmode")
194 0d8dd58afc44 Docu: Enhanced the custom loader section somewhat Franz Glasner <fzglas.hg@dom66.de> parents: 193 diff changeset	395
0d8dd58afc44 Docu: Enhanced the custom loader section somewhat Franz Glasner <fzglas.hg@dom66.de> parents: 193 diff changeset	396 If :py:func:`~configmix.clear_assoc` will not be called then just a new
0d8dd58afc44 Docu: Enhanced the custom loader section somewhat Franz Glasner <fzglas.hg@dom66.de> parents: 193 diff changeset	397 configuration file style will be installed.

Mercurial > hgrepos > Python > libs > ConfigMix

annotate doc/introduction.rst @ 200:c6904d02beae