Mercurial > hgrepos > Python > libs > ConfigMix

annotate docs/introduction.rst @ 260:2cfd670281ae

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Do not set "root", "self" and "here" variables any more. This hinders proper automatic configuration on some PyPy configurations when using `genapplib`.
author Franz Glasner <fzglas.hg@dom66.de>
date Tue, 28 Jul 2020 01:12:41 +0200
parents 57ff12610dc5
children af371f9c016d
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
145
d44ee758e31b Some docu on comments in files
Franz Glasner <hg@dom66.de>
parents: 142
diff changeset
230 .. _comments:
d44ee758e31b Some docu on comments in files
Franz Glasner <hg@dom66.de>
parents: 142
diff changeset
231
d44ee758e31b Some docu on comments in files
Franz Glasner <hg@dom66.de>
parents: 142
diff changeset
232 Comments
d44ee758e31b Some docu on comments in files
Franz Glasner <hg@dom66.de>
parents: 142
diff changeset
233 --------
d44ee758e31b Some docu on comments in files
Franz Glasner <hg@dom66.de>
parents: 142
diff changeset
234
d44ee758e31b Some docu on comments in files
Franz Glasner <hg@dom66.de>
parents: 142
diff changeset
235 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
236 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
237 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
238
d44ee758e31b Some docu on comments in files
Franz Glasner <hg@dom66.de>
parents: 142
diff changeset
239 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
240 are allowed too.
d44ee758e31b Some docu on comments in files
Franz Glasner <hg@dom66.de>
parents: 142
diff changeset
241
d44ee758e31b Some docu on comments in files
Franz Glasner <hg@dom66.de>
parents: 142
diff changeset
242
117
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
243 .. _variable-namespaces:
115
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
244
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
245 Variable Namespaces
117
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
246 -------------------
115
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
247
117
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
248 Currently there are 4 namespaces:
115
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 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
251
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
252 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
253
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
254 2. The namespace ``OS``
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 Available functions:
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
257
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
258 ``cwd``
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
259 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
260
243
57ff12610dc5 Implemented OS:node to return the host's computername
Franz Glasner <fzglas.hg@dom66.de>
parents: 215
diff changeset
261 ``node``
57ff12610dc5 Implemented OS:node to return the host's computername
Franz Glasner <fzglas.hg@dom66.de>
parents: 215
diff changeset
262 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
263 :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
264
115
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
265 3. The namespace ``ENV``
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 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
268 available from :py:data:`os.environ`.
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
269
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
270 4. The namespace ``PY``
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
271
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
272 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
273
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
274 ``version``
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
275 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
276
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
277 ``version_maj_min``
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
278 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
279 (``.`` separated)
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 ``version_maj``
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
282 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
283
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
284 ``implementation``
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
285 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
286
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
287
117
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
288 Examples
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
289 ~~~~~~~~
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
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
293 config.getvar("OS:cwd")
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
294
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
295 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
296
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
297
202
2e66178a09d8 Docu: Ban "keyword expansion" -- use "variable interpolation" instead
Franz Glasner <fzglas.hg@dom66.de>
parents: 200
diff changeset
298 .. _variable-interpolation:
117
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
299
202
2e66178a09d8 Docu: Ban "keyword expansion" -- use "variable interpolation" instead
Franz Glasner <fzglas.hg@dom66.de>
parents: 200
diff changeset
300 Variable Interpolation
2e66178a09d8 Docu: Ban "keyword expansion" -- use "variable interpolation" instead
Franz Glasner <fzglas.hg@dom66.de>
parents: 200
diff changeset
301 ----------------------
117
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 Configuration variable values that are read with
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
304 :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
305 interpolation. The general syntactic pattern for this is::
117
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 {{[namespace:]variable[|filter[|filter...]]}}
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
308
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
309 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
310 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
311 introduced by a pipe symbol ``|``.
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
312
202
2e66178a09d8 Docu: Ban "keyword expansion" -- use "variable interpolation" instead
Franz Glasner <fzglas.hg@dom66.de>
parents: 200
diff changeset
313 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
314 :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
315 :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
316 :py:meth:`.Configuration.expand_variable`
117
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
115
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
319 Filter functions
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
320 ~~~~~~~~~~~~~~~~
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 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
323
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
324 {{my.variable|filter1|filter2}}
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 Available filter functions are:
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 ``urlquote``
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 ``saslprep``
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 ``normpath``
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 ``abspath``
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 ``posixpath``
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
337
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
338 ``lower``
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 ``upper``
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
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
343 Examples
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
344 ~~~~~~~~
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
345
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 {{OS:cwd|posixpath}}
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
349
117
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
350 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
351 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
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 {{ENV:PATH}}
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 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
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:version}}
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 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
364
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
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
367 {{PY::implementation|upper}}
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
368
117
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
369 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
370 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
371
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 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
374 ---------------------------------------------
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
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
376 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
377 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
378
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
379 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
380 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
381
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
382 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
383
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
384 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
385 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
386
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
387 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
388 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
389
194
0d8dd58afc44 Docu: Enhanced the custom loader section somewhat
Franz Glasner <fzglas.hg@dom66.de>
parents: 193
diff changeset
390 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
391
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
392 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
393 ...
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
394 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
395
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
396 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
397 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
398 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
399
0d8dd58afc44 Docu: Enhanced the custom loader section somewhat
Franz Glasner <fzglas.hg@dom66.de>
parents: 193
diff changeset
400 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
401 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
402
fa660f084ceb Docu: an example for configmix.try_determine_filemode()
Franz Glasner <fzglas.hg@dom66.de>
parents: 202
diff changeset
403 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
404 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
405
fa660f084ceb Docu: an example for configmix.try_determine_filemode()
Franz Glasner <fzglas.hg@dom66.de>
parents: 202
diff changeset
406 configmix.set_assoc("*", configmix.try_determine_filemode)