Mercurial > hgrepos > Python > libs > ConfigMix
annotate docs/introduction.rst @ 428:090a25f36a3d
FIX: Allow jailed configurations to use correctly use base configurations that use a different "default" marker object.
Jailed configurations assumed that their "default" marker object is
identical to the "default" marker object in the unjailed base
configuration. This is not always true, especially if
"_JailedConfiguration.rebind()" is used.
Removed the explicit "default" keyword argument and passed the complete
keywords argument dictionary to the base instead. This triggers correct
default handling in the base.
| author | Franz Glasner <f.glasner@feldmann-mg.com> |
|---|---|
| date | Thu, 09 Dec 2021 13:02:17 +0100 |
| parents | 84d4f82ffe59 |
| children | 6102b767fc69 |
| rev | line source |
|---|---|
| 94 | 1 .. -*- coding: utf-8; indent-tabs-mode: nil; -*- |
| 2 | |
| 3 .. _introduction: | |
| 4 | |
| 5 Introduction | |
| 6 ============ | |
| 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 | 11 The configurations can be read from different types of files: |
| 12 | |
| 13 - :ref:`YAML files <yaml-files>` | |
| 131 | 14 - :ref:`JSON files <json-files>` |
| 94 | 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 | 17 - :ref:`executable Python scripts <executable-python-scripts>` |
| 18 | |
| 19 | |
| 20 .. _yaml-files: | |
| 21 | |
| 22 YAML Files | |
| 23 ---------- | |
| 24 | |
| 200 | 25 Need the :mod:`yaml` package (https://github.com/yaml/pyyaml) |
| 26 (e.g. ``pip install pyyaml``) | |
| 94 | 27 |
| 28 .. note:: All strings are returned as Unicode text strings. | |
| 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 | 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 | 45 Read the JSON file with the help of Python's native :mod:`json` package. |
| 46 | |
| 47 .. note:: All strings are returned as Unicode text strings. | |
| 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 | 52 |
| 53 An example is: | |
| 54 | |
| 55 .. literalinclude:: ../tests/data/conf10.json | |
| 56 :language: js | |
|
122
21d92ff8cf31
Begin the handling of JSON-style configuration files
Franz Glasner <hg@dom66.de>
parents:
117
diff
changeset
|
57 |
| 145 | 58 For comments in JSON files see section :ref:`comments`. |
| 59 | |
|
122
21d92ff8cf31
Begin the handling of JSON-style configuration files
Franz Glasner <hg@dom66.de>
parents:
117
diff
changeset
|
60 |
| 94 | 61 .. _ini-files: |
| 62 | |
| 63 INI Files | |
| 64 --------- | |
| 65 | |
| 66 Read the file and all sections named in parameter `extract` are flattened | |
| 67 into the resulting dictionary. By default the section named ``config`` is | |
|
300
28aa21095a68
Docs: "config" is the default **root** section
Franz Glasner <fzglas.hg@dom66.de>
parents:
282
diff
changeset
|
68 used as root section. |
| 94 | 69 |
| 70 Normally all values are returned as Unicode text strings. | |
| 71 But values can be annotated and therefore interpreted as other types: | |
| 72 | |
| 73 ``:int:`` | |
| 74 The value is handled in the same way as a Python :class:`int` | |
| 75 literal | |
| 76 | |
| 77 ``:float:`` | |
| 78 The value is interpreted as :class:`float` | |
| 79 | |
| 80 ``:bool:`` | |
| 81 The resulting value is a :class:`bool` where | |
| 82 | |
| 83 ``1``, ``true``, ``yes``, ``on`` | |
| 84 yield a Python ``True`` | |
| 85 | |
| 86 ``0``, ``false``, ``no``, ``off`` | |
| 87 yield a Python ``False`` | |
| 88 | |
| 89 The evaluation is done *case-insensitively*. | |
| 90 | |
| 91 .. note:: All strings are returned as Unicode text strings. | |
| 92 | |
| 93 .. note:: Contrary to the behaviour of the standard Python :mod:`configparser` | |
| 94 module the INI file reader is *case-sensitive*. | |
| 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 | 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 | 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 | 107 |
| 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 | 114 Read the TOML file with the help of the pure Python :mod:`toml` |
| 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 | 127 .. _executable-python-scripts: |
| 128 | |
| 129 Executable Python Scripts | |
| 130 ------------------------- | |
| 131 | |
| 132 What will be exported: | |
| 133 | |
| 134 1. If loading is done with the `extract` parameter only the given keys are | |
| 135 extracted from the script. | |
| 136 | |
| 137 2. Otherwise it is checked if the scripts defines an ``__all__`` | |
| 138 sequence. If there is one it's contents are the keys to be | |
| 139 extracted. | |
| 140 | |
| 141 3. If there is no ``__all__`` object all names not starting with an | |
| 142 underscore ``_`` are found. | |
| 143 | |
| 144 This is analogous to as Python modules behave when importing them with | |
| 145 ``from module import *``. | |
| 146 | |
| 147 .. note:: The Python configuration files are evaluated with ``exec`` and not | |
| 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 |
|
315
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
204 Get a -- possibly interpolated -- 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") |
|
315
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
207 value2 = config.getvar_s("key1.subkey2") |
|
117
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
208 |
|
315
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
209 or equivalently with :: |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
210 |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
211 value1 = config.getvarl_s("key1") |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
212 value2 = config.getvarl_s("key1", "subkey2") |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
213 |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
214 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
|
215 |
|
117
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
216 value1_raw = config.getvar("key1") |
|
315
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
217 value2_raw = config.getvarl("key1.subkey2") |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
218 |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
219 or equivalently with :: |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
220 |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
221 value1_raw = config.getvarl("key1") |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
222 value2_raw = config.getvarl("key1", "subkey2") |
|
117
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
223 |
|
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
224 Because the configuration is not only a plain list of but a tree of |
|
315
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
225 key-value pairs you will want to fetch a nested configuration value |
|
375
baedd2031074
Docs: Introduce the newly introduces access methods
Franz Glasner <fzglas.hg@dom66.de>
parents:
354
diff
changeset
|
226 using two access basic methods: |
|
315
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
227 |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
228 :py:meth:`.Configuration.getvar` and :py:meth:`.Configuration.getvar_s` |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
229 |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
230 Use a single key variable where the invidual level keys are joined |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
231 using a dot (``.``) |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
232 |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
233 :py:meth:`.Configuration.getvarl` and :py:meth:`.Configuration.getvarl_s` |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
234 |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
235 Use just positional Python arguments for each level key |
|
115
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
236 |
|
375
baedd2031074
Docs: Introduce the newly introduces access methods
Franz Glasner <fzglas.hg@dom66.de>
parents:
354
diff
changeset
|
237 Also there exist variants of the basic access methods that coerce |
|
baedd2031074
Docs: Introduce the newly introduces access methods
Franz Glasner <fzglas.hg@dom66.de>
parents:
354
diff
changeset
|
238 returned variables into :py:class:`int` or :py:class:`bool` types |
|
baedd2031074
Docs: Introduce the newly introduces access methods
Franz Glasner <fzglas.hg@dom66.de>
parents:
354
diff
changeset
|
239 (:py:meth:`.Configuration.getintvar_s`, |
|
baedd2031074
Docs: Introduce the newly introduces access methods
Franz Glasner <fzglas.hg@dom66.de>
parents:
354
diff
changeset
|
240 :py:meth:`.Configuration.getboolvar_s`) |
|
baedd2031074
Docs: Introduce the newly introduces access methods
Franz Glasner <fzglas.hg@dom66.de>
parents:
354
diff
changeset
|
241 |
|
baedd2031074
Docs: Introduce the newly introduces access methods
Franz Glasner <fzglas.hg@dom66.de>
parents:
354
diff
changeset
|
242 And with :py:meth:`.Configuration.getfirstvar`, |
|
baedd2031074
Docs: Introduce the newly introduces access methods
Franz Glasner <fzglas.hg@dom66.de>
parents:
354
diff
changeset
|
243 :py:meth:`.Configuration.getfirstvar_s`, |
| 400 | 244 :py:meth:`.Configuration.getfirstintvar_s`, |
|
386
d7dcd76c262a
Add Configuration.getfirstfloatvar_s() to the introduction
Franz Glasner <fzglas.hg@dom66.de>
parents:
375
diff
changeset
|
245 :py:meth:`.Configuration.getfirstboolvar_s` and |
|
d7dcd76c262a
Add Configuration.getfirstfloatvar_s() to the introduction
Franz Glasner <fzglas.hg@dom66.de>
parents:
375
diff
changeset
|
246 :py:meth:`.Configuration.getfirstfloatvar_s` there exist variants that |
|
375
baedd2031074
Docs: Introduce the newly introduces access methods
Franz Glasner <fzglas.hg@dom66.de>
parents:
354
diff
changeset
|
247 accept a *list* of possible variables names and return the first one |
|
baedd2031074
Docs: Introduce the newly introduces access methods
Franz Glasner <fzglas.hg@dom66.de>
parents:
354
diff
changeset
|
248 that is found. |
|
baedd2031074
Docs: Introduce the newly introduces access methods
Franz Glasner <fzglas.hg@dom66.de>
parents:
354
diff
changeset
|
249 |
|
387
b2c0550d5a44
Docs: minimal introduction for getfirstXXXl_s variants
Franz Glasner <fzglas.hg@dom66.de>
parents:
386
diff
changeset
|
250 And again --- with :py:meth:`.Configuration.getfirstvarl`, |
|
b2c0550d5a44
Docs: minimal introduction for getfirstXXXl_s variants
Franz Glasner <fzglas.hg@dom66.de>
parents:
386
diff
changeset
|
251 :py:meth:`.Configuration.getfirstvarl_s`, |
|
b2c0550d5a44
Docs: minimal introduction for getfirstXXXl_s variants
Franz Glasner <fzglas.hg@dom66.de>
parents:
386
diff
changeset
|
252 :py:meth:`.Configuration.getfirstintvarl_s`, |
|
b2c0550d5a44
Docs: minimal introduction for getfirstXXXl_s variants
Franz Glasner <fzglas.hg@dom66.de>
parents:
386
diff
changeset
|
253 :py:meth:`.Configuration.getfirstboolvarl_s` and |
|
b2c0550d5a44
Docs: minimal introduction for getfirstXXXl_s variants
Franz Glasner <fzglas.hg@dom66.de>
parents:
386
diff
changeset
|
254 :py:meth:`.Configuration.getfirstfloatvarl_s` there exist variants |
|
b2c0550d5a44
Docs: minimal introduction for getfirstXXXl_s variants
Franz Glasner <fzglas.hg@dom66.de>
parents:
386
diff
changeset
|
255 that accept a *list* of lists or tuples or dicts that describe |
|
b2c0550d5a44
Docs: minimal introduction for getfirstXXXl_s variants
Franz Glasner <fzglas.hg@dom66.de>
parents:
386
diff
changeset
|
256 possible variables names and return the first one that is found. |
|
b2c0550d5a44
Docs: minimal introduction for getfirstXXXl_s variants
Franz Glasner <fzglas.hg@dom66.de>
parents:
386
diff
changeset
|
257 |
|
b2c0550d5a44
Docs: minimal introduction for getfirstXXXl_s variants
Franz Glasner <fzglas.hg@dom66.de>
parents:
386
diff
changeset
|
258 For example -- these methods for retrieving the first found variables |
| 389 | 259 can be used and are equivalent (Note that a caller that wants to use |
| 260 variables from a non-default namespace must use a sequence of dicts | |
| 261 here):: | |
|
387
b2c0550d5a44
Docs: minimal introduction for getfirstXXXl_s variants
Franz Glasner <fzglas.hg@dom66.de>
parents:
386
diff
changeset
|
262 |
|
b2c0550d5a44
Docs: minimal introduction for getfirstXXXl_s variants
Franz Glasner <fzglas.hg@dom66.de>
parents:
386
diff
changeset
|
263 value1 = config.getfirstvar_s("key1.subkey2", "key3.subkey4", default=None, namespace=None) |
|
b2c0550d5a44
Docs: minimal introduction for getfirstXXXl_s variants
Franz Glasner <fzglas.hg@dom66.de>
parents:
386
diff
changeset
|
264 value2 = config.getfirstvarl_s(*[["key1", "subkey2"], ["key3", "subkey4"]], default=None) |
|
b2c0550d5a44
Docs: minimal introduction for getfirstXXXl_s variants
Franz Glasner <fzglas.hg@dom66.de>
parents:
386
diff
changeset
|
265 value3 = config.getfirstvarl_s(*(("key1", "subkey2"), ("key3", "subkey4")), default=None) |
|
b2c0550d5a44
Docs: minimal introduction for getfirstXXXl_s variants
Franz Glasner <fzglas.hg@dom66.de>
parents:
386
diff
changeset
|
266 value4 = config.getfirstvarl_s(*[{"namespace": None, "path": ["key1", "subkey2"]}, {"namespace": None, "path": ("key3", "subkey4")}], default=None) |
|
b2c0550d5a44
Docs: minimal introduction for getfirstXXXl_s variants
Franz Glasner <fzglas.hg@dom66.de>
parents:
386
diff
changeset
|
267 |
|
115
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
268 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
|
269 ``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
|
270 ``get this as `tree1.tree2.key4'``. |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
271 |
|
315
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
272 Alternatively ``config.getvarl_s("tree1", "tree2", "key4")`` can be called |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
273 with the very same result. |
|
115
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
274 |
|
315
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
275 All four methods also perform direct :ref:`variable-interpolation` and |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
276 handle :ref:`variable-namespaces` -- yet in different ways. |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
277 Filtering is not supported. |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
278 So -- the variable name arguments of :py:meth:`.Configuration.getvar` |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
279 and :py:meth:`.Configuration.getvar_s` are of the form |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
280 ``[namespace:]variable`` where for :py:meth:`.Configuration.getvarl` |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
281 and :py:meth:`.Configuration.getvarl_s` the namespace is given as |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
282 optional keyword parameter `namespace`. |
|
117
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
283 |
| 333 | 284 .. note:: Special characters within namespace, key and filter names |
| 285 *must* be quoted (see :ref:`quoting`) when using | |
| 286 :py:meth:`~.Configuration.getvar` or | |
| 287 :py:meth:`~.Configuration.getvar_s` to retrieve variables. | |
| 288 | |
| 289 With :py:meth:`~.Configuration.getvarl` or | |
| 290 :py:meth:`~.Configuration.getvarl_s` quoting is neither needed | |
| 291 and not supported. | |
|
117
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
292 |
|
276
af371f9c016d
Allow deletion of key-value pairs when merging is done.
Franz Glasner <fzglas.hg@dom66.de>
parents:
243
diff
changeset
|
293 .. _merging-deletions: |
|
af371f9c016d
Allow deletion of key-value pairs when merging is done.
Franz Glasner <fzglas.hg@dom66.de>
parents:
243
diff
changeset
|
294 |
|
af371f9c016d
Allow deletion of key-value pairs when merging is done.
Franz Glasner <fzglas.hg@dom66.de>
parents:
243
diff
changeset
|
295 Deletions |
|
af371f9c016d
Allow deletion of key-value pairs when merging is done.
Franz Glasner <fzglas.hg@dom66.de>
parents:
243
diff
changeset
|
296 --------- |
|
af371f9c016d
Allow deletion of key-value pairs when merging is done.
Franz Glasner <fzglas.hg@dom66.de>
parents:
243
diff
changeset
|
297 |
|
af371f9c016d
Allow deletion of key-value pairs when merging is done.
Franz Glasner <fzglas.hg@dom66.de>
parents:
243
diff
changeset
|
298 By using the special value ``{{::DEL::}}`` the corresponding key-value |
|
af371f9c016d
Allow deletion of key-value pairs when merging is done.
Franz Glasner <fzglas.hg@dom66.de>
parents:
243
diff
changeset
|
299 pair is deleted when merging is done. |
|
af371f9c016d
Allow deletion of key-value pairs when merging is done.
Franz Glasner <fzglas.hg@dom66.de>
parents:
243
diff
changeset
|
300 |
|
af371f9c016d
Allow deletion of key-value pairs when merging is done.
Franz Glasner <fzglas.hg@dom66.de>
parents:
243
diff
changeset
|
301 |
| 145 | 302 .. _comments: |
| 303 | |
| 304 Comments | |
| 305 -------- | |
| 306 | |
| 307 By default all keys beginning with ``__comment`` or ``__doc`` are | |
| 308 filtered out and not given to the application. This allows comments in | |
| 309 JSON files -- but is not restricted to JSON files only. | |
| 310 | |
| 311 For all types of configuration files their respective standard comments | |
| 312 are allowed too. | |
| 313 | |
| 314 | |
|
117
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
315 .. _variable-namespaces: |
|
115
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 Variable Namespaces |
|
117
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
318 ------------------- |
|
115
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
319 |
|
316
fe2e28e5fd08
Docu: first short notes about configuration tree references
Franz Glasner <fzglas.hg@dom66.de>
parents:
315
diff
changeset
|
320 Currently there are 6 namespaces: |
|
115
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 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
|
323 |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
324 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
|
325 |
| 333 | 326 .. seealso:: :ref:`quoting` |
| 327 | |
|
316
fe2e28e5fd08
Docu: first short notes about configuration tree references
Franz Glasner <fzglas.hg@dom66.de>
parents:
315
diff
changeset
|
328 2. The namespace ``ref`` to be used for configuration references. |
|
fe2e28e5fd08
Docu: first short notes about configuration tree references
Franz Glasner <fzglas.hg@dom66.de>
parents:
315
diff
changeset
|
329 |
|
fe2e28e5fd08
Docu: first short notes about configuration tree references
Franz Glasner <fzglas.hg@dom66.de>
parents:
315
diff
changeset
|
330 This is a namespace that is handled special within "ConfigMix". |
|
fe2e28e5fd08
Docu: first short notes about configuration tree references
Franz Glasner <fzglas.hg@dom66.de>
parents:
315
diff
changeset
|
331 |
|
fe2e28e5fd08
Docu: first short notes about configuration tree references
Franz Glasner <fzglas.hg@dom66.de>
parents:
315
diff
changeset
|
332 Must be Filters are **not** supported. |
|
fe2e28e5fd08
Docu: first short notes about configuration tree references
Franz Glasner <fzglas.hg@dom66.de>
parents:
315
diff
changeset
|
333 |
|
fe2e28e5fd08
Docu: first short notes about configuration tree references
Franz Glasner <fzglas.hg@dom66.de>
parents:
315
diff
changeset
|
334 3. The namespace ``OS`` |
|
115
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 Available functions: |
|
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 ``cwd`` |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
339 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
|
340 |
|
243
57ff12610dc5
Implemented OS:node to return the host's computername
Franz Glasner <fzglas.hg@dom66.de>
parents:
215
diff
changeset
|
341 ``node`` |
|
57ff12610dc5
Implemented OS:node to return the host's computername
Franz Glasner <fzglas.hg@dom66.de>
parents:
215
diff
changeset
|
342 Contains the current node's computername (or whatever |
|
57ff12610dc5
Implemented OS:node to return the host's computername
Franz Glasner <fzglas.hg@dom66.de>
parents:
215
diff
changeset
|
343 :py:func:`platform.node` returns) |
|
57ff12610dc5
Implemented OS:node to return the host's computername
Franz Glasner <fzglas.hg@dom66.de>
parents:
215
diff
changeset
|
344 |
|
316
fe2e28e5fd08
Docu: first short notes about configuration tree references
Franz Glasner <fzglas.hg@dom66.de>
parents:
315
diff
changeset
|
345 4. The namespace ``ENV`` |
|
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 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
|
348 available from :py:data:`os.environ`. |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
349 |
|
316
fe2e28e5fd08
Docu: first short notes about configuration tree references
Franz Glasner <fzglas.hg@dom66.de>
parents:
315
diff
changeset
|
350 5. The namespace ``PY`` |
|
115
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
351 |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
352 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
|
353 |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
354 ``version`` |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
355 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
|
356 |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
357 ``version_maj_min`` |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
358 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
|
359 (``.`` separated) |
|
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 ``version_maj`` |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
362 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
|
363 |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
364 ``implementation`` |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
365 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
|
366 |
|
316
fe2e28e5fd08
Docu: first short notes about configuration tree references
Franz Glasner <fzglas.hg@dom66.de>
parents:
315
diff
changeset
|
367 6. The namespace ``AWS`` |
|
282
da1596034954
Implemented an "AWS" namespace to retrieve some AWS-specific metadata
Franz Glasner <fzglas.hg@dom66.de>
parents:
276
diff
changeset
|
368 |
|
da1596034954
Implemented an "AWS" namespace to retrieve some AWS-specific metadata
Franz Glasner <fzglas.hg@dom66.de>
parents:
276
diff
changeset
|
369 Contains some metadata for AWS instances when running from within |
|
da1596034954
Implemented an "AWS" namespace to retrieve some AWS-specific metadata
Franz Glasner <fzglas.hg@dom66.de>
parents:
276
diff
changeset
|
370 AWS: |
|
da1596034954
Implemented an "AWS" namespace to retrieve some AWS-specific metadata
Franz Glasner <fzglas.hg@dom66.de>
parents:
276
diff
changeset
|
371 |
|
da1596034954
Implemented an "AWS" namespace to retrieve some AWS-specific metadata
Franz Glasner <fzglas.hg@dom66.de>
parents:
276
diff
changeset
|
372 ``metadata.instance-id`` |
|
da1596034954
Implemented an "AWS" namespace to retrieve some AWS-specific metadata
Franz Glasner <fzglas.hg@dom66.de>
parents:
276
diff
changeset
|
373 |
|
da1596034954
Implemented an "AWS" namespace to retrieve some AWS-specific metadata
Franz Glasner <fzglas.hg@dom66.de>
parents:
276
diff
changeset
|
374 ``metadata.placement.region`` |
|
da1596034954
Implemented an "AWS" namespace to retrieve some AWS-specific metadata
Franz Glasner <fzglas.hg@dom66.de>
parents:
276
diff
changeset
|
375 |
|
da1596034954
Implemented an "AWS" namespace to retrieve some AWS-specific metadata
Franz Glasner <fzglas.hg@dom66.de>
parents:
276
diff
changeset
|
376 ``metadata.placement.availability-zone`` |
|
da1596034954
Implemented an "AWS" namespace to retrieve some AWS-specific metadata
Franz Glasner <fzglas.hg@dom66.de>
parents:
276
diff
changeset
|
377 |
|
da1596034954
Implemented an "AWS" namespace to retrieve some AWS-specific metadata
Franz Glasner <fzglas.hg@dom66.de>
parents:
276
diff
changeset
|
378 ``dynamic.instance-identity.region`` |
|
da1596034954
Implemented an "AWS" namespace to retrieve some AWS-specific metadata
Franz Glasner <fzglas.hg@dom66.de>
parents:
276
diff
changeset
|
379 and all other properties of the instance-identity document |
|
da1596034954
Implemented an "AWS" namespace to retrieve some AWS-specific metadata
Franz Glasner <fzglas.hg@dom66.de>
parents:
276
diff
changeset
|
380 (e.g. ``instanceId``, ``instanceType``, ``imageId``, ``pendingTime``, |
|
da1596034954
Implemented an "AWS" namespace to retrieve some AWS-specific metadata
Franz Glasner <fzglas.hg@dom66.de>
parents:
276
diff
changeset
|
381 ``architecture``, ``availabilityZone``, ``privateIp``, ``version`` |
|
da1596034954
Implemented an "AWS" namespace to retrieve some AWS-specific metadata
Franz Glasner <fzglas.hg@dom66.de>
parents:
276
diff
changeset
|
382 et al.). |
|
da1596034954
Implemented an "AWS" namespace to retrieve some AWS-specific metadata
Franz Glasner <fzglas.hg@dom66.de>
parents:
276
diff
changeset
|
383 |
|
115
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
384 |
|
117
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
385 Examples |
|
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
386 ~~~~~~~~ |
|
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
387 |
|
315
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
388 Both :: |
|
117
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
389 |
|
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
390 config.getvar("OS:cwd") |
|
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
391 |
|
315
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
392 or :: |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
393 |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
394 config.getvarl("cwd", namespace="OS") |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
395 |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
396 yield the current working directory -- just as :py:func:`os.getcwd` does. |
|
117
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
397 |
|
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
398 |
|
202
2e66178a09d8
Docu: Ban "keyword expansion" -- use "variable interpolation" instead
Franz Glasner <fzglas.hg@dom66.de>
parents:
200
diff
changeset
|
399 .. _variable-interpolation: |
|
117
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
400 |
|
202
2e66178a09d8
Docu: Ban "keyword expansion" -- use "variable interpolation" instead
Franz Glasner <fzglas.hg@dom66.de>
parents:
200
diff
changeset
|
401 Variable Interpolation |
|
2e66178a09d8
Docu: Ban "keyword expansion" -- use "variable interpolation" instead
Franz Glasner <fzglas.hg@dom66.de>
parents:
200
diff
changeset
|
402 ---------------------- |
|
117
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
403 |
|
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
404 Configuration variable values that are read with |
|
315
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
405 :py:meth:`.Configuration.getvar_s` or :py:meth:`.Configuration.getvarl_s` |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
406 are subject to variable interpolation. |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
407 The general syntactic pattern for this is:: |
|
117
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
408 |
|
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
409 {{[namespace:]variable[|filter[|filter...]]}} |
|
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
410 |
|
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
411 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
|
412 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
|
413 introduced by a pipe symbol ``|``. |
|
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
414 |
|
202
2e66178a09d8
Docu: Ban "keyword expansion" -- use "variable interpolation" instead
Franz Glasner <fzglas.hg@dom66.de>
parents:
200
diff
changeset
|
415 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
|
416 :py:meth:`.Configuration.getvar_s`, |
|
315
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
417 :py:meth:`.Configuration.getvarl_s`, |
|
158
ab6a48ff5235
FIX: Docu: Configuration.getvar() does **not** apply variable substitutions
Franz Glasner <fzglas.hg@dom66.de>
parents:
145
diff
changeset
|
418 :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
|
419 :py:meth:`.Configuration.expand_variable` |
|
117
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
420 |
| 333 | 421 .. note:: Special characters within namespace, key and filter names |
| 422 *must* be quoted (see :ref:`quoting`) when using variable | |
| 423 interpolation syntax. | |
| 424 | |
|
117
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
425 |
|
115
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
426 Filter functions |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
427 ~~~~~~~~~~~~~~~~ |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
428 |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
429 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
|
430 |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
431 {{my.variable|filter1|filter2}} |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
432 |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
433 Available filter functions are: |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
434 |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
435 ``urlquote`` |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
436 |
|
347
d7daec119383
New filter function "urlquote_plus" which quotes a space into a '+' character
Franz Glasner <fzglas.hg@dom66.de>
parents:
343
diff
changeset
|
437 ``urlquote_plus`` |
|
d7daec119383
New filter function "urlquote_plus" which quotes a space into a '+' character
Franz Glasner <fzglas.hg@dom66.de>
parents:
343
diff
changeset
|
438 |
|
115
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
439 ``saslprep`` |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
440 |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
441 ``normpath`` |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
442 |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
443 ``abspath`` |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
444 |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
445 ``posixpath`` |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
446 |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
447 ``lower`` |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
448 |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
449 ``upper`` |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
450 |
|
353
a7491f835cb0
Changelog and minimal docu for `None` and `Empty` filters
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
347
diff
changeset
|
451 Also available are special filter functions ``None`` and ``Empty``. |
|
a7491f835cb0
Changelog and minimal docu for `None` and `Empty` filters
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
347
diff
changeset
|
452 They are useful in variable interpolation context because they |
|
354
bd28fb4565e1
FIX: Tagging of the KeyError: :py:exception: -> :py:exc:
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
353
diff
changeset
|
453 suppress possible lookup errors (aka :py:exc:`KeyError`) and instead |
|
bd28fb4565e1
FIX: Tagging of the KeyError: :py:exception: -> :py:exc:
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
353
diff
changeset
|
454 return with :py:obj:`None` or an empty string. |
|
353
a7491f835cb0
Changelog and minimal docu for `None` and `Empty` filters
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
347
diff
changeset
|
455 |
|
115
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
456 |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
457 Examples |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
458 ~~~~~~~~ |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
459 |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
460 :: |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
461 |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
462 {{OS:cwd|posixpath}} |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
463 |
|
117
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
464 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
|
465 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
|
466 |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
467 :: |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
468 |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
469 {{ENV:PATH}} |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
470 |
|
117
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
471 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
|
472 |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
473 :: |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
474 |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
475 {{PY:version}} |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
476 |
|
117
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
477 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
|
478 |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
479 :: |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
480 |
|
328
cffa4fcd0a4d
Docu: syntax fix in example
Franz Glasner <fzglas.hg@dom66.de>
parents:
316
diff
changeset
|
481 {{PY:implementation|upper}} |
|
115
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
482 |
|
117
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
483 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
|
484 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
|
485 |
|
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
|
486 |
|
316
fe2e28e5fd08
Docu: first short notes about configuration tree references
Franz Glasner <fzglas.hg@dom66.de>
parents:
315
diff
changeset
|
487 Configuration tree references |
|
fe2e28e5fd08
Docu: first short notes about configuration tree references
Franz Glasner <fzglas.hg@dom66.de>
parents:
315
diff
changeset
|
488 ----------------------------- |
|
fe2e28e5fd08
Docu: first short notes about configuration tree references
Franz Glasner <fzglas.hg@dom66.de>
parents:
315
diff
changeset
|
489 |
|
341
ae4b76d0da45
docs: fix example of tree reference syntax
Franz Glasner <fzglas.hg@dom66.de>
parents:
340
diff
changeset
|
490 With ``{{ref:#my.other.key}}`` |
|
316
fe2e28e5fd08
Docu: first short notes about configuration tree references
Franz Glasner <fzglas.hg@dom66.de>
parents:
315
diff
changeset
|
491 |
|
353
a7491f835cb0
Changelog and minimal docu for `None` and `Empty` filters
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
347
diff
changeset
|
492 - think of it as a sort of a symbolic link to other parts of the |
|
343
c8b98285a7b5
docs: some more docu for tree references
Franz Glasner <fzglas.hg@dom66.de>
parents:
341
diff
changeset
|
493 configuration tree |
|
c8b98285a7b5
docs: some more docu for tree references
Franz Glasner <fzglas.hg@dom66.de>
parents:
341
diff
changeset
|
494 - by employing the special namespace ``ref`` |
|
340
176e22110fc5
docs, tests: notes and additional tests when quoting the "ref" namespace name
Franz Glasner <fzglas.hg@dom66.de>
parents:
339
diff
changeset
|
495 - can not be quoted currently in variable interpolation syntax |
|
343
c8b98285a7b5
docs: some more docu for tree references
Franz Glasner <fzglas.hg@dom66.de>
parents:
341
diff
changeset
|
496 - No special handling when merging is done -- merging is agnostic of |
|
c8b98285a7b5
docs: some more docu for tree references
Franz Glasner <fzglas.hg@dom66.de>
parents:
341
diff
changeset
|
497 tree references |
|
353
a7491f835cb0
Changelog and minimal docu for `None` and `Empty` filters
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
347
diff
changeset
|
498 - Keys within :meth:`.Configuration.getvar_s`, |
|
343
c8b98285a7b5
docs: some more docu for tree references
Franz Glasner <fzglas.hg@dom66.de>
parents:
341
diff
changeset
|
499 :py:meth:`.Configuration.getvar`, :py:meth:`.Configuration.getvarl` |
|
c8b98285a7b5
docs: some more docu for tree references
Franz Glasner <fzglas.hg@dom66.de>
parents:
341
diff
changeset
|
500 and :py:meth:`.Configuration.getvarl_s` are handled |
|
c8b98285a7b5
docs: some more docu for tree references
Franz Glasner <fzglas.hg@dom66.de>
parents:
341
diff
changeset
|
501 - in :py:meth:`.Configuration.getvar` only, when it is the directly |
| 333 | 502 referenced value |
|
343
c8b98285a7b5
docs: some more docu for tree references
Franz Glasner <fzglas.hg@dom66.de>
parents:
341
diff
changeset
|
503 - recursive expansion in :py:meth:`.Configuration.getvar_s` and |
|
c8b98285a7b5
docs: some more docu for tree references
Franz Glasner <fzglas.hg@dom66.de>
parents:
341
diff
changeset
|
504 :py:meth:`.Configuration.getvarl_s`: |
|
c8b98285a7b5
docs: some more docu for tree references
Franz Glasner <fzglas.hg@dom66.de>
parents:
341
diff
changeset
|
505 beware of recursive (direct or indirect) tree references |
| 333 | 506 |
| 507 | |
| 508 .. _quoting: | |
| 509 | |
| 510 Quoting | |
| 511 ------- | |
| 512 | |
| 513 When using :py:meth:`.Configuration.getvar` and | |
| 514 :py:meth:`.Configuration.getvar_s` and when retrieving values in the | |
| 515 default namespace the namespace separator ``:`` or the hierarchy | |
| 516 separator ``.`` are characters with a special meaning. When using | |
| 517 :ref:`variable interpolation <variable-interpolation>` the filter | |
| 339 | 518 separator ``|`` is also special. To use them in key names they must be |
| 333 | 519 quoted. |
| 520 | |
| 521 Quoting is done with a variant of the well-known percent-encoding in | |
| 522 URIs (:rfc:`3986`). | |
| 523 | |
| 524 A percent-encoded character consists of the percent character ``%``, | |
| 525 followed by one of the characters ``x``, ``u`` or ``U``, followed by | |
| 526 the two, four or eight hexadecimal digits of the unicode codepoint | |
| 527 value of the character that is to be quoted. ``x`` must be followed by | |
| 528 two hex digits, ``u`` by four and ``U`` by eight. | |
| 529 | |
| 530 Example: | |
| 531 | |
| 532 The character ``.`` with the Unicode (and ASCII) value 46 (hex 0x2e) | |
| 533 can be encoded as ``%x2e`` or ``%u002e`` or ``%U0000002e``. | |
| 534 | |
| 535 .. note:: Filters neeed no quoting -- and quoting within filters is *not* | |
| 536 supported. | |
|
316
fe2e28e5fd08
Docu: first short notes about configuration tree references
Franz Glasner <fzglas.hg@dom66.de>
parents:
315
diff
changeset
|
537 |
|
340
176e22110fc5
docs, tests: notes and additional tests when quoting the "ref" namespace name
Franz Glasner <fzglas.hg@dom66.de>
parents:
339
diff
changeset
|
538 .. note:: Quoting the ``ref`` namespace name does not work currently when |
|
176e22110fc5
docs, tests: notes and additional tests when quoting the "ref" namespace name
Franz Glasner <fzglas.hg@dom66.de>
parents:
339
diff
changeset
|
539 used in variable interpolation syntax. |
|
176e22110fc5
docs, tests: notes and additional tests when quoting the "ref" namespace name
Franz Glasner <fzglas.hg@dom66.de>
parents:
339
diff
changeset
|
540 |
|
316
fe2e28e5fd08
Docu: first short notes about configuration tree references
Franz Glasner <fzglas.hg@dom66.de>
parents:
315
diff
changeset
|
541 |
| 400 | 542 .. _jailed-configuration: |
| 543 | |
| 544 Jailed Configurations | |
| 545 --------------------- | |
| 546 | |
| 547 With :meth:`configmix.config.Configuration.jailed` you get a `jailed` | |
| 548 (or `restricted`) configuration from a "normal" configuration. | |
| 549 | |
| 550 Restriction is two-fold: | |
| 551 | |
| 552 - The access to configuration variables in `config` is restricted | |
| 553 to the configuration sub-tree that is configured in `path`. | |
| 554 | |
| 555 - Not all access-methods of :class:`Configuration` are implemented | |
| 556 yet. | |
| 557 | |
| 558 This is somewhat analogous to a `chroot` environment for filesystems. | |
| 559 | |
| 560 .. note:: The word "jail" is shamelessly stolen from FreeBSD jails. | |
| 561 | |
| 562 Usage example:: | |
| 563 | |
| 564 import configmix | |
| 565 | |
| 566 config = configmix.load("conf10.py") | |
|
426
84d4f82ffe59
Docs: more on jails and sub-jails
Franz Glasner <fzglas.hg@dom66.de>
parents:
425
diff
changeset
|
567 assert not config.is_jail |
| 400 | 568 value = config.getvar_s("tree1.tree2.key4") |
| 569 | |
| 570 jailed_config1 = config.jailed(rootpath="tree1.tree2") | |
|
426
84d4f82ffe59
Docs: more on jails and sub-jails
Franz Glasner <fzglas.hg@dom66.de>
parents:
425
diff
changeset
|
571 assert jailed_config1.is_jail |
|
84d4f82ffe59
Docs: more on jails and sub-jails
Franz Glasner <fzglas.hg@dom66.de>
parents:
425
diff
changeset
|
572 assert jailed_config1.base is config |
| 400 | 573 jvalue1 = jailed_config1.getvar_s("key4") |
| 574 | |
| 575 jailed_config2 = config.jailed(root=("tree1", "tree2")) | |
|
426
84d4f82ffe59
Docs: more on jails and sub-jails
Franz Glasner <fzglas.hg@dom66.de>
parents:
425
diff
changeset
|
576 assert jailed_config2.is_jail |
|
84d4f82ffe59
Docs: more on jails and sub-jails
Franz Glasner <fzglas.hg@dom66.de>
parents:
425
diff
changeset
|
577 assert jailed_config2.base is config |
| 400 | 578 jvalue2 = jailed_config.getvarl_s("key4") |
| 579 | |
| 580 assert value == jvalue1 == jvalue2 == "get this as `tree1.tree2.key4'" | |
| 581 | |
| 582 `jvalue1` and `jvalue2` (and `value`) yield the very same value | |
| 583 ``get this as `tree1.tree2.key4'`` from the configuration. | |
| 584 | |
| 585 All access methods in a jailed configuration automatically prepend the | |
| 586 given `root path` in order to get the effective key into the base | |
| 587 configuration. | |
| 588 | |
|
424
e60b72df15de
Introduction into sub-jails
Franz Glasner <fzglas.hg@dom66.de>
parents:
400
diff
changeset
|
589 It is possible to get a jailed configuration from an already jailed |
|
426
84d4f82ffe59
Docs: more on jails and sub-jails
Franz Glasner <fzglas.hg@dom66.de>
parents:
425
diff
changeset
|
590 configuration. This sub-jail inherits the unjailed base configuration from |
|
84d4f82ffe59
Docs: more on jails and sub-jails
Franz Glasner <fzglas.hg@dom66.de>
parents:
425
diff
changeset
|
591 the jailed configuration by default. |
|
84d4f82ffe59
Docs: more on jails and sub-jails
Franz Glasner <fzglas.hg@dom66.de>
parents:
425
diff
changeset
|
592 |
|
84d4f82ffe59
Docs: more on jails and sub-jails
Franz Glasner <fzglas.hg@dom66.de>
parents:
425
diff
changeset
|
593 :: |
|
424
e60b72df15de
Introduction into sub-jails
Franz Glasner <fzglas.hg@dom66.de>
parents:
400
diff
changeset
|
594 |
|
e60b72df15de
Introduction into sub-jails
Franz Glasner <fzglas.hg@dom66.de>
parents:
400
diff
changeset
|
595 import configmix |
|
e60b72df15de
Introduction into sub-jails
Franz Glasner <fzglas.hg@dom66.de>
parents:
400
diff
changeset
|
596 |
|
e60b72df15de
Introduction into sub-jails
Franz Glasner <fzglas.hg@dom66.de>
parents:
400
diff
changeset
|
597 config = configmix.load("conf10.py") |
|
426
84d4f82ffe59
Docs: more on jails and sub-jails
Franz Glasner <fzglas.hg@dom66.de>
parents:
425
diff
changeset
|
598 assert not config.is_jail |
|
424
e60b72df15de
Introduction into sub-jails
Franz Glasner <fzglas.hg@dom66.de>
parents:
400
diff
changeset
|
599 value = config.getvar_s("tree1.tree2.key4") |
|
e60b72df15de
Introduction into sub-jails
Franz Glasner <fzglas.hg@dom66.de>
parents:
400
diff
changeset
|
600 |
|
e60b72df15de
Introduction into sub-jails
Franz Glasner <fzglas.hg@dom66.de>
parents:
400
diff
changeset
|
601 jailed_config1 = config.jailed(rootpath="tree1") |
|
426
84d4f82ffe59
Docs: more on jails and sub-jails
Franz Glasner <fzglas.hg@dom66.de>
parents:
425
diff
changeset
|
602 assert jailed_config1.is_jail |
|
84d4f82ffe59
Docs: more on jails and sub-jails
Franz Glasner <fzglas.hg@dom66.de>
parents:
425
diff
changeset
|
603 assert jailed_config2.base is config |
|
424
e60b72df15de
Introduction into sub-jails
Franz Glasner <fzglas.hg@dom66.de>
parents:
400
diff
changeset
|
604 |
|
e60b72df15de
Introduction into sub-jails
Franz Glasner <fzglas.hg@dom66.de>
parents:
400
diff
changeset
|
605 jailed_config2 = jailed_config2.jailed(rootpath="tree2") |
|
426
84d4f82ffe59
Docs: more on jails and sub-jails
Franz Glasner <fzglas.hg@dom66.de>
parents:
425
diff
changeset
|
606 assert jailed_config2.is_jail |
|
84d4f82ffe59
Docs: more on jails and sub-jails
Franz Glasner <fzglas.hg@dom66.de>
parents:
425
diff
changeset
|
607 assert jailed_config2.base is config |
|
424
e60b72df15de
Introduction into sub-jails
Franz Glasner <fzglas.hg@dom66.de>
parents:
400
diff
changeset
|
608 jvalue2 = jailed_config.getvarl_s("key4") |
|
e60b72df15de
Introduction into sub-jails
Franz Glasner <fzglas.hg@dom66.de>
parents:
400
diff
changeset
|
609 |
|
e60b72df15de
Introduction into sub-jails
Franz Glasner <fzglas.hg@dom66.de>
parents:
400
diff
changeset
|
610 assert value == jvalue2 == "get this as `tree1.tree2.key4'" |
|
e60b72df15de
Introduction into sub-jails
Franz Glasner <fzglas.hg@dom66.de>
parents:
400
diff
changeset
|
611 |
|
425
88d8de9310af
Docs: jails hold strong references to the unjailed base configuration
Franz Glasner <fzglas.hg@dom66.de>
parents:
424
diff
changeset
|
612 .. note:: A jailed configuration holds a strong reference to the unjailed |
|
88d8de9310af
Docs: jails hold strong references to the unjailed base configuration
Franz Glasner <fzglas.hg@dom66.de>
parents:
424
diff
changeset
|
613 base configuration. |
|
88d8de9310af
Docs: jails hold strong references to the unjailed base configuration
Franz Glasner <fzglas.hg@dom66.de>
parents:
424
diff
changeset
|
614 |
| 400 | 615 |
|
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
|
616 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
|
617 --------------------------------------------- |
|
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
|
618 |
|
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
|
619 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
|
620 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
|
621 |
|
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
|
622 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
|
623 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
|
624 |
|
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
|
625 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
|
626 |
|
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
|
627 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
|
628 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
|
629 |
|
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
|
630 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
|
631 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
|
632 |
|
194
0d8dd58afc44
Docu: Enhanced the custom loader section somewhat
Franz Glasner <fzglas.hg@dom66.de>
parents:
193
diff
changeset
|
633 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
|
634 |
|
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
|
635 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
|
636 ... |
|
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
|
637 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
|
638 |
|
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
|
639 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
|
640 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
|
641 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
|
642 |
|
0d8dd58afc44
Docu: Enhanced the custom loader section somewhat
Franz Glasner <fzglas.hg@dom66.de>
parents:
193
diff
changeset
|
643 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
|
644 configuration file style will be installed. |
|
210
fa660f084ceb
Docu: an example for configmix.try_determine_filemode()
Franz Glasner <fzglas.hg@dom66.de>
parents:
202
diff
changeset
|
645 |
|
fa660f084ceb
Docu: an example for configmix.try_determine_filemode()
Franz Glasner <fzglas.hg@dom66.de>
parents:
202
diff
changeset
|
646 To select the loader not by extension but by an Emacs-compatible mode |
|
fa660f084ceb
Docu: an example for configmix.try_determine_filemode()
Franz Glasner <fzglas.hg@dom66.de>
parents:
202
diff
changeset
|
647 declaration (e.g. ``mode: yaml``) in the first two lines of a file use:: |
|
fa660f084ceb
Docu: an example for configmix.try_determine_filemode()
Franz Glasner <fzglas.hg@dom66.de>
parents:
202
diff
changeset
|
648 |
|
fa660f084ceb
Docu: an example for configmix.try_determine_filemode()
Franz Glasner <fzglas.hg@dom66.de>
parents:
202
diff
changeset
|
649 configmix.set_assoc("*", configmix.try_determine_filemode) |