Mercurial > hgrepos > Python > libs > ConfigMix

annotate doc/introduction.rst @ 142:fc2bd73f9e98

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Sort extension list in the docu
author Franz Glasner <hg@dom66.de>
date Sat, 07 Apr 2018 09:33:13 +0200
parents c87b0dc54e1d
children d44ee758e31b
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
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
8 The configurations can be read from different types of files:
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
9
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
10 - :ref:`YAML files <yaml-files>`
131
b34ad08e7198 Document the JSON files
Franz Glasner <hg@dom66.de>
parents: 122
diff changeset
11 - :ref:`JSON files <json-files>`
94
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
12 - :ref:`INI files <ini-files>`
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
13 - :ref:`executable Python scripts <executable-python-scripts>`
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
14
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
15
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
16 .. _yaml-files:
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
17
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
18 YAML Files
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
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
21 Need the :mod:`yaml` package (e.g. ``pip install pyyaml``)
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
22
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
23 .. note:: All strings are returned as Unicode text strings.
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
24
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
25 .. 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
26 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
27 implementation.
94
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
28
97
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents: 94
diff changeset
29 An example is:
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents: 94
diff changeset
30
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents: 94
diff changeset
31 .. 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
32 :language: yaml
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents: 94
diff changeset
33
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents: 94
diff changeset
34
122
21d92ff8cf31 Begin the handling of JSON-style configuration files
Franz Glasner <hg@dom66.de>
parents: 117
diff changeset
35 .. _json-files:
21d92ff8cf31 Begin the handling of JSON-style configuration files
Franz Glasner <hg@dom66.de>
parents: 117
diff changeset
36
21d92ff8cf31 Begin the handling of JSON-style configuration files
Franz Glasner <hg@dom66.de>
parents: 117
diff changeset
37 JSON files
21d92ff8cf31 Begin the handling of JSON-style configuration files
Franz Glasner <hg@dom66.de>
parents: 117
diff changeset
38 ----------
21d92ff8cf31 Begin the handling of JSON-style configuration files
Franz Glasner <hg@dom66.de>
parents: 117
diff changeset
39
131
b34ad08e7198 Document the JSON files
Franz Glasner <hg@dom66.de>
parents: 122
diff changeset
40 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
41
b34ad08e7198 Document the JSON files
Franz Glasner <hg@dom66.de>
parents: 122
diff changeset
42 .. note:: All strings are returned as Unicode text strings.
b34ad08e7198 Document the JSON files
Franz Glasner <hg@dom66.de>
parents: 122
diff changeset
43
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
44 .. 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
45 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
46 implementation.
131
b34ad08e7198 Document the JSON files
Franz Glasner <hg@dom66.de>
parents: 122
diff changeset
47
b34ad08e7198 Document the JSON files
Franz Glasner <hg@dom66.de>
parents: 122
diff changeset
48 .. todo:: Handle JSON comments by special attributes which will
b34ad08e7198 Document the JSON files
Franz Glasner <hg@dom66.de>
parents: 122
diff changeset
49 filtered out on further processing. Javascript comments are
b34ad08e7198 Document the JSON files
Franz Glasner <hg@dom66.de>
parents: 122
diff changeset
50 not allowed by the JSON specification.
b34ad08e7198 Document the JSON files
Franz Glasner <hg@dom66.de>
parents: 122
diff changeset
51
b34ad08e7198 Document the JSON files
Franz Glasner <hg@dom66.de>
parents: 122
diff changeset
52 An example is:
b34ad08e7198 Document the JSON files
Franz Glasner <hg@dom66.de>
parents: 122
diff changeset
53
b34ad08e7198 Document the JSON files
Franz Glasner <hg@dom66.de>
parents: 122
diff changeset
54 .. literalinclude:: ../tests/data/conf10.json
b34ad08e7198 Document the JSON files
Franz Glasner <hg@dom66.de>
parents: 122
diff changeset
55 :language: js
122
21d92ff8cf31 Begin the handling of JSON-style configuration files
Franz Glasner <hg@dom66.de>
parents: 117
diff changeset
56
21d92ff8cf31 Begin the handling of JSON-style configuration files
Franz Glasner <hg@dom66.de>
parents: 117
diff changeset
57
94
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
58 .. _ini-files:
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
59
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
60 INI Files
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
61 ---------
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 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
64 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
65 used.
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
66
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
67 Normally all values are returned as Unicode text strings.
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
68 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
69
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
70 ``:int:``
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
71 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
72 literal
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
73
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
74 ``:float:``
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
75 The value is interpreted as :class:`float`
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 ``:bool:``
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
78 The resulting value is a :class:`bool` where
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 ``1``, ``true``, ``yes``, ``on``
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
81 yield a Python ``True``
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 ``0``, ``false``, ``no``, ``off``
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
84 yield a Python ``False``
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 The evaluation is done *case-insensitively*.
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
87
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
88 .. note:: All strings are returned as Unicode text strings.
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
89
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
90 .. 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
91 module the INI file reader is *case-sensitive*.
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
92
97
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents: 94
diff changeset
93 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
94 configuration to the YAML configuration above:
94
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 .. 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
97 :language: ini
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents: 94
diff changeset
98
133
05cb18c8697a FIX: Typo
Franz Glasner <hg@dom66.de>
parents: 132
diff changeset
99 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
100 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
101
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents: 94
diff changeset
102 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
103 tree-ish configuration dictionary.
94
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
104
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
105
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
106 .. _executable-python-scripts:
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 Executable Python Scripts
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
109 -------------------------
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
110
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
111 What will be exported:
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
112
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
113 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
114 extracted from the script.
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
115
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
116 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
117 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
118 extracted.
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
119
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
120 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
121 underscore ``_`` are found.
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
122
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
123 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
124 ``from module import *``.
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
125
2b79ddc0f92b Begin a basic introduction chapter
Franz Glasner <hg@dom66.de>
parents:
diff changeset
126 .. 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
127 imported.
97
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents: 94
diff changeset
128
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents: 94
diff changeset
129 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
130 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
131
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents: 94
diff changeset
132 .. 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
133 :language: python
114
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
134
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
135
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
136 .. _loading-and-merging:
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
137
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
138 Loading and Merging
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
139 -------------------
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
140
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
141 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
142
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
143 import configmix
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
144
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
145 #
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
146 # 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
147 # 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
148 # also here.
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
149 #
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
150 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
151
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
152 # 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
153 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
154
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
155 # 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
156 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
157
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
158
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
159 By default filenames of the configuration files must have the extensions
114
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
160 (case-insensitively):
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
161
142
fc2bd73f9e98 Sort extension list in the docu
Franz Glasner <hg@dom66.de>
parents: 139
diff changeset
162 ``.ini``
fc2bd73f9e98 Sort extension list in the docu
Franz Glasner <hg@dom66.de>
parents: 139
diff changeset
163 for INI configuration files
fc2bd73f9e98 Sort extension list in the docu
Franz Glasner <hg@dom66.de>
parents: 139
diff changeset
164
fc2bd73f9e98 Sort extension list in the docu
Franz Glasner <hg@dom66.de>
parents: 139
diff changeset
165 ``.json``
fc2bd73f9e98 Sort extension list in the docu
Franz Glasner <hg@dom66.de>
parents: 139
diff changeset
166 for JSON configuration files
fc2bd73f9e98 Sort extension list in the docu
Franz Glasner <hg@dom66.de>
parents: 139
diff changeset
167
114
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
168 ``.py``
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
169 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
170
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
171 ``.yml`` or ``.yaml``
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents: 97
diff changeset
172 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
173
115
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
174
117
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
175 .. _getting-values:
115
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
176
117
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
177 Getting configuration variables
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
178 -------------------------------
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
179
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
180 Get a -- possibly expanded -- configuration variable's value with::
115
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
181
117
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
182 value1 = config.getvar_s("key1")
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
183
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
184 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
185
117
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
186 value1_raw = config.getvar("key1")
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
187
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
188 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
189 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
190 level keys with a point ``.``.
115
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
191
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
192 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
193 ``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
194 ``get this as `tree1.tree2.key4'``.
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
195
117
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
196 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
197 :py:meth:`.Configuration.getvar_s`.
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 Both methods also perform :ref:`variable-expansion` and handle
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
200 :ref:`variable-namespaces`. Filtering is not supported. So -- the
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
201 variable name arguments of :py:meth:`.Configuration.getvar` and
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
202 :py:meth:`.Configuration.getvar_s` are of the form
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
203 ``[namespace:]variable``.
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
204
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
205
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
206 .. _variable-namespaces:
115
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
207
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
208 Variable Namespaces
117
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
209 -------------------
115
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
210
117
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
211 Currently there are 4 namespaces:
115
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
212
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
213 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
214
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
215 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
216
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
217 2. The namespace ``OS``
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
218
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
219 Available functions:
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
220
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
221 ``cwd``
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
222 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
223
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
224 3. The namespace ``ENV``
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
225
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
226 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
227 available from :py:data:`os.environ`.
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
228
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
229 4. The namespace ``PY``
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
230
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
231 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
232
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
233 ``version``
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
234 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
235
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
236 ``version_maj_min``
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
237 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
238 (``.`` separated)
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
239
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
240 ``version_maj``
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
241 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
242
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
243 ``implementation``
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
244 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
245
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
246
117
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
247 Examples
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
248 ~~~~~~~~
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
249
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
250 ::
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
251
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
252 config.getvar("OS:cwd")
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
253
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
254 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
255
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
256
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
257 .. _variable-expansion:
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
258
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
259 Variable Expansion
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
260 ------------------
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
261
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
262 Configuration variable values that are read with
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
263 :py:meth:`.Configuration.getvar_s` are subject to variable
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
264 expansion. The general syntactic pattern for this is::
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
265
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
266 {{[namespace:]variable[|filter[|filter...]]}}
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
267
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
268 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
269 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
270 introduced by a pipe symbol ``|``.
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
271
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
272 Variables are expanded lately at runtime -- exactly when calling
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
273 :py:meth:`.Configuration.getvar_s` or :py:meth:`.Configuration.getvar`.
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
274
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
275
115
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
276 Filter functions
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
277 ~~~~~~~~~~~~~~~~
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
278
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
279 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
280
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
281 {{my.variable|filter1|filter2}}
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 Available filter functions are:
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
284
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
285 ``urlquote``
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 ``saslprep``
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
288
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
289 ``normpath``
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
290
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
291 ``abspath``
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 ``posixpath``
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
294
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
295 ``lower``
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
296
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
297 ``upper``
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
298
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
299
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
300 Examples
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
301 ~~~~~~~~
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
302
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
303 ::
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
304
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
305 {{OS:cwd|posixpath}}
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
306
117
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
307 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
308 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
309
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
310 ::
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
311
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
312 {{ENV:PATH}}
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 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
315
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
316 ::
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
317
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
318 {{PY:version}}
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
319
117
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
320 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
321
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
322 ::
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 {{PY::implementation|upper}}
a5339d39af5c Begin the documentation of variables and its expansion
Franz Glasner <hg@dom66.de>
parents: 114
diff changeset
325
117
c5b638f9c607 - More on getting variable values
Franz Glasner <hg@dom66.de>
parents: 115
diff changeset
326 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
327 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
328
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
329
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
330 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
331 ---------------------------------------------
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
332
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
333 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
334 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
335
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
336 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
337 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
338
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
339 configmix.set_loader(".conf", configmix.default_loaders[".yml"])
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
340
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
341 Allow only files with extension ".cfg" in INI-style::
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
342
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
343 configmix.clear_loader()
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
344 configmix.set_loader(".cfg", configmix.default_loders[".ini"])
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
345
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
346 Just a new configuration file style::
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
347
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
348 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
349 ...
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
350 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
351
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
352 configmix.clear_loader()
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
353 configmix.set_loader(".my.configuration", my_custom_loader)