Mercurial > hgrepos > Python > libs > ConfigMix

annotate doc/introduction.rst @ 199:852f6c0c9298

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Need a PyYAML version < 4. PyYAML 5 is out -- which dropped support for Python 2.6. Because we support Python 2.6 stay at version 3.
author Franz Glasner <fzglas.hg@dom66.de>
date Sat, 04 May 2019 14:23:09 +0200
parents 28e6c1413947
children c6904d02beae
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
25 Need the :mod:`yaml` package (e.g. ``pip install pyyaml``)
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
26
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
27 .. note:: All strings are returned as Unicode text strings.
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
28
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
29 .. 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
30 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
31 implementation.
94
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
32
97
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents: 94
diff changeset
33 An example is:
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents: 94
diff changeset
34
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents: 94
diff changeset
35 .. 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
36 :language: yaml
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents: 94
diff changeset
37
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents: 94
diff changeset
38
122
21d92ff8cf31 Begin the handling of JSON-style configuration files
Franz Glasner <hg@dom66.de>
parents: 117
diff changeset
39 .. _json-files:
21d92ff8cf31 Begin the handling of JSON-style configuration files
Franz Glasner <hg@dom66.de>
parents: 117
diff changeset
40
21d92ff8cf31 Begin the handling of JSON-style configuration files
Franz Glasner <hg@dom66.de>
parents: 117
diff changeset
41 JSON files
21d92ff8cf31 Begin the handling of JSON-style configuration files
Franz Glasner <hg@dom66.de>
parents: 117
diff changeset
42 ----------
21d92ff8cf31 Begin the handling of JSON-style configuration files
Franz Glasner <hg@dom66.de>
parents: 117
diff changeset
43
131
b34ad08e7198 Document the JSON files
Franz Glasner <hg@dom66.de>
parents: 122
diff changeset
44 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
45
b34ad08e7198 Document the JSON files
Franz Glasner <hg@dom66.de>
parents: 122
diff changeset
46 .. note:: All strings are returned as Unicode text strings.
b34ad08e7198 Document the JSON files
Franz Glasner <hg@dom66.de>
parents: 122
diff changeset
47
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
48 .. 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
49 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
50 implementation.
131
b34ad08e7198 Document the JSON files
Franz Glasner <hg@dom66.de>
parents: 122
diff changeset
51
b34ad08e7198 Document the JSON files
Franz Glasner <hg@dom66.de>
parents: 122
diff changeset
52 An example is:
b34ad08e7198 Document the JSON files
Franz Glasner <hg@dom66.de>
parents: 122
diff changeset
53
b34ad08e7198 Document the JSON files
Franz Glasner <hg@dom66.de>
parents: 122
diff changeset
54 .. literalinclude:: ../tests/data/conf10.json
b34ad08e7198 Document the JSON files
Franz Glasner <hg@dom66.de>
parents: 122
diff changeset
55 :language: js
122
21d92ff8cf31 Begin the handling of JSON-style configuration files
Franz Glasner <hg@dom66.de>
parents: 117
diff changeset
56
145
d44ee758e31b Some docu on comments in files
Franz Glasner <hg@dom66.de>
parents: 142
diff changeset
57 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
58
122
21d92ff8cf31 Begin the handling of JSON-style configuration files
Franz Glasner <hg@dom66.de>
parents: 117
diff changeset
59
94
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
60 .. _ini-files:
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
61
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
62 INI Files
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
63 ---------
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 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
66 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
67 used.
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
68
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
69 Normally all values are returned as Unicode text strings.
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
70 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
71
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
72 ``:int:``
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
73 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
74 literal
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
75
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
76 ``:float:``
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
77 The value is interpreted as :class:`float`
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
78
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
79 ``:bool:``
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
80 The resulting value is a :class:`bool` where
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
81
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
82 ``1``, ``true``, ``yes``, ``on``
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
83 yield a Python ``True``
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
84
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
85 ``0``, ``false``, ``no``, ``off``
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
86 yield a Python ``False``
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
87
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
88 The evaluation is done *case-insensitively*.
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
89
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
90 .. note:: All strings are returned as Unicode text strings.
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
91
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
92 .. 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
93 module the INI file reader is *case-sensitive*.
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
94
97
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents: 94
diff changeset
95 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
96 configuration to the YAML configuration above:
94
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
97
97
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents: 94
diff changeset
98 .. 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
99 :language: ini
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents: 94
diff changeset
100
133
05cb18c8697a FIX: Typo
Franz Glasner <hg@dom66.de>
parents: 132
diff changeset
101 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
102 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
103
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents: 94
diff changeset
104 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
105 tree-ish configuration dictionary.
94
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
106
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
107
195
28e6c1413947 Added support for TOML style configuration files
Franz Glasner <fzglas.hg@dom66.de>
parents: 194
diff changeset
108 .. _toml-files:
28e6c1413947 Added support for TOML style configuration files
Franz Glasner <fzglas.hg@dom66.de>
parents: 194
diff changeset
109
28e6c1413947 Added support for TOML style configuration files
Franz Glasner <fzglas.hg@dom66.de>
parents: 194
diff changeset
110 TOML Files
28e6c1413947 Added support for TOML style configuration files
Franz Glasner <fzglas.hg@dom66.de>
parents: 194
diff changeset
111 ----------
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 Read the TOML file with the help of the pure Python `uiri/toml` package.
28e6c1413947 Added support for TOML style configuration files
Franz Glasner <fzglas.hg@dom66.de>
parents: 194
diff changeset
114
28e6c1413947 Added support for TOML style configuration files
Franz Glasner <fzglas.hg@dom66.de>
parents: 194
diff changeset
115 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
116
28e6c1413947 Added support for TOML style configuration files
Franz Glasner <fzglas.hg@dom66.de>
parents: 194
diff changeset
117 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
118 configuration to the YAML configuration above:
28e6c1413947 Added support for TOML style configuration files
Franz Glasner <fzglas.hg@dom66.de>
parents: 194
diff changeset
119
28e6c1413947 Added support for TOML style configuration files
Franz Glasner <fzglas.hg@dom66.de>
parents: 194
diff changeset
120
28e6c1413947 Added support for TOML style configuration files
Franz Glasner <fzglas.hg@dom66.de>
parents: 194
diff changeset
121 .. literalinclude:: ../tests/data/conf10.toml
28e6c1413947 Added support for TOML style configuration files
Franz Glasner <fzglas.hg@dom66.de>
parents: 194
diff changeset
122 :language: ini
28e6c1413947 Added support for TOML style configuration files
Franz Glasner <fzglas.hg@dom66.de>
parents: 194
diff changeset
123
28e6c1413947 Added support for TOML style configuration files
Franz Glasner <fzglas.hg@dom66.de>
parents: 194
diff changeset
124
94
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
125 .. _executable-python-scripts:
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
126
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
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
130 What will be exported:
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 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
133 extracted from the script.
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
134
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
135 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
136 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
137 extracted.
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
138
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
139 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
140 underscore ``_`` are found.
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
141
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
142 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
143 ``from module import *``.
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
144
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
145 .. 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
146 imported.
97
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents: 94
diff changeset
147
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents: 94
diff changeset
148 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
149 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
150
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents: 94
diff changeset
151 .. 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
152 :language: python
114
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
153
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
154
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
155 .. _loading-and-merging:
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
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
160 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
161
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
162 import configmix
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 #
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
165 # 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
166 # 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
167 # also here.
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
168 #
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
169 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
170
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
171 # 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
172 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
173
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
174 # 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
175 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
176
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
177
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
178 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
179 (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
180
142
fc2bd73f9e98 Sort extension list in the docu
Franz Glasner <hg@dom66.de>
parents: 139
diff changeset
181 ``.ini``
fc2bd73f9e98 Sort extension list in the docu
Franz Glasner <hg@dom66.de>
parents: 139
diff changeset
182 for INI configuration files
fc2bd73f9e98 Sort extension list in the docu
Franz Glasner <hg@dom66.de>
parents: 139
diff changeset
183
fc2bd73f9e98 Sort extension list in the docu
Franz Glasner <hg@dom66.de>
parents: 139
diff changeset
184 ``.json``
fc2bd73f9e98 Sort extension list in the docu
Franz Glasner <hg@dom66.de>
parents: 139
diff changeset
185 for JSON configuration files
fc2bd73f9e98 Sort extension list in the docu
Franz Glasner <hg@dom66.de>
parents: 139
diff changeset
186
114
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
187 ``.py``
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
188 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
189
195
28e6c1413947 Added support for TOML style configuration files
Franz Glasner <fzglas.hg@dom66.de>
parents: 194
diff changeset
190 ``.toml``
28e6c1413947 Added support for TOML style configuration files
Franz Glasner <fzglas.hg@dom66.de>
parents: 194
diff changeset
191 for TOML configuration file
28e6c1413947 Added support for TOML style configuration files
Franz Glasner <fzglas.hg@dom66.de>
parents: 194
diff changeset
192
114
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
193 ``.yml`` or ``.yaml``
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
194 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
195
115
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
196
117
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
197 .. _getting-values:
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 configuration variables
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
200 -------------------------------
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
201
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
202 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
203
117
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
204 value1 = config.getvar_s("key1")
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
205
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
206 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
207
117
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
208 value1_raw = config.getvar("key1")
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
209
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
210 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
211 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
212 level keys with a point ``.``.
115
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
213
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
214 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
215 ``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
216 ``get this as `tree1.tree2.key4'``.
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
217
117
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
218 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
219 :py:meth:`.Configuration.getvar_s`.
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
220
117
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
221 Both methods also perform :ref:`variable-expansion` and handle
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
222 :ref:`variable-namespaces`. Filtering is not supported. So -- the
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
223 variable name arguments of :py:meth:`.Configuration.getvar` and
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
224 :py:meth:`.Configuration.getvar_s` are of the form
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
225 ``[namespace:]variable``.
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
226
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
227
145
d44ee758e31b Some docu on comments in files
Franz Glasner <hg@dom66.de>
parents: 142
diff changeset
228 .. _comments:
d44ee758e31b Some docu on comments in files
Franz Glasner <hg@dom66.de>
parents: 142
diff changeset
229
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
d44ee758e31b Some docu on comments in files
Franz Glasner <hg@dom66.de>
parents: 142
diff changeset
233 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
234 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
235 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
236
d44ee758e31b Some docu on comments in files
Franz Glasner <hg@dom66.de>
parents: 142
diff changeset
237 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
238 are allowed too.
d44ee758e31b Some docu on comments in files
Franz Glasner <hg@dom66.de>
parents: 142
diff changeset
239
d44ee758e31b Some docu on comments in files
Franz Glasner <hg@dom66.de>
parents: 142
diff changeset
240
117
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
241 .. _variable-namespaces:
115
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
242
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
243 Variable Namespaces
117
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
244 -------------------
115
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
245
117
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
246 Currently there are 4 namespaces:
115
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
247
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
248 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
249
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
250 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
251
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
252 2. The namespace ``OS``
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 Available functions:
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 ``cwd``
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
257 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
258
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
259 3. The namespace ``ENV``
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 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
262 available from :py:data:`os.environ`.
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
263
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
264 4. The namespace ``PY``
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 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
267
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
268 ``version``
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
269 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
270
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
271 ``version_maj_min``
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
272 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
273 (``.`` separated)
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
274
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
275 ``version_maj``
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
276 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
277
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
278 ``implementation``
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
279 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
280
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
281
117
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
282 Examples
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
283 ~~~~~~~~
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
284
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 config.getvar("OS:cwd")
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 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
290
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
291
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
292 .. _variable-expansion:
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
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
297 Configuration variable values that are read with
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
298 :py:meth:`.Configuration.getvar_s` are subject to variable
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
299 expansion. The general syntactic pattern for this is::
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
300
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
301 {{[namespace:]variable[|filter[|filter...]]}}
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 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
304 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
305 introduced by a pipe symbol ``|``.
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
306
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
307 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
308 :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
309 :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
310 :py:meth:`.Configuration.expand_variable`
117
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
311
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
312
115
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
313 Filter functions
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
314 ~~~~~~~~~~~~~~~~
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
315
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
316 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
317
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
318 {{my.variable|filter1|filter2}}
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 Available filter functions are:
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 ``urlquote``
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 ``saslprep``
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 ``normpath``
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 ``abspath``
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 ``posixpath``
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 ``lower``
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 ``upper``
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
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
337 Examples
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
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 {{OS:cwd|posixpath}}
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
343
117
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
344 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
345 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
346
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
347 ::
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 {{ENV:PATH}}
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
350
117
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
351 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
352
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
353 ::
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 {{PY:version}}
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
356
117
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
357 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
358
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
359 ::
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 {{PY::implementation|upper}}
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
362
117
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
363 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
364 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
365
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
366
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 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
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
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 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
371 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
372
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 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
374 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
375
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
376 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
377
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
378 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
379 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
380
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
381 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
382 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
383
194
0d8dd58afc44 Docu: Enhanced the custom loader section somewhat
Franz Glasner <fzglas.hg@dom66.de>
parents: 193
diff changeset
384 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
385
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
386 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
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 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
389
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
390 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
391 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
392 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
393
0d8dd58afc44 Docu: Enhanced the custom loader section somewhat
Franz Glasner <fzglas.hg@dom66.de>
parents: 193
diff changeset
394 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
395 configuration file style will be installed.