Mercurial > hgrepos > Python > libs > ConfigMix

annotate docs/introduction.rst @ 284:4aaf74858d07

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Some links to AWS docu into the aws moduleSome links to AWS docu into the aws moduleSome links to AWS docu into the aws moduleSome links to AWS docu into the aws moduleSome links to AWS docu into the aws moduleSome links to AWS docu into the aws moduleSome links to AWS docu into the aws moduleSome links to AWS docu into the aws module
author Franz Glasner <fzglas.hg@dom66.de>
date Mon, 07 Dec 2020 01:59:11 +0100
parents da1596034954
children 28aa21095a68
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
94
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
1 .. -*- coding: utf-8; indent-tabs-mode: nil; -*-
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
2
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
3 .. _introduction:
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
4
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
5 Introduction
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
6 ============
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
7
161
4643763b39ee Docu: print a local table of contents in the introduction
Franz Glasner <fzglas.hg@dom66.de>
parents: 158
diff changeset
8 .. contents::
4643763b39ee Docu: print a local table of contents in the introduction
Franz Glasner <fzglas.hg@dom66.de>
parents: 158
diff changeset
9 :local:
4643763b39ee Docu: print a local table of contents in the introduction
Franz Glasner <fzglas.hg@dom66.de>
parents: 158
diff changeset
10
94
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
11 The configurations can be read from different types of files:
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
12
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
13 - :ref:`YAML files <yaml-files>`
131
b34ad08e7198 Document the JSON files
Franz Glasner <hg@dom66.de>
parents: 122
diff changeset
14 - :ref:`JSON files <json-files>`
94
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
15 - :ref:`INI files <ini-files>`
195
28e6c1413947 Added support for TOML style configuration files
Franz Glasner <fzglas.hg@dom66.de>
parents: 194
diff changeset
16 - :ref:`TOML files <toml-files>`
94
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
17 - :ref:`executable Python scripts <executable-python-scripts>`
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
18
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
19
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
20 .. _yaml-files:
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
21
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
22 YAML Files
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
23 ----------
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
24
200
c6904d02beae Doc: some wording
Franz Glasner <fzglas.hg@dom66.de>
parents: 195
diff changeset
25 Need the :mod:`yaml` package (https://github.com/yaml/pyyaml)
c6904d02beae Doc: some wording
Franz Glasner <fzglas.hg@dom66.de>
parents: 195
diff changeset
26 (e.g. ``pip install pyyaml``)
94
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
27
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
28 .. note:: All strings are returned as Unicode text strings.
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
29
134
2f2e819e8d17 Check the return type of the JSON and YAML loading functions: they must be a dict alike
Franz Glasner <hg@dom66.de>
parents: 133
diff changeset
30 .. note:: The root object must be a *mapping* and therefore decode
2f2e819e8d17 Check the return type of the JSON and YAML loading functions: they must be a dict alike
Franz Glasner <hg@dom66.de>
parents: 133
diff changeset
31 into a Python :class:`dict` alike. This is checked by the
2f2e819e8d17 Check the return type of the JSON and YAML loading functions: they must be a dict alike
Franz Glasner <hg@dom66.de>
parents: 133
diff changeset
32 implementation.
94
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
33
97
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents: 94
diff changeset
34 An example is:
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents: 94
diff changeset
35
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents: 94
diff changeset
36 .. literalinclude:: ../tests/data/conf10.yml
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents: 94
diff changeset
37 :language: yaml
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents: 94
diff changeset
38
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents: 94
diff changeset
39
122
21d92ff8cf31 Begin the handling of JSON-style configuration files
Franz Glasner <hg@dom66.de>
parents: 117
diff changeset
40 .. _json-files:
21d92ff8cf31 Begin the handling of JSON-style configuration files
Franz Glasner <hg@dom66.de>
parents: 117
diff changeset
41
21d92ff8cf31 Begin the handling of JSON-style configuration files
Franz Glasner <hg@dom66.de>
parents: 117
diff changeset
42 JSON files
21d92ff8cf31 Begin the handling of JSON-style configuration files
Franz Glasner <hg@dom66.de>
parents: 117
diff changeset
43 ----------
21d92ff8cf31 Begin the handling of JSON-style configuration files
Franz Glasner <hg@dom66.de>
parents: 117
diff changeset
44
131
b34ad08e7198 Document the JSON files
Franz Glasner <hg@dom66.de>
parents: 122
diff changeset
45 Read the JSON file with the help of Python's native :mod:`json` package.
b34ad08e7198 Document the JSON files
Franz Glasner <hg@dom66.de>
parents: 122
diff changeset
46
b34ad08e7198 Document the JSON files
Franz Glasner <hg@dom66.de>
parents: 122
diff changeset
47 .. note:: All strings are returned as Unicode text strings.
b34ad08e7198 Document the JSON files
Franz Glasner <hg@dom66.de>
parents: 122
diff changeset
48
134
2f2e819e8d17 Check the return type of the JSON and YAML loading functions: they must be a dict alike
Franz Glasner <hg@dom66.de>
parents: 133
diff changeset
49 .. note:: The root object must be an *object* and therefore decode
2f2e819e8d17 Check the return type of the JSON and YAML loading functions: they must be a dict alike
Franz Glasner <hg@dom66.de>
parents: 133
diff changeset
50 into a Python :class:`dict` alike. This is checked by the
2f2e819e8d17 Check the return type of the JSON and YAML loading functions: they must be a dict alike
Franz Glasner <hg@dom66.de>
parents: 133
diff changeset
51 implementation.
131
b34ad08e7198 Document the JSON files
Franz Glasner <hg@dom66.de>
parents: 122
diff changeset
52
b34ad08e7198 Document the JSON files
Franz Glasner <hg@dom66.de>
parents: 122
diff changeset
53 An example is:
b34ad08e7198 Document the JSON files
Franz Glasner <hg@dom66.de>
parents: 122
diff changeset
54
b34ad08e7198 Document the JSON files
Franz Glasner <hg@dom66.de>
parents: 122
diff changeset
55 .. literalinclude:: ../tests/data/conf10.json
b34ad08e7198 Document the JSON files
Franz Glasner <hg@dom66.de>
parents: 122
diff changeset
56 :language: js
122
21d92ff8cf31 Begin the handling of JSON-style configuration files
Franz Glasner <hg@dom66.de>
parents: 117
diff changeset
57
145
d44ee758e31b Some docu on comments in files
Franz Glasner <hg@dom66.de>
parents: 142
diff changeset
58 For comments in JSON files see section :ref:`comments`.
d44ee758e31b Some docu on comments in files
Franz Glasner <hg@dom66.de>
parents: 142
diff changeset
59
122
21d92ff8cf31 Begin the handling of JSON-style configuration files
Franz Glasner <hg@dom66.de>
parents: 117
diff changeset
60
94
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
61 .. _ini-files:
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
62
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
63 INI Files
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
64 ---------
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
65
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
66 Read the file and all sections named in parameter `extract` are flattened
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
67 into the resulting dictionary. By default the section named ``config`` is
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
68 used.
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
69
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
70 Normally all values are returned as Unicode text strings.
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
71 But values can be annotated and therefore interpreted as other types:
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
72
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
73 ``:int:``
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
74 The value is handled in the same way as a Python :class:`int`
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
75 literal
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
76
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
77 ``:float:``
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
78 The value is interpreted as :class:`float`
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
79
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
80 ``:bool:``
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
81 The resulting value is a :class:`bool` where
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
82
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
83 ``1``, ``true``, ``yes``, ``on``
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
84 yield a Python ``True``
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
85
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
86 ``0``, ``false``, ``no``, ``off``
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
87 yield a Python ``False``
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
88
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
89 The evaluation is done *case-insensitively*.
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
90
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
91 .. note:: All strings are returned as Unicode text strings.
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
92
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
93 .. note:: Contrary to the behaviour of the standard Python :mod:`configparser`
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
94 module the INI file reader is *case-sensitive*.
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
95
97
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents: 94
diff changeset
96 The example INI style configuration below yields an equivalent
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents: 94
diff changeset
97 configuration to the YAML configuration above:
94
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
98
97
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents: 94
diff changeset
99 .. literalinclude:: ../tests/data/conf10.ini
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents: 94
diff changeset
100 :language: ini
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents: 94
diff changeset
101
133
05cb18c8697a FIX: Typo
Franz Glasner <hg@dom66.de>
parents: 132
diff changeset
102 As can be seen in this example -- INI file internal value interpolation
97
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents: 94
diff changeset
103 is done as in Python's standard :mod:`configparser` module.
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents: 94
diff changeset
104
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents: 94
diff changeset
105 This example also illustrates how INI sections are used to build a
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents: 94
diff changeset
106 tree-ish configuration dictionary.
94
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
107
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
108
195
28e6c1413947 Added support for TOML style configuration files
Franz Glasner <fzglas.hg@dom66.de>
parents: 194
diff changeset
109 .. _toml-files:
28e6c1413947 Added support for TOML style configuration files
Franz Glasner <fzglas.hg@dom66.de>
parents: 194
diff changeset
110
28e6c1413947 Added support for TOML style configuration files
Franz Glasner <fzglas.hg@dom66.de>
parents: 194
diff changeset
111 TOML Files
28e6c1413947 Added support for TOML style configuration files
Franz Glasner <fzglas.hg@dom66.de>
parents: 194
diff changeset
112 ----------
28e6c1413947 Added support for TOML style configuration files
Franz Glasner <fzglas.hg@dom66.de>
parents: 194
diff changeset
113
200
c6904d02beae Doc: some wording
Franz Glasner <fzglas.hg@dom66.de>
parents: 195
diff changeset
114 Read the TOML file with the help of the pure Python :mod:`toml`
c6904d02beae Doc: some wording
Franz Glasner <fzglas.hg@dom66.de>
parents: 195
diff changeset
115 package (https://github.com/uiri/toml) (e.g. ``pip install toml``).
195
28e6c1413947 Added support for TOML style configuration files
Franz Glasner <fzglas.hg@dom66.de>
parents: 194
diff changeset
116
28e6c1413947 Added support for TOML style configuration files
Franz Glasner <fzglas.hg@dom66.de>
parents: 194
diff changeset
117 All TOML features map seamingless to "ConfigMix".
28e6c1413947 Added support for TOML style configuration files
Franz Glasner <fzglas.hg@dom66.de>
parents: 194
diff changeset
118
28e6c1413947 Added support for TOML style configuration files
Franz Glasner <fzglas.hg@dom66.de>
parents: 194
diff changeset
119 The example TOML style configuration below yields an equivalent
28e6c1413947 Added support for TOML style configuration files
Franz Glasner <fzglas.hg@dom66.de>
parents: 194
diff changeset
120 configuration to the YAML configuration above:
28e6c1413947 Added support for TOML style configuration files
Franz Glasner <fzglas.hg@dom66.de>
parents: 194
diff changeset
121
28e6c1413947 Added support for TOML style configuration files
Franz Glasner <fzglas.hg@dom66.de>
parents: 194
diff changeset
122
28e6c1413947 Added support for TOML style configuration files
Franz Glasner <fzglas.hg@dom66.de>
parents: 194
diff changeset
123 .. literalinclude:: ../tests/data/conf10.toml
28e6c1413947 Added support for TOML style configuration files
Franz Glasner <fzglas.hg@dom66.de>
parents: 194
diff changeset
124 :language: ini
28e6c1413947 Added support for TOML style configuration files
Franz Glasner <fzglas.hg@dom66.de>
parents: 194
diff changeset
125
28e6c1413947 Added support for TOML style configuration files
Franz Glasner <fzglas.hg@dom66.de>
parents: 194
diff changeset
126
94
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
127 .. _executable-python-scripts:
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
128
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
129 Executable Python Scripts
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
130 -------------------------
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
131
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
132 What will be exported:
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
133
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
134 1. If loading is done with the `extract` parameter only the given keys are
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
135 extracted from the script.
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
136
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
137 2. Otherwise it is checked if the scripts defines an ``__all__``
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
138 sequence. If there is one it's contents are the keys to be
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
139 extracted.
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
140
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
141 3. If there is no ``__all__`` object all names not starting with an
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
142 underscore ``_`` are found.
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
143
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
144 This is analogous to as Python modules behave when importing them with
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
145 ``from module import *``.
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
146
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
147 .. note:: The Python configuration files are evaluated with ``exec`` and not
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
148 imported.
97
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents: 94
diff changeset
149
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents: 94
diff changeset
150 The example configuration by Python script below yields an equivalent
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents: 94
diff changeset
151 configuration to the YAML configuration above:
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents: 94
diff changeset
152
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents: 94
diff changeset
153 .. literalinclude:: ../tests/data/conf10.py
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents: 94
diff changeset
154 :language: python
114
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
155
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
156
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
157 .. _loading-and-merging:
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
158
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
159 Loading and Merging
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
160 -------------------
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
161
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
162 Basic usage of the API is as follows in this example::
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
163
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
164 import configmix
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
165
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
166 #
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
167 # Note: With conf10 merging is rather pointless because the tree
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
168 # files # are really the same configuration. But is doesn't harm
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
169 # also here.
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
170 #
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
171 config = configmix.load("conf10.yml", "conf10.ini", "conf10.py")
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
172
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
173 # Get a -- possibly interpolated -- configuration variable's value
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
174 value1 = config.getvar_s("key1")
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
175
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
176 # Get a -- possibly interpolated -- variable from within the tree
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
177 value2 = config.getvar_s("tree1.tree2.key4")
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
178
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
179
139
c87b0dc54e1d Allow custom configuration filename extensions and custom loaders that can handle custom configuration file syntax styles
Franz Glasner <hg@dom66.de>
parents: 134
diff changeset
180 By default filenames of the configuration files must have the extensions
193
70c4f81ac58c FIX: Docu: Case-sensitivety of filename extension matching depends on the OS now
Franz Glasner <fzglas.hg@dom66.de>
parents: 190
diff changeset
181 (case-sensitivety depends on your OS):
114
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
182
142
fc2bd73f9e98 Sort extension list in the docu
Franz Glasner <hg@dom66.de>
parents: 139
diff changeset
183 ``.ini``
fc2bd73f9e98 Sort extension list in the docu
Franz Glasner <hg@dom66.de>
parents: 139
diff changeset
184 for INI configuration files
fc2bd73f9e98 Sort extension list in the docu
Franz Glasner <hg@dom66.de>
parents: 139
diff changeset
185
fc2bd73f9e98 Sort extension list in the docu
Franz Glasner <hg@dom66.de>
parents: 139
diff changeset
186 ``.json``
fc2bd73f9e98 Sort extension list in the docu
Franz Glasner <hg@dom66.de>
parents: 139
diff changeset
187 for JSON configuration files
fc2bd73f9e98 Sort extension list in the docu
Franz Glasner <hg@dom66.de>
parents: 139
diff changeset
188
114
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
189 ``.py``
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
190 for Python configuration files
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
191
195
28e6c1413947 Added support for TOML style configuration files
Franz Glasner <fzglas.hg@dom66.de>
parents: 194
diff changeset
192 ``.toml``
28e6c1413947 Added support for TOML style configuration files
Franz Glasner <fzglas.hg@dom66.de>
parents: 194
diff changeset
193 for TOML configuration file
28e6c1413947 Added support for TOML style configuration files
Franz Glasner <fzglas.hg@dom66.de>
parents: 194
diff changeset
194
114
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
195 ``.yml`` or ``.yaml``
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
196 for YAML configuration files
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
197
115
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
198
117
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
199 .. _getting-values:
115
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
200
117
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
201 Getting configuration variables
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
202 -------------------------------
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
203
202
2e66178a09d8 Docu: Ban "keyword expansion" -- use "variable interpolation" instead
Franz Glasner <fzglas.hg@dom66.de>
parents: 200
diff changeset
204 Get a -- possibly interpolated -- configuration variable's value with::
115
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
205
117
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
206 value1 = config.getvar_s("key1")
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
207
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
208 Get a raw configuration variable's value with::
115
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
209
117
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
210 value1_raw = config.getvar("key1")
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
211
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
212 Because the configuration is not only a plain list of but a tree of
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
213 key-value pairs you will want to fetch them by separating the individual
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
214 level keys with a point ``.``.
115
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
215
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
216 Looking at the example in chapter :ref:`yaml-files` -- when calling
117
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
217 ``config.getvar_s("tree1.tree2.key4")`` you will get the value
115
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
218 ``get this as `tree1.tree2.key4'``.
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
219
117
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
220 This is true for both methods :py:meth:`.Configuration.getvar` and
115
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
221 :py:meth:`.Configuration.getvar_s`.
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
222
202
2e66178a09d8 Docu: Ban "keyword expansion" -- use "variable interpolation" instead
Franz Glasner <fzglas.hg@dom66.de>
parents: 200
diff changeset
223 Both methods also perform :ref:`variable-interpolation` and handle
117
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
224 :ref:`variable-namespaces`. Filtering is not supported. So -- the
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
225 variable name arguments of :py:meth:`.Configuration.getvar` and
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
226 :py:meth:`.Configuration.getvar_s` are of the form
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
227 ``[namespace:]variable``.
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
228
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
229
276
af371f9c016d Allow deletion of key-value pairs when merging is done.
Franz Glasner <fzglas.hg@dom66.de>
parents: 243
diff changeset
230 .. _merging-deletions:
af371f9c016d Allow deletion of key-value pairs when merging is done.
Franz Glasner <fzglas.hg@dom66.de>
parents: 243
diff changeset
231
af371f9c016d Allow deletion of key-value pairs when merging is done.
Franz Glasner <fzglas.hg@dom66.de>
parents: 243
diff changeset
232 Deletions
af371f9c016d Allow deletion of key-value pairs when merging is done.
Franz Glasner <fzglas.hg@dom66.de>
parents: 243
diff changeset
233 ---------
af371f9c016d Allow deletion of key-value pairs when merging is done.
Franz Glasner <fzglas.hg@dom66.de>
parents: 243
diff changeset
234
af371f9c016d Allow deletion of key-value pairs when merging is done.
Franz Glasner <fzglas.hg@dom66.de>
parents: 243
diff changeset
235 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
236 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
237
af371f9c016d Allow deletion of key-value pairs when merging is done.
Franz Glasner <fzglas.hg@dom66.de>
parents: 243
diff changeset
238
145
d44ee758e31b Some docu on comments in files
Franz Glasner <hg@dom66.de>
parents: 142
diff changeset
239 .. _comments:
d44ee758e31b Some docu on comments in files
Franz Glasner <hg@dom66.de>
parents: 142
diff changeset
240
d44ee758e31b Some docu on comments in files
Franz Glasner <hg@dom66.de>
parents: 142
diff changeset
241 Comments
d44ee758e31b Some docu on comments in files
Franz Glasner <hg@dom66.de>
parents: 142
diff changeset
242 --------
d44ee758e31b Some docu on comments in files
Franz Glasner <hg@dom66.de>
parents: 142
diff changeset
243
d44ee758e31b Some docu on comments in files
Franz Glasner <hg@dom66.de>
parents: 142
diff changeset
244 By default all keys beginning with ``__comment`` or ``__doc`` are
d44ee758e31b Some docu on comments in files
Franz Glasner <hg@dom66.de>
parents: 142
diff changeset
245 filtered out and not given to the application. This allows comments in
d44ee758e31b Some docu on comments in files
Franz Glasner <hg@dom66.de>
parents: 142
diff changeset
246 JSON files -- but is not restricted to JSON files only.
d44ee758e31b Some docu on comments in files
Franz Glasner <hg@dom66.de>
parents: 142
diff changeset
247
d44ee758e31b Some docu on comments in files
Franz Glasner <hg@dom66.de>
parents: 142
diff changeset
248 For all types of configuration files their respective standard comments
d44ee758e31b Some docu on comments in files
Franz Glasner <hg@dom66.de>
parents: 142
diff changeset
249 are allowed too.
d44ee758e31b Some docu on comments in files
Franz Glasner <hg@dom66.de>
parents: 142
diff changeset
250
d44ee758e31b Some docu on comments in files
Franz Glasner <hg@dom66.de>
parents: 142
diff changeset
251
117
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
252 .. _variable-namespaces:
115
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 Variable Namespaces
117
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
255 -------------------
115
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
256
117
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
257 Currently there are 4 namespaces:
115
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 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
260
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
261 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
262
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
263 2. The namespace ``OS``
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
264
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
265 Available functions:
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
266
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
267 ``cwd``
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
268 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
269
243
57ff12610dc5 Implemented OS:node to return the host's computername
Franz Glasner <fzglas.hg@dom66.de>
parents: 215
diff changeset
270 ``node``
57ff12610dc5 Implemented OS:node to return the host's computername
Franz Glasner <fzglas.hg@dom66.de>
parents: 215
diff changeset
271 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
272 :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
273
115
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
274 3. The namespace ``ENV``
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
275
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
276 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
277 available from :py:data:`os.environ`.
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
278
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
279 4. The namespace ``PY``
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 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
282
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
283 ``version``
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
284 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
285
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
286 ``version_maj_min``
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
287 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
288 (``.`` separated)
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
289
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
290 ``version_maj``
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
291 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
292
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
293 ``implementation``
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
294 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
295
282
da1596034954 Implemented an "AWS" namespace to retrieve some AWS-specific metadata
Franz Glasner <fzglas.hg@dom66.de>
parents: 276
diff changeset
296 5. The namespace ``AWS``
da1596034954 Implemented an "AWS" namespace to retrieve some AWS-specific metadata
Franz Glasner <fzglas.hg@dom66.de>
parents: 276
diff changeset
297
da1596034954 Implemented an "AWS" namespace to retrieve some AWS-specific metadata
Franz Glasner <fzglas.hg@dom66.de>
parents: 276
diff changeset
298 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
299 AWS:
da1596034954 Implemented an "AWS" namespace to retrieve some AWS-specific metadata
Franz Glasner <fzglas.hg@dom66.de>
parents: 276
diff changeset
300
da1596034954 Implemented an "AWS" namespace to retrieve some AWS-specific metadata
Franz Glasner <fzglas.hg@dom66.de>
parents: 276
diff changeset
301 ``metadata.instance-id``
da1596034954 Implemented an "AWS" namespace to retrieve some AWS-specific metadata
Franz Glasner <fzglas.hg@dom66.de>
parents: 276
diff changeset
302
da1596034954 Implemented an "AWS" namespace to retrieve some AWS-specific metadata
Franz Glasner <fzglas.hg@dom66.de>
parents: 276
diff changeset
303 ``metadata.placement.region``
da1596034954 Implemented an "AWS" namespace to retrieve some AWS-specific metadata
Franz Glasner <fzglas.hg@dom66.de>
parents: 276
diff changeset
304
da1596034954 Implemented an "AWS" namespace to retrieve some AWS-specific metadata
Franz Glasner <fzglas.hg@dom66.de>
parents: 276
diff changeset
305 ``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
306
da1596034954 Implemented an "AWS" namespace to retrieve some AWS-specific metadata
Franz Glasner <fzglas.hg@dom66.de>
parents: 276
diff changeset
307 ``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
308 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
309 (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
310 ``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
311 et al.).
da1596034954 Implemented an "AWS" namespace to retrieve some AWS-specific metadata
Franz Glasner <fzglas.hg@dom66.de>
parents: 276
diff changeset
312
115
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
313
117
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
314 Examples
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
315 ~~~~~~~~
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
316
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
317 ::
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
318
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
319 config.getvar("OS:cwd")
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
320
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
321 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
322
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
323
202
2e66178a09d8 Docu: Ban "keyword expansion" -- use "variable interpolation" instead
Franz Glasner <fzglas.hg@dom66.de>
parents: 200
diff changeset
324 .. _variable-interpolation:
117
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
325
202
2e66178a09d8 Docu: Ban "keyword expansion" -- use "variable interpolation" instead
Franz Glasner <fzglas.hg@dom66.de>
parents: 200
diff changeset
326 Variable Interpolation
2e66178a09d8 Docu: Ban "keyword expansion" -- use "variable interpolation" instead
Franz Glasner <fzglas.hg@dom66.de>
parents: 200
diff changeset
327 ----------------------
117
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
328
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
329 Configuration variable values that are read with
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
330 :py:meth:`.Configuration.getvar_s` are subject to variable
202
2e66178a09d8 Docu: Ban "keyword expansion" -- use "variable interpolation" instead
Franz Glasner <fzglas.hg@dom66.de>
parents: 200
diff changeset
331 interpolation. The general syntactic pattern for this is::
117
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
332
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
333 {{[namespace:]variable[|filter[|filter...]]}}
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
334
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
335 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
336 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
337 introduced by a pipe symbol ``|``.
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
338
202
2e66178a09d8 Docu: Ban "keyword expansion" -- use "variable interpolation" instead
Franz Glasner <fzglas.hg@dom66.de>
parents: 200
diff changeset
339 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
340 :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
341 :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
342 :py:meth:`.Configuration.expand_variable`
117
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
343
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
344
115
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
345 Filter functions
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 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
349
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
350 {{my.variable|filter1|filter2}}
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
351
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
352 Available filter functions are:
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 ``urlquote``
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
355
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
356 ``saslprep``
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
357
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
358 ``normpath``
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 ``abspath``
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
361
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
362 ``posixpath``
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
363
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
364 ``lower``
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
365
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
366 ``upper``
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
367
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
368
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
369 Examples
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
370 ~~~~~~~~
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
371
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
372 ::
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
373
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
374 {{OS:cwd|posixpath}}
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
375
117
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
376 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
377 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
378
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
379 ::
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
380
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
381 {{ENV:PATH}}
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
382
117
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
383 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
384
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
385 ::
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
386
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
387 {{PY:version}}
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
388
117
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
389 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
390
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
391 ::
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
392
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
393 {{PY::implementation|upper}}
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
394
117
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
395 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
396 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
397
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
398
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
399 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
400 ---------------------------------------------
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
401
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
402 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
403 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
404
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
405 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
406 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
407
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
408 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
409
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
410 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
411 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
412
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
413 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
414 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
415
194
0d8dd58afc44 Docu: Enhanced the custom loader section somewhat
Franz Glasner <fzglas.hg@dom66.de>
parents: 193
diff changeset
416 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
417
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
418 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
419 ...
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
420 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
421
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
422 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
423 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
424 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
425
0d8dd58afc44 Docu: Enhanced the custom loader section somewhat
Franz Glasner <fzglas.hg@dom66.de>
parents: 193
diff changeset
426 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
427 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
428
fa660f084ceb Docu: an example for configmix.try_determine_filemode()
Franz Glasner <fzglas.hg@dom66.de>
parents: 202
diff changeset
429 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
430 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
431
fa660f084ceb Docu: an example for configmix.try_determine_filemode()
Franz Glasner <fzglas.hg@dom66.de>
parents: 202
diff changeset
432 configmix.set_assoc("*", configmix.try_determine_filemode)