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