Mercurial > hgrepos > Python > libs > ConfigMix
annotate docs/introduction.rst @ 765:0180b7deebf1
===== Added signature for changeset 7bdf7d8a4e27
| author | Franz Glasner <fzglas.hg@dom66.de> |
|---|---|
| date | Thu, 07 Dec 2023 08:44:05 +0100 |
| parents | 220a9ec9ac72 |
| children |
| 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 |
|
742
220a9ec9ac72
- Docs the the new list merging strategies.
Franz Glasner <fzglas.hg@dom66.de>
parents:
727
diff
changeset
|
198 When loading two or more configuration files the configurations will be |
|
220a9ec9ac72
- Docs the the new list merging strategies.
Franz Glasner <fzglas.hg@dom66.de>
parents:
727
diff
changeset
|
199 merged: |
|
220a9ec9ac72
- Docs the the new list merging strategies.
Franz Glasner <fzglas.hg@dom66.de>
parents:
727
diff
changeset
|
200 |
|
220a9ec9ac72
- Docs the the new list merging strategies.
Franz Glasner <fzglas.hg@dom66.de>
parents:
727
diff
changeset
|
201 * later values overwrite earlier values |
|
220a9ec9ac72
- Docs the the new list merging strategies.
Franz Glasner <fzglas.hg@dom66.de>
parents:
727
diff
changeset
|
202 * :py:class:`dict`-like objects are merged `recursively` |
|
220a9ec9ac72
- Docs the the new list merging strategies.
Franz Glasner <fzglas.hg@dom66.de>
parents:
727
diff
changeset
|
203 * :py:class:`list` objects are by default completely replaced by later ones. |
|
220a9ec9ac72
- Docs the the new list merging strategies.
Franz Glasner <fzglas.hg@dom66.de>
parents:
727
diff
changeset
|
204 When using ``merge_lists="extend"`` then later list extend earlier lists, |
|
220a9ec9ac72
- Docs the the new list merging strategies.
Franz Glasner <fzglas.hg@dom66.de>
parents:
727
diff
changeset
|
205 when using ``merge_lists="prepend"`` then earlier lists extend later ones. |
|
220a9ec9ac72
- Docs the the new list merging strategies.
Franz Glasner <fzglas.hg@dom66.de>
parents:
727
diff
changeset
|
206 |
|
220a9ec9ac72
- Docs the the new list merging strategies.
Franz Glasner <fzglas.hg@dom66.de>
parents:
727
diff
changeset
|
207 This is done `non-recursively`. |
|
220a9ec9ac72
- Docs the the new list merging strategies.
Franz Glasner <fzglas.hg@dom66.de>
parents:
727
diff
changeset
|
208 |
|
115
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
209 |
|
117
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
210 .. _getting-values: |
|
115
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
211 |
|
117
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
212 Getting configuration variables |
|
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
213 ------------------------------- |
|
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
214 |
|
315
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
215 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
|
216 |
|
117
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
217 value1 = config.getvar_s("key1") |
|
315
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
218 value2 = config.getvar_s("key1.subkey2") |
|
117
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
219 |
|
315
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
220 or equivalently with :: |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
221 |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
222 value1 = config.getvarl_s("key1") |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
223 value2 = config.getvarl_s("key1", "subkey2") |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
224 |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
225 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
|
226 |
|
117
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
227 value1_raw = config.getvar("key1") |
|
315
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
228 value2_raw = config.getvarl("key1.subkey2") |
|
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 or equivalently with :: |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
231 |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
232 value1_raw = config.getvarl("key1") |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
233 value2_raw = config.getvarl("key1", "subkey2") |
|
117
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
234 |
|
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
235 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
|
236 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
|
237 using two access basic methods: |
|
315
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
238 |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
239 :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
|
240 |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
241 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
|
242 using a dot (``.``) |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
243 |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
244 :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
|
245 |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
246 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
|
247 |
|
375
baedd2031074
Docs: Introduce the newly introduces access methods
Franz Glasner <fzglas.hg@dom66.de>
parents:
354
diff
changeset
|
248 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
|
249 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
|
250 (:py:meth:`.Configuration.getintvar_s`, |
|
baedd2031074
Docs: Introduce the newly introduces access methods
Franz Glasner <fzglas.hg@dom66.de>
parents:
354
diff
changeset
|
251 :py:meth:`.Configuration.getboolvar_s`) |
|
baedd2031074
Docs: Introduce the newly introduces access methods
Franz Glasner <fzglas.hg@dom66.de>
parents:
354
diff
changeset
|
252 |
|
baedd2031074
Docs: Introduce the newly introduces access methods
Franz Glasner <fzglas.hg@dom66.de>
parents:
354
diff
changeset
|
253 And with :py:meth:`.Configuration.getfirstvar`, |
|
baedd2031074
Docs: Introduce the newly introduces access methods
Franz Glasner <fzglas.hg@dom66.de>
parents:
354
diff
changeset
|
254 :py:meth:`.Configuration.getfirstvar_s`, |
| 400 | 255 :py:meth:`.Configuration.getfirstintvar_s`, |
|
386
d7dcd76c262a
Add Configuration.getfirstfloatvar_s() to the introduction
Franz Glasner <fzglas.hg@dom66.de>
parents:
375
diff
changeset
|
256 :py:meth:`.Configuration.getfirstboolvar_s` and |
|
d7dcd76c262a
Add Configuration.getfirstfloatvar_s() to the introduction
Franz Glasner <fzglas.hg@dom66.de>
parents:
375
diff
changeset
|
257 :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
|
258 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
|
259 that is found. |
|
baedd2031074
Docs: Introduce the newly introduces access methods
Franz Glasner <fzglas.hg@dom66.de>
parents:
354
diff
changeset
|
260 |
|
387
b2c0550d5a44
Docs: minimal introduction for getfirstXXXl_s variants
Franz Glasner <fzglas.hg@dom66.de>
parents:
386
diff
changeset
|
261 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
|
262 :py:meth:`.Configuration.getfirstvarl_s`, |
|
b2c0550d5a44
Docs: minimal introduction for getfirstXXXl_s variants
Franz Glasner <fzglas.hg@dom66.de>
parents:
386
diff
changeset
|
263 :py:meth:`.Configuration.getfirstintvarl_s`, |
|
b2c0550d5a44
Docs: minimal introduction for getfirstXXXl_s variants
Franz Glasner <fzglas.hg@dom66.de>
parents:
386
diff
changeset
|
264 :py:meth:`.Configuration.getfirstboolvarl_s` and |
|
b2c0550d5a44
Docs: minimal introduction for getfirstXXXl_s variants
Franz Glasner <fzglas.hg@dom66.de>
parents:
386
diff
changeset
|
265 :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
|
266 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
|
267 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
|
268 |
|
b2c0550d5a44
Docs: minimal introduction for getfirstXXXl_s variants
Franz Glasner <fzglas.hg@dom66.de>
parents:
386
diff
changeset
|
269 For example -- these methods for retrieving the first found variables |
| 389 | 270 can be used and are equivalent (Note that a caller that wants to use |
| 271 variables from a non-default namespace must use a sequence of dicts | |
| 272 here):: | |
|
387
b2c0550d5a44
Docs: minimal introduction for getfirstXXXl_s variants
Franz Glasner <fzglas.hg@dom66.de>
parents:
386
diff
changeset
|
273 |
|
b2c0550d5a44
Docs: minimal introduction for getfirstXXXl_s variants
Franz Glasner <fzglas.hg@dom66.de>
parents:
386
diff
changeset
|
274 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
|
275 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
|
276 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
|
277 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
|
278 |
|
115
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
279 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
|
280 ``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
|
281 ``get this as `tree1.tree2.key4'``. |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
282 |
|
315
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
283 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
|
284 with the very same result. |
|
115
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
285 |
|
315
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
286 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
|
287 handle :ref:`variable-namespaces` -- yet in different ways. |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
288 Filtering is not supported. |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
289 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
|
290 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
|
291 ``[namespace:]variable`` where for :py:meth:`.Configuration.getvarl` |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
292 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
|
293 optional keyword parameter `namespace`. |
|
117
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
294 |
| 333 | 295 .. note:: Special characters within namespace, key and filter names |
| 296 *must* be quoted (see :ref:`quoting`) when using | |
| 297 :py:meth:`~.Configuration.getvar` or | |
| 298 :py:meth:`~.Configuration.getvar_s` to retrieve variables. | |
| 299 | |
| 300 With :py:meth:`~.Configuration.getvarl` or | |
| 301 :py:meth:`~.Configuration.getvarl_s` quoting is neither needed | |
| 302 and not supported. | |
|
117
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
303 |
|
658
6102b767fc69
Basic documentation for the indexed list access
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
426
diff
changeset
|
304 |
|
6102b767fc69
Basic documentation for the indexed list access
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
426
diff
changeset
|
305 Direct Access to List Items |
|
6102b767fc69
Basic documentation for the indexed list access
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
426
diff
changeset
|
306 --------------------------- |
|
6102b767fc69
Basic documentation for the indexed list access
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
426
diff
changeset
|
307 |
|
6102b767fc69
Basic documentation for the indexed list access
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
426
diff
changeset
|
308 Direct access to list items is possible: |
|
6102b767fc69
Basic documentation for the indexed list access
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
426
diff
changeset
|
309 |
|
6102b767fc69
Basic documentation for the indexed list access
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
426
diff
changeset
|
310 - Directly use the integer list index in :py:meth:`~.Configuration.getvarl` |
|
6102b767fc69
Basic documentation for the indexed list access
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
426
diff
changeset
|
311 and its friends. |
|
6102b767fc69
Basic documentation for the indexed list access
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
426
diff
changeset
|
312 - Encode the index number to string format using the ``~INDEX~`` syntax and |
|
6102b767fc69
Basic documentation for the indexed list access
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
426
diff
changeset
|
313 use :py:meth:`~.Configuration.getvar` and its friends. |
|
6102b767fc69
Basic documentation for the indexed list access
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
426
diff
changeset
|
314 |
|
659
b97e5f3bbc8e
Test indexed list access in variable interpolations: ok.
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
658
diff
changeset
|
315 This syntax is also supported for variable interpolations. |
|
b97e5f3bbc8e
Test indexed list access in variable interpolations: ok.
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
658
diff
changeset
|
316 |
|
658
6102b767fc69
Basic documentation for the indexed list access
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
426
diff
changeset
|
317 Negative indexes are supported with Python semantics. |
|
6102b767fc69
Basic documentation for the indexed list access
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
426
diff
changeset
|
318 |
|
6102b767fc69
Basic documentation for the indexed list access
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
426
diff
changeset
|
319 Examples: |
|
6102b767fc69
Basic documentation for the indexed list access
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
426
diff
changeset
|
320 |
|
6102b767fc69
Basic documentation for the indexed list access
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
426
diff
changeset
|
321 - ``config.getvarl_s("mylist", 0)`` or ``config.getvar_s("mylist.~0~)"`` |
|
6102b767fc69
Basic documentation for the indexed list access
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
426
diff
changeset
|
322 - ``config.getvarl_s("mylist", -1)`` or ``config.getvar_s("mylist.~-1~")`` |
|
6102b767fc69
Basic documentation for the indexed list access
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
426
diff
changeset
|
323 |
|
662
ce2f723da730
Drop a note when using direct list access syntax together with jailed configurations
Franz Glasner <fzglas.hg@dom66.de>
parents:
659
diff
changeset
|
324 This also works when using `Jailed Configurations`_. |
|
658
6102b767fc69
Basic documentation for the indexed list access
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
426
diff
changeset
|
325 |
|
663
8647eb175bb9
Docs: Drop a note to quote the "~" character when it shall not be subject to interpretation as key index but key string
Franz Glasner <fzglas.hg@dom66.de>
parents:
662
diff
changeset
|
326 Use `Quoting`_ for the ``~`` character (``%x7e``) when the ``~INDEX~`` |
|
8647eb175bb9
Docs: Drop a note to quote the "~" character when it shall not be subject to interpretation as key index but key string
Franz Glasner <fzglas.hg@dom66.de>
parents:
662
diff
changeset
|
327 syntax should not be interpreted as list index but as key string. |
|
8647eb175bb9
Docs: Drop a note to quote the "~" character when it shall not be subject to interpretation as key index but key string
Franz Glasner <fzglas.hg@dom66.de>
parents:
662
diff
changeset
|
328 |
|
658
6102b767fc69
Basic documentation for the indexed list access
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
426
diff
changeset
|
329 |
|
276
af371f9c016d
Allow deletion of key-value pairs when merging is done.
Franz Glasner <fzglas.hg@dom66.de>
parents:
243
diff
changeset
|
330 .. _merging-deletions: |
|
af371f9c016d
Allow deletion of key-value pairs when merging is done.
Franz Glasner <fzglas.hg@dom66.de>
parents:
243
diff
changeset
|
331 |
|
af371f9c016d
Allow deletion of key-value pairs when merging is done.
Franz Glasner <fzglas.hg@dom66.de>
parents:
243
diff
changeset
|
332 Deletions |
|
af371f9c016d
Allow deletion of key-value pairs when merging is done.
Franz Glasner <fzglas.hg@dom66.de>
parents:
243
diff
changeset
|
333 --------- |
|
af371f9c016d
Allow deletion of key-value pairs when merging is done.
Franz Glasner <fzglas.hg@dom66.de>
parents:
243
diff
changeset
|
334 |
|
af371f9c016d
Allow deletion of key-value pairs when merging is done.
Franz Glasner <fzglas.hg@dom66.de>
parents:
243
diff
changeset
|
335 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
|
336 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
|
337 |
|
af371f9c016d
Allow deletion of key-value pairs when merging is done.
Franz Glasner <fzglas.hg@dom66.de>
parents:
243
diff
changeset
|
338 |
| 145 | 339 .. _comments: |
| 340 | |
| 341 Comments | |
| 342 -------- | |
| 343 | |
| 344 By default all keys beginning with ``__comment`` or ``__doc`` are | |
| 345 filtered out and not given to the application. This allows comments in | |
| 346 JSON files -- but is not restricted to JSON files only. | |
| 347 | |
| 348 For all types of configuration files their respective standard comments | |
| 349 are allowed too. | |
| 350 | |
| 351 | |
|
117
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
352 .. _variable-namespaces: |
|
115
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 Variable Namespaces |
|
117
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
355 ------------------- |
|
115
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
356 |
|
316
fe2e28e5fd08
Docu: first short notes about configuration tree references
Franz Glasner <fzglas.hg@dom66.de>
parents:
315
diff
changeset
|
357 Currently there are 6 namespaces: |
|
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 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
|
360 |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
361 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
|
362 |
| 333 | 363 .. seealso:: :ref:`quoting` |
| 364 | |
|
316
fe2e28e5fd08
Docu: first short notes about configuration tree references
Franz Glasner <fzglas.hg@dom66.de>
parents:
315
diff
changeset
|
365 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
|
366 |
|
fe2e28e5fd08
Docu: first short notes about configuration tree references
Franz Glasner <fzglas.hg@dom66.de>
parents:
315
diff
changeset
|
367 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
|
368 |
|
fe2e28e5fd08
Docu: first short notes about configuration tree references
Franz Glasner <fzglas.hg@dom66.de>
parents:
315
diff
changeset
|
369 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
|
370 |
| 682 | 371 Think of them as symbolic links. |
| 372 | |
| 683 | 373 See also chapter `Configuration tree references`_. |
| 374 | |
|
316
fe2e28e5fd08
Docu: first short notes about configuration tree references
Franz Glasner <fzglas.hg@dom66.de>
parents:
315
diff
changeset
|
375 3. The namespace ``OS`` |
|
115
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
376 |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
377 Available functions: |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
378 |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
379 ``cwd`` |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
380 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
|
381 |
|
243
57ff12610dc5
Implemented OS:node to return the host's computername
Franz Glasner <fzglas.hg@dom66.de>
parents:
215
diff
changeset
|
382 ``node`` |
|
57ff12610dc5
Implemented OS:node to return the host's computername
Franz Glasner <fzglas.hg@dom66.de>
parents:
215
diff
changeset
|
383 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
|
384 :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
|
385 |
|
697
57fe110c50c8
Implement a new "SYS" namespace with "prefix", "base_prefix" and "platform"
Franz Glasner <fzglas.hg@dom66.de>
parents:
683
diff
changeset
|
386 4. The namespace ``SYS`` |
|
57fe110c50c8
Implement a new "SYS" namespace with "prefix", "base_prefix" and "platform"
Franz Glasner <fzglas.hg@dom66.de>
parents:
683
diff
changeset
|
387 |
|
57fe110c50c8
Implement a new "SYS" namespace with "prefix", "base_prefix" and "platform"
Franz Glasner <fzglas.hg@dom66.de>
parents:
683
diff
changeset
|
388 Available functions: |
|
57fe110c50c8
Implement a new "SYS" namespace with "prefix", "base_prefix" and "platform"
Franz Glasner <fzglas.hg@dom66.de>
parents:
683
diff
changeset
|
389 |
|
698
3a9d661d33b5
Implement SYS:executable
Franz Glasner <fzglas.hg@dom66.de>
parents:
697
diff
changeset
|
390 ``executable`` |
|
3a9d661d33b5
Implement SYS:executable
Franz Glasner <fzglas.hg@dom66.de>
parents:
697
diff
changeset
|
391 Contains the content of the current running Python's |
|
3a9d661d33b5
Implement SYS:executable
Franz Glasner <fzglas.hg@dom66.de>
parents:
697
diff
changeset
|
392 :py:data:`sys.executable`. |
|
3a9d661d33b5
Implement SYS:executable
Franz Glasner <fzglas.hg@dom66.de>
parents:
697
diff
changeset
|
393 |
|
697
57fe110c50c8
Implement a new "SYS" namespace with "prefix", "base_prefix" and "platform"
Franz Glasner <fzglas.hg@dom66.de>
parents:
683
diff
changeset
|
394 ``prefix`` |
|
57fe110c50c8
Implement a new "SYS" namespace with "prefix", "base_prefix" and "platform"
Franz Glasner <fzglas.hg@dom66.de>
parents:
683
diff
changeset
|
395 Contains the content of the current running Python's |
|
57fe110c50c8
Implement a new "SYS" namespace with "prefix", "base_prefix" and "platform"
Franz Glasner <fzglas.hg@dom66.de>
parents:
683
diff
changeset
|
396 :py:data:`sys.prefix`. |
|
57fe110c50c8
Implement a new "SYS" namespace with "prefix", "base_prefix" and "platform"
Franz Glasner <fzglas.hg@dom66.de>
parents:
683
diff
changeset
|
397 |
|
57fe110c50c8
Implement a new "SYS" namespace with "prefix", "base_prefix" and "platform"
Franz Glasner <fzglas.hg@dom66.de>
parents:
683
diff
changeset
|
398 ``base_prefix`` |
|
57fe110c50c8
Implement a new "SYS" namespace with "prefix", "base_prefix" and "platform"
Franz Glasner <fzglas.hg@dom66.de>
parents:
683
diff
changeset
|
399 Contains the content of the current running Python's |
|
57fe110c50c8
Implement a new "SYS" namespace with "prefix", "base_prefix" and "platform"
Franz Glasner <fzglas.hg@dom66.de>
parents:
683
diff
changeset
|
400 :py:data:`sys.base_prefix`. |
|
57fe110c50c8
Implement a new "SYS" namespace with "prefix", "base_prefix" and "platform"
Franz Glasner <fzglas.hg@dom66.de>
parents:
683
diff
changeset
|
401 |
|
57fe110c50c8
Implement a new "SYS" namespace with "prefix", "base_prefix" and "platform"
Franz Glasner <fzglas.hg@dom66.de>
parents:
683
diff
changeset
|
402 Raises :py:class:`KeyError` if the attribute is not available. |
|
57fe110c50c8
Implement a new "SYS" namespace with "prefix", "base_prefix" and "platform"
Franz Glasner <fzglas.hg@dom66.de>
parents:
683
diff
changeset
|
403 |
|
57fe110c50c8
Implement a new "SYS" namespace with "prefix", "base_prefix" and "platform"
Franz Glasner <fzglas.hg@dom66.de>
parents:
683
diff
changeset
|
404 ``platform`` |
|
57fe110c50c8
Implement a new "SYS" namespace with "prefix", "base_prefix" and "platform"
Franz Glasner <fzglas.hg@dom66.de>
parents:
683
diff
changeset
|
405 Contains the content of the current running Python's |
|
57fe110c50c8
Implement a new "SYS" namespace with "prefix", "base_prefix" and "platform"
Franz Glasner <fzglas.hg@dom66.de>
parents:
683
diff
changeset
|
406 :py:data:`sys.platform`. |
|
57fe110c50c8
Implement a new "SYS" namespace with "prefix", "base_prefix" and "platform"
Franz Glasner <fzglas.hg@dom66.de>
parents:
683
diff
changeset
|
407 |
|
57fe110c50c8
Implement a new "SYS" namespace with "prefix", "base_prefix" and "platform"
Franz Glasner <fzglas.hg@dom66.de>
parents:
683
diff
changeset
|
408 5. The namespace ``ENV`` |
|
115
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
409 |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
410 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
|
411 available from :py:data:`os.environ`. |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
412 |
|
697
57fe110c50c8
Implement a new "SYS" namespace with "prefix", "base_prefix" and "platform"
Franz Glasner <fzglas.hg@dom66.de>
parents:
683
diff
changeset
|
413 6. The namespace ``PY`` |
|
115
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
414 |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
415 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
|
416 |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
417 ``version`` |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
418 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
|
419 |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
420 ``version_maj_min`` |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
421 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
|
422 (``.`` separated) |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
423 |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
424 ``version_maj`` |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
425 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
|
426 |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
427 ``implementation`` |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
428 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
|
429 |
|
697
57fe110c50c8
Implement a new "SYS" namespace with "prefix", "base_prefix" and "platform"
Franz Glasner <fzglas.hg@dom66.de>
parents:
683
diff
changeset
|
430 7. 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
|
431 |
|
da1596034954
Implemented an "AWS" namespace to retrieve some AWS-specific metadata
Franz Glasner <fzglas.hg@dom66.de>
parents:
276
diff
changeset
|
432 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
|
433 AWS: |
|
da1596034954
Implemented an "AWS" namespace to retrieve some AWS-specific metadata
Franz Glasner <fzglas.hg@dom66.de>
parents:
276
diff
changeset
|
434 |
|
da1596034954
Implemented an "AWS" namespace to retrieve some AWS-specific metadata
Franz Glasner <fzglas.hg@dom66.de>
parents:
276
diff
changeset
|
435 ``metadata.instance-id`` |
|
da1596034954
Implemented an "AWS" namespace to retrieve some AWS-specific metadata
Franz Glasner <fzglas.hg@dom66.de>
parents:
276
diff
changeset
|
436 |
|
da1596034954
Implemented an "AWS" namespace to retrieve some AWS-specific metadata
Franz Glasner <fzglas.hg@dom66.de>
parents:
276
diff
changeset
|
437 ``metadata.placement.region`` |
|
da1596034954
Implemented an "AWS" namespace to retrieve some AWS-specific metadata
Franz Glasner <fzglas.hg@dom66.de>
parents:
276
diff
changeset
|
438 |
|
da1596034954
Implemented an "AWS" namespace to retrieve some AWS-specific metadata
Franz Glasner <fzglas.hg@dom66.de>
parents:
276
diff
changeset
|
439 ``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
|
440 |
|
da1596034954
Implemented an "AWS" namespace to retrieve some AWS-specific metadata
Franz Glasner <fzglas.hg@dom66.de>
parents:
276
diff
changeset
|
441 ``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
|
442 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
|
443 (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
|
444 ``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
|
445 et al.). |
|
da1596034954
Implemented an "AWS" namespace to retrieve some AWS-specific metadata
Franz Glasner <fzglas.hg@dom66.de>
parents:
276
diff
changeset
|
446 |
|
115
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
447 |
|
117
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
448 Examples |
|
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
449 ~~~~~~~~ |
|
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
450 |
|
315
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
451 Both :: |
|
117
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
452 |
|
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
453 config.getvar("OS:cwd") |
|
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
454 |
|
315
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
455 or :: |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
456 |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
457 config.getvarl("cwd", namespace="OS") |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
458 |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
459 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
|
460 |
|
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
461 |
|
202
2e66178a09d8
Docu: Ban "keyword expansion" -- use "variable interpolation" instead
Franz Glasner <fzglas.hg@dom66.de>
parents:
200
diff
changeset
|
462 .. _variable-interpolation: |
|
117
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
463 |
|
202
2e66178a09d8
Docu: Ban "keyword expansion" -- use "variable interpolation" instead
Franz Glasner <fzglas.hg@dom66.de>
parents:
200
diff
changeset
|
464 Variable Interpolation |
|
2e66178a09d8
Docu: Ban "keyword expansion" -- use "variable interpolation" instead
Franz Glasner <fzglas.hg@dom66.de>
parents:
200
diff
changeset
|
465 ---------------------- |
|
117
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
466 |
|
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
467 Configuration variable values that are read with |
|
315
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
468 :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
|
469 are subject to variable interpolation. |
|
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
470 The general syntactic pattern for this is:: |
|
117
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
471 |
|
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
472 {{[namespace:]variable[|filter[|filter...]]}} |
|
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
473 |
|
708
e692216f8756
Allow also "," characters to act as a separator within a filter-chain.
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
698
diff
changeset
|
474 or:: |
|
e692216f8756
Allow also "," characters to act as a separator within a filter-chain.
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
698
diff
changeset
|
475 |
|
e692216f8756
Allow also "," characters to act as a separator within a filter-chain.
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
698
diff
changeset
|
476 {{[namespace:]variable[|filter[,filter...]]}} |
|
e692216f8756
Allow also "," characters to act as a separator within a filter-chain.
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
698
diff
changeset
|
477 |
|
117
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
478 I.e.: between double curly braces an optional `namespace` name followed by |
|
708
e692216f8756
Allow also "," characters to act as a separator within a filter-chain.
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
698
diff
changeset
|
479 a colon ``:``, the `variable` and then zero or more filters, the first one |
|
e692216f8756
Allow also "," characters to act as a separator within a filter-chain.
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
698
diff
changeset
|
480 introduced by a pipe symbol ``|`` the following ones introduced by a |
|
e692216f8756
Allow also "," characters to act as a separator within a filter-chain.
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
698
diff
changeset
|
481 comma ``,`` or a pipe symbol ``|``. The comma ``,`` should be preferred. |
|
117
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
482 |
|
202
2e66178a09d8
Docu: Ban "keyword expansion" -- use "variable interpolation" instead
Franz Glasner <fzglas.hg@dom66.de>
parents:
200
diff
changeset
|
483 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
|
484 :py:meth:`.Configuration.getvar_s`, |
|
315
21fa4b4bfdaa
Docu: .getvarl() and .getvarl_s()
Franz Glasner <fzglas.hg@dom66.de>
parents:
308
diff
changeset
|
485 :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
|
486 :py:meth:`.Configuration.substitute_variables_in_obj` or |
|
721
a8bcb22341cd
Docs: FIX: Method name
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
708
diff
changeset
|
487 :py:meth:`.Configuration.interpolate_variables` |
|
117
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
488 |
| 333 | 489 .. note:: Special characters within namespace, key and filter names |
| 490 *must* be quoted (see :ref:`quoting`) when using variable | |
| 491 interpolation syntax. | |
| 492 | |
|
708
e692216f8756
Allow also "," characters to act as a separator within a filter-chain.
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
698
diff
changeset
|
493 .. note:: Commata ``,`` and pipe symbols ``|`` are not allowed within |
|
e692216f8756
Allow also "," characters to act as a separator within a filter-chain.
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
698
diff
changeset
|
494 filter names. |
|
e692216f8756
Allow also "," characters to act as a separator within a filter-chain.
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
698
diff
changeset
|
495 |
|
117
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
496 |
|
115
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
497 Filter functions |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
498 ~~~~~~~~~~~~~~~~ |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
499 |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
500 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
|
501 |
|
708
e692216f8756
Allow also "," characters to act as a separator within a filter-chain.
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
698
diff
changeset
|
502 {{my.variable|filter1|filter2|filter3}} |
|
e692216f8756
Allow also "," characters to act as a separator within a filter-chain.
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
698
diff
changeset
|
503 |
|
e692216f8756
Allow also "," characters to act as a separator within a filter-chain.
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
698
diff
changeset
|
504 or:: |
|
e692216f8756
Allow also "," characters to act as a separator within a filter-chain.
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
698
diff
changeset
|
505 |
|
e692216f8756
Allow also "," characters to act as a separator within a filter-chain.
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
698
diff
changeset
|
506 {{my.variable|filter1,filter2,filter3}} |
|
115
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
507 |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
508 Available filter functions are: |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
509 |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
510 ``urlquote`` |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
511 |
|
347
d7daec119383
New filter function "urlquote_plus" which quotes a space into a '+' character
Franz Glasner <fzglas.hg@dom66.de>
parents:
343
diff
changeset
|
512 ``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
|
513 |
|
115
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
514 ``saslprep`` |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
515 |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
516 ``normpath`` |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
517 |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
518 ``abspath`` |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
519 |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
520 ``posixpath`` |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
521 |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
522 ``lower`` |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
523 |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
524 ``upper`` |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
525 |
|
353
a7491f835cb0
Changelog and minimal docu for `None` and `Empty` filters
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
347
diff
changeset
|
526 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
|
527 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
|
528 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
|
529 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
|
530 |
|
115
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
531 |
|
723
c17a4e30ebbf
Docs for nested filters
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
721
diff
changeset
|
532 Nested Interpolation (Filtering Only) |
|
c17a4e30ebbf
Docs for nested filters
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
721
diff
changeset
|
533 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
c17a4e30ebbf
Docs for nested filters
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
721
diff
changeset
|
534 |
|
c17a4e30ebbf
Docs for nested filters
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
721
diff
changeset
|
535 Generally, nested interpolation does *not* work. Something like |
|
c17a4e30ebbf
Docs for nested filters
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
721
diff
changeset
|
536 ``{{{{variable}}}}`` does not work. |
|
c17a4e30ebbf
Docs for nested filters
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
721
diff
changeset
|
537 |
|
c17a4e30ebbf
Docs for nested filters
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
721
diff
changeset
|
538 Also something like ``{{{{path-variable|Empty}}/subdir|normpath}}`` does not |
|
c17a4e30ebbf
Docs for nested filters
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
721
diff
changeset
|
539 work as expected: `path-variable` would not get interpolated and `Empty` |
|
c17a4e30ebbf
Docs for nested filters
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
721
diff
changeset
|
540 not be applied. |
|
c17a4e30ebbf
Docs for nested filters
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
721
diff
changeset
|
541 |
|
c17a4e30ebbf
Docs for nested filters
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
721
diff
changeset
|
542 But -- as a special case -- a simplified form of nested evaluation is |
|
c17a4e30ebbf
Docs for nested filters
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
721
diff
changeset
|
543 implemented for filters only. Instead of using the start tag ``{{`` and end |
|
c17a4e30ebbf
Docs for nested filters
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
721
diff
changeset
|
544 tag ``}}`` it uses the special start tag ``{{|`` and end tag ``|}}``. |
|
c17a4e30ebbf
Docs for nested filters
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
721
diff
changeset
|
545 |
|
c17a4e30ebbf
Docs for nested filters
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
721
diff
changeset
|
546 |
|
c17a4e30ebbf
Docs for nested filters
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
721
diff
changeset
|
547 With the syntax:: |
|
c17a4e30ebbf
Docs for nested filters
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
721
diff
changeset
|
548 |
|
725
11e24e1bbf20
Docs: Introduce the new nested interpolation with filters
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
723
diff
changeset
|
549 {{|<expression with variables (including filters)>|filter1[,filter2...]|}} |
|
723
c17a4e30ebbf
Docs for nested filters
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
721
diff
changeset
|
550 |
|
725
11e24e1bbf20
Docs: Introduce the new nested interpolation with filters
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
723
diff
changeset
|
551 The ``<expression with variables (including filers)`` is interpolated |
|
11e24e1bbf20
Docs: Introduce the new nested interpolation with filters
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
723
diff
changeset
|
552 first, and the complete result is feeded into the filter chain, |
|
11e24e1bbf20
Docs: Introduce the new nested interpolation with filters
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
723
diff
changeset
|
553 beginning with ``filter1``. |
|
11e24e1bbf20
Docs: Introduce the new nested interpolation with filters
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
723
diff
changeset
|
554 |
|
727
3686bad61391
Docs: Notes on chaining filters in nested filter interpolation
Franz Glasner <fzglas.hg@dom66.de>
parents:
725
diff
changeset
|
555 .. note:: Chaining filters is allowed only with the comma ``,`` as separating |
|
3686bad61391
Docs: Notes on chaining filters in nested filter interpolation
Franz Glasner <fzglas.hg@dom66.de>
parents:
725
diff
changeset
|
556 symbol. Using the pipe symbol ``|`` is not supported. |
|
3686bad61391
Docs: Notes on chaining filters in nested filter interpolation
Franz Glasner <fzglas.hg@dom66.de>
parents:
725
diff
changeset
|
557 |
|
725
11e24e1bbf20
Docs: Introduce the new nested interpolation with filters
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
723
diff
changeset
|
558 With this, the non-working example above can be expressed as |
|
723
c17a4e30ebbf
Docs for nested filters
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
721
diff
changeset
|
559 ``{{|{{path-variable|Empty}}/subdir|normpath|}}`` |
|
c17a4e30ebbf
Docs for nested filters
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
721
diff
changeset
|
560 and yields the expected result -- with `normpath` applied to the now |
|
c17a4e30ebbf
Docs for nested filters
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
721
diff
changeset
|
561 interpolated expression. |
|
c17a4e30ebbf
Docs for nested filters
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
721
diff
changeset
|
562 |
|
c17a4e30ebbf
Docs for nested filters
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
721
diff
changeset
|
563 |
|
115
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
564 Examples |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
565 ~~~~~~~~ |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
566 |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
567 :: |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
568 |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
569 {{OS:cwd|posixpath}} |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
570 |
|
117
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
571 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
|
572 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
|
573 |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
574 :: |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
575 |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
576 {{ENV:PATH}} |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
577 |
|
117
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
578 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
|
579 |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
580 :: |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
581 |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
582 {{PY:version}} |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
583 |
|
117
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
584 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
|
585 |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
586 :: |
|
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
587 |
|
328
cffa4fcd0a4d
Docu: syntax fix in example
Franz Glasner <fzglas.hg@dom66.de>
parents:
316
diff
changeset
|
588 {{PY:implementation|upper}} |
|
115
a5339d39af5c
Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents:
114
diff
changeset
|
589 |
|
117
c5b638f9c607
- More on getting variable values
Franz Glasner <hg@dom66.de>
parents:
115
diff
changeset
|
590 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
|
591 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
|
592 |
|
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
|
593 |
|
316
fe2e28e5fd08
Docu: first short notes about configuration tree references
Franz Glasner <fzglas.hg@dom66.de>
parents:
315
diff
changeset
|
594 Configuration tree references |
|
fe2e28e5fd08
Docu: first short notes about configuration tree references
Franz Glasner <fzglas.hg@dom66.de>
parents:
315
diff
changeset
|
595 ----------------------------- |
|
fe2e28e5fd08
Docu: first short notes about configuration tree references
Franz Glasner <fzglas.hg@dom66.de>
parents:
315
diff
changeset
|
596 |
| 683 | 597 Syntax is ``{{ref:#my.other.key}}``. |
|
316
fe2e28e5fd08
Docu: first short notes about configuration tree references
Franz Glasner <fzglas.hg@dom66.de>
parents:
315
diff
changeset
|
598 |
| 683 | 599 - Think of it as a sort of a symbolic link to other parts of the |
| 600 configuration tree. | |
| 601 - They occupy the special namespace ``ref``. | |
| 602 - Note that they 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
|
603 - No special handling when merging is done -- merging is agnostic of |
| 683 | 604 tree references. |
|
353
a7491f835cb0
Changelog and minimal docu for `None` and `Empty` filters
Franz Glasner <f.glasner@feldmann-mg.com>
parents:
347
diff
changeset
|
605 - 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
|
606 :py:meth:`.Configuration.getvar`, :py:meth:`.Configuration.getvarl` |
| 683 | 607 and :py:meth:`.Configuration.getvarl_s` are handled. |
| 608 - In :py:meth:`.Configuration.getvar` a reference handled only when it | |
| 609 is the directly referenced value | |
| 610 - Recursive expansion in :py:meth:`.Configuration.getvar_s` and | |
|
343
c8b98285a7b5
docs: some more docu for tree references
Franz Glasner <fzglas.hg@dom66.de>
parents:
341
diff
changeset
|
611 :py:meth:`.Configuration.getvarl_s`: |
| 683 | 612 beware of recursive (direct or indirect) tree references. |
| 613 - References do work as root paths of `Jailed Configurations`_. | |
| 333 | 614 |
| 615 | |
| 616 .. _quoting: | |
| 617 | |
| 618 Quoting | |
| 619 ------- | |
| 620 | |
| 621 When using :py:meth:`.Configuration.getvar` and | |
| 622 :py:meth:`.Configuration.getvar_s` and when retrieving values in the | |
| 623 default namespace the namespace separator ``:`` or the hierarchy | |
| 624 separator ``.`` are characters with a special meaning. When using | |
| 625 :ref:`variable interpolation <variable-interpolation>` the filter | |
| 339 | 626 separator ``|`` is also special. To use them in key names they must be |
| 333 | 627 quoted. |
| 628 | |
| 629 Quoting is done with a variant of the well-known percent-encoding in | |
| 630 URIs (:rfc:`3986`). | |
| 631 | |
| 632 A percent-encoded character consists of the percent character ``%``, | |
| 633 followed by one of the characters ``x``, ``u`` or ``U``, followed by | |
| 634 the two, four or eight hexadecimal digits of the unicode codepoint | |
| 635 value of the character that is to be quoted. ``x`` must be followed by | |
| 636 two hex digits, ``u`` by four and ``U`` by eight. | |
| 637 | |
| 638 Example: | |
| 639 | |
| 640 The character ``.`` with the Unicode (and ASCII) value 46 (hex 0x2e) | |
| 641 can be encoded as ``%x2e`` or ``%u002e`` or ``%U0000002e``. | |
| 642 | |
| 643 .. note:: Filters neeed no quoting -- and quoting within filters is *not* | |
| 644 supported. | |
|
316
fe2e28e5fd08
Docu: first short notes about configuration tree references
Franz Glasner <fzglas.hg@dom66.de>
parents:
315
diff
changeset
|
645 |
|
340
176e22110fc5
docs, tests: notes and additional tests when quoting the "ref" namespace name
Franz Glasner <fzglas.hg@dom66.de>
parents:
339
diff
changeset
|
646 .. 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
|
647 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
|
648 |
|
316
fe2e28e5fd08
Docu: first short notes about configuration tree references
Franz Glasner <fzglas.hg@dom66.de>
parents:
315
diff
changeset
|
649 |
| 400 | 650 .. _jailed-configuration: |
| 651 | |
| 652 Jailed Configurations | |
| 653 --------------------- | |
| 654 | |
| 655 With :meth:`configmix.config.Configuration.jailed` you get a `jailed` | |
| 656 (or `restricted`) configuration from a "normal" configuration. | |
| 657 | |
| 658 Restriction is two-fold: | |
| 659 | |
| 660 - The access to configuration variables in `config` is restricted | |
| 661 to the configuration sub-tree that is configured in `path`. | |
| 662 | |
| 663 - Not all access-methods of :class:`Configuration` are implemented | |
| 664 yet. | |
| 665 | |
| 666 This is somewhat analogous to a `chroot` environment for filesystems. | |
| 667 | |
| 668 .. note:: The word "jail" is shamelessly stolen from FreeBSD jails. | |
| 669 | |
| 670 Usage example:: | |
| 671 | |
| 672 import configmix | |
| 673 | |
| 674 config = configmix.load("conf10.py") | |
|
426
84d4f82ffe59
Docs: more on jails and sub-jails
Franz Glasner <fzglas.hg@dom66.de>
parents:
425
diff
changeset
|
675 assert not config.is_jail |
| 400 | 676 value = config.getvar_s("tree1.tree2.key4") |
| 677 | |
| 678 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
|
679 assert jailed_config1.is_jail |
|
84d4f82ffe59
Docs: more on jails and sub-jails
Franz Glasner <fzglas.hg@dom66.de>
parents:
425
diff
changeset
|
680 assert jailed_config1.base is config |
| 400 | 681 jvalue1 = jailed_config1.getvar_s("key4") |
| 682 | |
| 683 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
|
684 assert jailed_config2.is_jail |
|
84d4f82ffe59
Docs: more on jails and sub-jails
Franz Glasner <fzglas.hg@dom66.de>
parents:
425
diff
changeset
|
685 assert jailed_config2.base is config |
| 400 | 686 jvalue2 = jailed_config.getvarl_s("key4") |
| 687 | |
| 688 assert value == jvalue1 == jvalue2 == "get this as `tree1.tree2.key4'" | |
| 689 | |
| 690 `jvalue1` and `jvalue2` (and `value`) yield the very same value | |
| 691 ``get this as `tree1.tree2.key4'`` from the configuration. | |
| 692 | |
| 693 All access methods in a jailed configuration automatically prepend the | |
| 694 given `root path` in order to get the effective key into the base | |
| 695 configuration. | |
| 696 | |
|
424
e60b72df15de
Introduction into sub-jails
Franz Glasner <fzglas.hg@dom66.de>
parents:
400
diff
changeset
|
697 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
|
698 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
|
699 the jailed configuration by default. |
|
84d4f82ffe59
Docs: more on jails and sub-jails
Franz Glasner <fzglas.hg@dom66.de>
parents:
425
diff
changeset
|
700 |
|
84d4f82ffe59
Docs: more on jails and sub-jails
Franz Glasner <fzglas.hg@dom66.de>
parents:
425
diff
changeset
|
701 :: |
|
424
e60b72df15de
Introduction into sub-jails
Franz Glasner <fzglas.hg@dom66.de>
parents:
400
diff
changeset
|
702 |
|
e60b72df15de
Introduction into sub-jails
Franz Glasner <fzglas.hg@dom66.de>
parents:
400
diff
changeset
|
703 import configmix |
|
e60b72df15de
Introduction into sub-jails
Franz Glasner <fzglas.hg@dom66.de>
parents:
400
diff
changeset
|
704 |
|
e60b72df15de
Introduction into sub-jails
Franz Glasner <fzglas.hg@dom66.de>
parents:
400
diff
changeset
|
705 config = configmix.load("conf10.py") |
|
426
84d4f82ffe59
Docs: more on jails and sub-jails
Franz Glasner <fzglas.hg@dom66.de>
parents:
425
diff
changeset
|
706 assert not config.is_jail |
|
424
e60b72df15de
Introduction into sub-jails
Franz Glasner <fzglas.hg@dom66.de>
parents:
400
diff
changeset
|
707 value = config.getvar_s("tree1.tree2.key4") |
|
e60b72df15de
Introduction into sub-jails
Franz Glasner <fzglas.hg@dom66.de>
parents:
400
diff
changeset
|
708 |
|
e60b72df15de
Introduction into sub-jails
Franz Glasner <fzglas.hg@dom66.de>
parents:
400
diff
changeset
|
709 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
|
710 assert jailed_config1.is_jail |
|
84d4f82ffe59
Docs: more on jails and sub-jails
Franz Glasner <fzglas.hg@dom66.de>
parents:
425
diff
changeset
|
711 assert jailed_config2.base is config |
|
424
e60b72df15de
Introduction into sub-jails
Franz Glasner <fzglas.hg@dom66.de>
parents:
400
diff
changeset
|
712 |
|
e60b72df15de
Introduction into sub-jails
Franz Glasner <fzglas.hg@dom66.de>
parents:
400
diff
changeset
|
713 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
|
714 assert jailed_config2.is_jail |
|
84d4f82ffe59
Docs: more on jails and sub-jails
Franz Glasner <fzglas.hg@dom66.de>
parents:
425
diff
changeset
|
715 assert jailed_config2.base is config |
|
424
e60b72df15de
Introduction into sub-jails
Franz Glasner <fzglas.hg@dom66.de>
parents:
400
diff
changeset
|
716 jvalue2 = jailed_config.getvarl_s("key4") |
|
e60b72df15de
Introduction into sub-jails
Franz Glasner <fzglas.hg@dom66.de>
parents:
400
diff
changeset
|
717 |
|
e60b72df15de
Introduction into sub-jails
Franz Glasner <fzglas.hg@dom66.de>
parents:
400
diff
changeset
|
718 assert value == jvalue2 == "get this as `tree1.tree2.key4'" |
|
e60b72df15de
Introduction into sub-jails
Franz Glasner <fzglas.hg@dom66.de>
parents:
400
diff
changeset
|
719 |
|
425
88d8de9310af
Docs: jails hold strong references to the unjailed base configuration
Franz Glasner <fzglas.hg@dom66.de>
parents:
424
diff
changeset
|
720 .. 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
|
721 base configuration. |
|
88d8de9310af
Docs: jails hold strong references to the unjailed base configuration
Franz Glasner <fzglas.hg@dom66.de>
parents:
424
diff
changeset
|
722 |
| 682 | 723 .. note:: If a jail's root path points to a location with a variable |
| 724 substitutions the jail does not work: it is not possible to | |
| 725 expand the substitution. | |
| 726 | |
| 727 Using ``ref`` namespaces instead works: think of | |
| 728 symbolic links. | |
| 729 | |
| 400 | 730 |
|
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
|
731 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
|
732 --------------------------------------------- |
|
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
|
733 |
|
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
|
734 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
|
735 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
|
736 |
|
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
|
737 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
|
738 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
|
739 |
|
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
|
740 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
|
741 |
|
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
|
742 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
|
743 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
|
744 |
|
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
|
745 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
|
746 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
|
747 |
|
194
0d8dd58afc44
Docu: Enhanced the custom loader section somewhat
Franz Glasner <fzglas.hg@dom66.de>
parents:
193
diff
changeset
|
748 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
|
749 |
|
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
|
750 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
|
751 ... |
|
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
|
752 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
|
753 |
|
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
|
754 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
|
755 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
|
756 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
|
757 |
|
0d8dd58afc44
Docu: Enhanced the custom loader section somewhat
Franz Glasner <fzglas.hg@dom66.de>
parents:
193
diff
changeset
|
758 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
|
759 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
|
760 |
|
fa660f084ceb
Docu: an example for configmix.try_determine_filemode()
Franz Glasner <fzglas.hg@dom66.de>
parents:
202
diff
changeset
|
761 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
|
762 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
|
763 |
|
fa660f084ceb
Docu: an example for configmix.try_determine_filemode()
Franz Glasner <fzglas.hg@dom66.de>
parents:
202
diff
changeset
|
764 configmix.set_assoc("*", configmix.try_determine_filemode) |