Python/libs/ConfigMix: docs/introduction.rst annotate

annotate docs/introduction.rst @ 354:bd28fb4565e1

FIX: Tagging of the KeyError: :py:exception: -> :py:exc:

author	Franz Glasner <f.glasner@feldmann-mg.com>
date	Thu, 24 Jun 2021 19:41:44 +0200
parents	a7491f835cb0
children	baedd2031074

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
300 28aa21095a68 Docs: "config" is the default root section Franz Glasner <fzglas.hg@dom66.de> parents: 282 diff changeset	68 used as root section.
94 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
315 21fa4b4bfdaa Docu: .getvarl() and .getvarl_s() Franz Glasner <fzglas.hg@dom66.de> parents: 308 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")
315 21fa4b4bfdaa Docu: .getvarl() and .getvarl_s() Franz Glasner <fzglas.hg@dom66.de> parents: 308 diff changeset	207 value2 = config.getvar_s("key1.subkey2")
117 c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	208
315 21fa4b4bfdaa Docu: .getvarl() and .getvarl_s() Franz Glasner <fzglas.hg@dom66.de> parents: 308 diff changeset	209 or equivalently with ::
21fa4b4bfdaa Docu: .getvarl() and .getvarl_s() Franz Glasner <fzglas.hg@dom66.de> parents: 308 diff changeset	210
21fa4b4bfdaa Docu: .getvarl() and .getvarl_s() Franz Glasner <fzglas.hg@dom66.de> parents: 308 diff changeset	211 value1 = config.getvarl_s("key1")
21fa4b4bfdaa Docu: .getvarl() and .getvarl_s() Franz Glasner <fzglas.hg@dom66.de> parents: 308 diff changeset	212 value2 = config.getvarl_s("key1", "subkey2")
21fa4b4bfdaa Docu: .getvarl() and .getvarl_s() Franz Glasner <fzglas.hg@dom66.de> parents: 308 diff changeset	213
21fa4b4bfdaa Docu: .getvarl() and .getvarl_s() Franz Glasner <fzglas.hg@dom66.de> parents: 308 diff changeset	214 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	215
117 c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	216 value1_raw = config.getvar("key1")
315 21fa4b4bfdaa Docu: .getvarl() and .getvarl_s() Franz Glasner <fzglas.hg@dom66.de> parents: 308 diff changeset	217 value2_raw = config.getvarl("key1.subkey2")
21fa4b4bfdaa Docu: .getvarl() and .getvarl_s() Franz Glasner <fzglas.hg@dom66.de> parents: 308 diff changeset	218
21fa4b4bfdaa Docu: .getvarl() and .getvarl_s() Franz Glasner <fzglas.hg@dom66.de> parents: 308 diff changeset	219 or equivalently with ::
21fa4b4bfdaa Docu: .getvarl() and .getvarl_s() Franz Glasner <fzglas.hg@dom66.de> parents: 308 diff changeset	220
21fa4b4bfdaa Docu: .getvarl() and .getvarl_s() Franz Glasner <fzglas.hg@dom66.de> parents: 308 diff changeset	221 value1_raw = config.getvarl("key1")
21fa4b4bfdaa Docu: .getvarl() and .getvarl_s() Franz Glasner <fzglas.hg@dom66.de> parents: 308 diff changeset	222 value2_raw = config.getvarl("key1", "subkey2")
117 c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	223
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	224 Because the configuration is not only a plain list of but a tree of
315 21fa4b4bfdaa Docu: .getvarl() and .getvarl_s() Franz Glasner <fzglas.hg@dom66.de> parents: 308 diff changeset	225 key-value pairs you will want to fetch a nested configuration value
21fa4b4bfdaa Docu: .getvarl() and .getvarl_s() Franz Glasner <fzglas.hg@dom66.de> parents: 308 diff changeset	226 using two access methods:
21fa4b4bfdaa Docu: .getvarl() and .getvarl_s() Franz Glasner <fzglas.hg@dom66.de> parents: 308 diff changeset	227
21fa4b4bfdaa Docu: .getvarl() and .getvarl_s() Franz Glasner <fzglas.hg@dom66.de> parents: 308 diff changeset	228 :py:meth:`.Configuration.getvar` and :py:meth:`.Configuration.getvar_s`
21fa4b4bfdaa Docu: .getvarl() and .getvarl_s() Franz Glasner <fzglas.hg@dom66.de> parents: 308 diff changeset	229
21fa4b4bfdaa Docu: .getvarl() and .getvarl_s() Franz Glasner <fzglas.hg@dom66.de> parents: 308 diff changeset	230 Use a single key variable where the invidual level keys are joined
21fa4b4bfdaa Docu: .getvarl() and .getvarl_s() Franz Glasner <fzglas.hg@dom66.de> parents: 308 diff changeset	231 using a dot (``.``)
21fa4b4bfdaa Docu: .getvarl() and .getvarl_s() Franz Glasner <fzglas.hg@dom66.de> parents: 308 diff changeset	232
21fa4b4bfdaa Docu: .getvarl() and .getvarl_s() Franz Glasner <fzglas.hg@dom66.de> parents: 308 diff changeset	233 :py:meth:`.Configuration.getvarl` and :py:meth:`.Configuration.getvarl_s`
21fa4b4bfdaa Docu: .getvarl() and .getvarl_s() Franz Glasner <fzglas.hg@dom66.de> parents: 308 diff changeset	234
21fa4b4bfdaa Docu: .getvarl() and .getvarl_s() Franz Glasner <fzglas.hg@dom66.de> parents: 308 diff changeset	235 Use just positional Python arguments for each level key
115 a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	236
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	237 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	238 ``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	239 ``get this as `tree1.tree2.key4'``.
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	240
315 21fa4b4bfdaa Docu: .getvarl() and .getvarl_s() Franz Glasner <fzglas.hg@dom66.de> parents: 308 diff changeset	241 Alternatively ``config.getvarl_s("tree1", "tree2", "key4")`` can be called
21fa4b4bfdaa Docu: .getvarl() and .getvarl_s() Franz Glasner <fzglas.hg@dom66.de> parents: 308 diff changeset	242 with the very same result.
115 a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	243
315 21fa4b4bfdaa Docu: .getvarl() and .getvarl_s() Franz Glasner <fzglas.hg@dom66.de> parents: 308 diff changeset	244 All four methods also perform direct :ref:`variable-interpolation` and
21fa4b4bfdaa Docu: .getvarl() and .getvarl_s() Franz Glasner <fzglas.hg@dom66.de> parents: 308 diff changeset	245 handle :ref:`variable-namespaces` -- yet in different ways.
21fa4b4bfdaa Docu: .getvarl() and .getvarl_s() Franz Glasner <fzglas.hg@dom66.de> parents: 308 diff changeset	246 Filtering is not supported.
21fa4b4bfdaa Docu: .getvarl() and .getvarl_s() Franz Glasner <fzglas.hg@dom66.de> parents: 308 diff changeset	247 So -- the variable name arguments of :py:meth:`.Configuration.getvar`
21fa4b4bfdaa Docu: .getvarl() and .getvarl_s() Franz Glasner <fzglas.hg@dom66.de> parents: 308 diff changeset	248 and :py:meth:`.Configuration.getvar_s` are of the form
21fa4b4bfdaa Docu: .getvarl() and .getvarl_s() Franz Glasner <fzglas.hg@dom66.de> parents: 308 diff changeset	249 ``[namespace:]variable`` where for :py:meth:`.Configuration.getvarl`
21fa4b4bfdaa Docu: .getvarl() and .getvarl_s() Franz Glasner <fzglas.hg@dom66.de> parents: 308 diff changeset	250 and :py:meth:`.Configuration.getvarl_s` the namespace is given as
21fa4b4bfdaa Docu: .getvarl() and .getvarl_s() Franz Glasner <fzglas.hg@dom66.de> parents: 308 diff changeset	251 optional keyword parameter `namespace`.
117 c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	252
333 5ec0ae3bb8db Docs: quoting Franz Glasner <fzglas.hg@dom66.de> parents: 328 diff changeset	253 .. note:: Special characters within namespace, key and filter names
5ec0ae3bb8db Docs: quoting Franz Glasner <fzglas.hg@dom66.de> parents: 328 diff changeset	254 must be quoted (see :ref:`quoting`) when using
5ec0ae3bb8db Docs: quoting Franz Glasner <fzglas.hg@dom66.de> parents: 328 diff changeset	255 :py:meth:`~.Configuration.getvar` or
5ec0ae3bb8db Docs: quoting Franz Glasner <fzglas.hg@dom66.de> parents: 328 diff changeset	256 :py:meth:`~.Configuration.getvar_s` to retrieve variables.
5ec0ae3bb8db Docs: quoting Franz Glasner <fzglas.hg@dom66.de> parents: 328 diff changeset	257
5ec0ae3bb8db Docs: quoting Franz Glasner <fzglas.hg@dom66.de> parents: 328 diff changeset	258 With :py:meth:`~.Configuration.getvarl` or
5ec0ae3bb8db Docs: quoting Franz Glasner <fzglas.hg@dom66.de> parents: 328 diff changeset	259 :py:meth:`~.Configuration.getvarl_s` quoting is neither needed
5ec0ae3bb8db Docs: quoting Franz Glasner <fzglas.hg@dom66.de> parents: 328 diff changeset	260 and not supported.
117 c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	261
276 af371f9c016d Allow deletion of key-value pairs when merging is done. Franz Glasner <fzglas.hg@dom66.de> parents: 243 diff changeset	262 .. _merging-deletions:
af371f9c016d Allow deletion of key-value pairs when merging is done. Franz Glasner <fzglas.hg@dom66.de> parents: 243 diff changeset	263
af371f9c016d Allow deletion of key-value pairs when merging is done. Franz Glasner <fzglas.hg@dom66.de> parents: 243 diff changeset	264 Deletions
af371f9c016d Allow deletion of key-value pairs when merging is done. Franz Glasner <fzglas.hg@dom66.de> parents: 243 diff changeset	265 ---------
af371f9c016d Allow deletion of key-value pairs when merging is done. Franz Glasner <fzglas.hg@dom66.de> parents: 243 diff changeset	266
af371f9c016d Allow deletion of key-value pairs when merging is done. Franz Glasner <fzglas.hg@dom66.de> parents: 243 diff changeset	267 By using the special value ``{{::DEL::}}`` the corresponding key-value
af371f9c016d Allow deletion of key-value pairs when merging is done. Franz Glasner <fzglas.hg@dom66.de> parents: 243 diff changeset	268 pair is deleted when merging is done.
af371f9c016d Allow deletion of key-value pairs when merging is done. Franz Glasner <fzglas.hg@dom66.de> parents: 243 diff changeset	269
af371f9c016d Allow deletion of key-value pairs when merging is done. Franz Glasner <fzglas.hg@dom66.de> parents: 243 diff changeset	270
145 d44ee758e31b Some docu on comments in files Franz Glasner <hg@dom66.de> parents: 142 diff changeset	271 .. _comments:
d44ee758e31b Some docu on comments in files Franz Glasner <hg@dom66.de> parents: 142 diff changeset	272
d44ee758e31b Some docu on comments in files Franz Glasner <hg@dom66.de> parents: 142 diff changeset	273 Comments
d44ee758e31b Some docu on comments in files Franz Glasner <hg@dom66.de> parents: 142 diff changeset	274 --------
d44ee758e31b Some docu on comments in files Franz Glasner <hg@dom66.de> parents: 142 diff changeset	275
d44ee758e31b Some docu on comments in files Franz Glasner <hg@dom66.de> parents: 142 diff changeset	276 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	277 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	278 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	279
d44ee758e31b Some docu on comments in files Franz Glasner <hg@dom66.de> parents: 142 diff changeset	280 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	281 are allowed too.
d44ee758e31b Some docu on comments in files Franz Glasner <hg@dom66.de> parents: 142 diff changeset	282
d44ee758e31b Some docu on comments in files Franz Glasner <hg@dom66.de> parents: 142 diff changeset	283
117 c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	284 .. _variable-namespaces:
115 a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	285
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	286 Variable Namespaces
117 c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	287 -------------------
115 a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	288
316 fe2e28e5fd08 Docu: first short notes about configuration tree references Franz Glasner <fzglas.hg@dom66.de> parents: 315 diff changeset	289 Currently there are 6 namespaces:
115 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 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	292
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	293 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	294
333 5ec0ae3bb8db Docs: quoting Franz Glasner <fzglas.hg@dom66.de> parents: 328 diff changeset	295 .. seealso:: :ref:`quoting`
5ec0ae3bb8db Docs: quoting Franz Glasner <fzglas.hg@dom66.de> parents: 328 diff changeset	296
316 fe2e28e5fd08 Docu: first short notes about configuration tree references Franz Glasner <fzglas.hg@dom66.de> parents: 315 diff changeset	297 2. The namespace ``ref`` to be used for configuration references.
fe2e28e5fd08 Docu: first short notes about configuration tree references Franz Glasner <fzglas.hg@dom66.de> parents: 315 diff changeset	298
fe2e28e5fd08 Docu: first short notes about configuration tree references Franz Glasner <fzglas.hg@dom66.de> parents: 315 diff changeset	299 This is a namespace that is handled special within "ConfigMix".
fe2e28e5fd08 Docu: first short notes about configuration tree references Franz Glasner <fzglas.hg@dom66.de> parents: 315 diff changeset	300
fe2e28e5fd08 Docu: first short notes about configuration tree references Franz Glasner <fzglas.hg@dom66.de> parents: 315 diff changeset	301 Must be Filters are not supported.
fe2e28e5fd08 Docu: first short notes about configuration tree references Franz Glasner <fzglas.hg@dom66.de> parents: 315 diff changeset	302
fe2e28e5fd08 Docu: first short notes about configuration tree references Franz Glasner <fzglas.hg@dom66.de> parents: 315 diff changeset	303 3. The namespace ``OS``
115 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 Available functions:
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	306
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	307 ``cwd``
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	308 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	309
243 57ff12610dc5 Implemented OS:node to return the host's computername Franz Glasner <fzglas.hg@dom66.de> parents: 215 diff changeset	310 ``node``
57ff12610dc5 Implemented OS:node to return the host's computername Franz Glasner <fzglas.hg@dom66.de> parents: 215 diff changeset	311 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	312 :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	313
316 fe2e28e5fd08 Docu: first short notes about configuration tree references Franz Glasner <fzglas.hg@dom66.de> parents: 315 diff changeset	314 4. The namespace ``ENV``
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 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	317 available from :py:data:`os.environ`.
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	318
316 fe2e28e5fd08 Docu: first short notes about configuration tree references Franz Glasner <fzglas.hg@dom66.de> parents: 315 diff changeset	319 5. The namespace ``PY``
115 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 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	322
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	323 ``version``
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	324 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	325
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	326 ``version_maj_min``
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	327 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	328 (``.`` separated)
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 ``version_maj``
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	331 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	332
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	333 ``implementation``
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	334 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	335
316 fe2e28e5fd08 Docu: first short notes about configuration tree references Franz Glasner <fzglas.hg@dom66.de> parents: 315 diff changeset	336 6. The namespace ``AWS``
282 da1596034954 Implemented an "AWS" namespace to retrieve some AWS-specific metadata Franz Glasner <fzglas.hg@dom66.de> parents: 276 diff changeset	337
da1596034954 Implemented an "AWS" namespace to retrieve some AWS-specific metadata Franz Glasner <fzglas.hg@dom66.de> parents: 276 diff changeset	338 Contains some metadata for AWS instances when running from within
da1596034954 Implemented an "AWS" namespace to retrieve some AWS-specific metadata Franz Glasner <fzglas.hg@dom66.de> parents: 276 diff changeset	339 AWS:
da1596034954 Implemented an "AWS" namespace to retrieve some AWS-specific metadata Franz Glasner <fzglas.hg@dom66.de> parents: 276 diff changeset	340
da1596034954 Implemented an "AWS" namespace to retrieve some AWS-specific metadata Franz Glasner <fzglas.hg@dom66.de> parents: 276 diff changeset	341 ``metadata.instance-id``
da1596034954 Implemented an "AWS" namespace to retrieve some AWS-specific metadata Franz Glasner <fzglas.hg@dom66.de> parents: 276 diff changeset	342
da1596034954 Implemented an "AWS" namespace to retrieve some AWS-specific metadata Franz Glasner <fzglas.hg@dom66.de> parents: 276 diff changeset	343 ``metadata.placement.region``
da1596034954 Implemented an "AWS" namespace to retrieve some AWS-specific metadata Franz Glasner <fzglas.hg@dom66.de> parents: 276 diff changeset	344
da1596034954 Implemented an "AWS" namespace to retrieve some AWS-specific metadata Franz Glasner <fzglas.hg@dom66.de> parents: 276 diff changeset	345 ``metadata.placement.availability-zone``
da1596034954 Implemented an "AWS" namespace to retrieve some AWS-specific metadata Franz Glasner <fzglas.hg@dom66.de> parents: 276 diff changeset	346
da1596034954 Implemented an "AWS" namespace to retrieve some AWS-specific metadata Franz Glasner <fzglas.hg@dom66.de> parents: 276 diff changeset	347 ``dynamic.instance-identity.region``
da1596034954 Implemented an "AWS" namespace to retrieve some AWS-specific metadata Franz Glasner <fzglas.hg@dom66.de> parents: 276 diff changeset	348 and all other properties of the instance-identity document
da1596034954 Implemented an "AWS" namespace to retrieve some AWS-specific metadata Franz Glasner <fzglas.hg@dom66.de> parents: 276 diff changeset	349 (e.g. ``instanceId``, ``instanceType``, ``imageId``, ``pendingTime``,
da1596034954 Implemented an "AWS" namespace to retrieve some AWS-specific metadata Franz Glasner <fzglas.hg@dom66.de> parents: 276 diff changeset	350 ``architecture``, ``availabilityZone``, ``privateIp``, ``version``
da1596034954 Implemented an "AWS" namespace to retrieve some AWS-specific metadata Franz Glasner <fzglas.hg@dom66.de> parents: 276 diff changeset	351 et al.).
da1596034954 Implemented an "AWS" namespace to retrieve some AWS-specific metadata Franz Glasner <fzglas.hg@dom66.de> parents: 276 diff changeset	352
115 a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	353
117 c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	354 Examples
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	355 ~~~~~~~~
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	356
315 21fa4b4bfdaa Docu: .getvarl() and .getvarl_s() Franz Glasner <fzglas.hg@dom66.de> parents: 308 diff changeset	357 Both ::
117 c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	358
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	359 config.getvar("OS:cwd")
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	360
315 21fa4b4bfdaa Docu: .getvarl() and .getvarl_s() Franz Glasner <fzglas.hg@dom66.de> parents: 308 diff changeset	361 or ::
21fa4b4bfdaa Docu: .getvarl() and .getvarl_s() Franz Glasner <fzglas.hg@dom66.de> parents: 308 diff changeset	362
21fa4b4bfdaa Docu: .getvarl() and .getvarl_s() Franz Glasner <fzglas.hg@dom66.de> parents: 308 diff changeset	363 config.getvarl("cwd", namespace="OS")
21fa4b4bfdaa Docu: .getvarl() and .getvarl_s() Franz Glasner <fzglas.hg@dom66.de> parents: 308 diff changeset	364
21fa4b4bfdaa Docu: .getvarl() and .getvarl_s() Franz Glasner <fzglas.hg@dom66.de> parents: 308 diff changeset	365 yield the current working directory -- just as :py:func:`os.getcwd` does.
117 c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	366
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	367
202 2e66178a09d8 Docu: Ban "keyword expansion" -- use "variable interpolation" instead Franz Glasner <fzglas.hg@dom66.de> parents: 200 diff changeset	368 .. _variable-interpolation:
117 c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	369
202 2e66178a09d8 Docu: Ban "keyword expansion" -- use "variable interpolation" instead Franz Glasner <fzglas.hg@dom66.de> parents: 200 diff changeset	370 Variable Interpolation
2e66178a09d8 Docu: Ban "keyword expansion" -- use "variable interpolation" instead Franz Glasner <fzglas.hg@dom66.de> parents: 200 diff changeset	371 ----------------------
117 c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	372
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	373 Configuration variable values that are read with
315 21fa4b4bfdaa Docu: .getvarl() and .getvarl_s() Franz Glasner <fzglas.hg@dom66.de> parents: 308 diff changeset	374 :py:meth:`.Configuration.getvar_s` or :py:meth:`.Configuration.getvarl_s`
21fa4b4bfdaa Docu: .getvarl() and .getvarl_s() Franz Glasner <fzglas.hg@dom66.de> parents: 308 diff changeset	375 are subject to variable interpolation.
21fa4b4bfdaa Docu: .getvarl() and .getvarl_s() Franz Glasner <fzglas.hg@dom66.de> parents: 308 diff changeset	376 The general syntactic pattern for this is::
117 c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	377
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	378 {{[namespace:]variable[\|filter[\|filter...]]}}
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	379
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	380 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	381 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	382 introduced by a pipe symbol ``\|``.
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	383
202 2e66178a09d8 Docu: Ban "keyword expansion" -- use "variable interpolation" instead Franz Glasner <fzglas.hg@dom66.de> parents: 200 diff changeset	384 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	385 :py:meth:`.Configuration.getvar_s`,
315 21fa4b4bfdaa Docu: .getvarl() and .getvarl_s() Franz Glasner <fzglas.hg@dom66.de> parents: 308 diff changeset	386 :py:meth:`.Configuration.getvarl_s`,
158 ab6a48ff5235 FIX: Docu: Configuration.getvar() does not apply variable substitutions Franz Glasner <fzglas.hg@dom66.de> parents: 145 diff changeset	387 :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	388 :py:meth:`.Configuration.expand_variable`
117 c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	389
333 5ec0ae3bb8db Docs: quoting Franz Glasner <fzglas.hg@dom66.de> parents: 328 diff changeset	390 .. note:: Special characters within namespace, key and filter names
5ec0ae3bb8db Docs: quoting Franz Glasner <fzglas.hg@dom66.de> parents: 328 diff changeset	391 must be quoted (see :ref:`quoting`) when using variable
5ec0ae3bb8db Docs: quoting Franz Glasner <fzglas.hg@dom66.de> parents: 328 diff changeset	392 interpolation syntax.
5ec0ae3bb8db Docs: quoting Franz Glasner <fzglas.hg@dom66.de> parents: 328 diff changeset	393
117 c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	394
115 a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	395 Filter functions
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	396 ~~~~~~~~~~~~~~~~
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	397
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	398 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	399
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	400 {{my.variable\|filter1\|filter2}}
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	401
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	402 Available filter functions are:
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	403
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	404 ``urlquote``
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	405
347 d7daec119383 New filter function "urlquote_plus" which quotes a space into a '+' character Franz Glasner <fzglas.hg@dom66.de> parents: 343 diff changeset	406 ``urlquote_plus``
d7daec119383 New filter function "urlquote_plus" which quotes a space into a '+' character Franz Glasner <fzglas.hg@dom66.de> parents: 343 diff changeset	407
115 a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	408 ``saslprep``
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	409
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	410 ``normpath``
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	411
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	412 ``abspath``
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	413
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	414 ``posixpath``
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	415
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	416 ``lower``
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	417
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	418 ``upper``
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	419
353 a7491f835cb0 Changelog and minimal docu for `None` and `Empty` filters Franz Glasner <f.glasner@feldmann-mg.com> parents: 347 diff changeset	420 Also available are special filter functions ``None`` and ``Empty``.
a7491f835cb0 Changelog and minimal docu for `None` and `Empty` filters Franz Glasner <f.glasner@feldmann-mg.com> parents: 347 diff changeset	421 They are useful in variable interpolation context because they
354 bd28fb4565e1 FIX: Tagging of the KeyError: :py:exception: -> :py:exc: Franz Glasner <f.glasner@feldmann-mg.com> parents: 353 diff changeset	422 suppress possible lookup errors (aka :py:exc:`KeyError`) and instead
bd28fb4565e1 FIX: Tagging of the KeyError: :py:exception: -> :py:exc: Franz Glasner <f.glasner@feldmann-mg.com> parents: 353 diff changeset	423 return with :py:obj:`None` or an empty string.
353 a7491f835cb0 Changelog and minimal docu for `None` and `Empty` filters Franz Glasner <f.glasner@feldmann-mg.com> parents: 347 diff changeset	424
115 a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	425
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	426 Examples
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	427 ~~~~~~~~
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	428
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	429 ::
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	430
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	431 {{OS:cwd\|posixpath}}
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	432
117 c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	433 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	434 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	435
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	436 ::
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	437
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	438 {{ENV:PATH}}
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	439
117 c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	440 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	441
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	442 ::
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	443
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	444 {{PY:version}}
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	445
117 c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	446 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	447
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	448 ::
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	449
328 cffa4fcd0a4d Docu: syntax fix in example Franz Glasner <fzglas.hg@dom66.de> parents: 316 diff changeset	450 {{PY:implementation\|upper}}
115 a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	451
117 c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	452 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	453 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	454
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	455
316 fe2e28e5fd08 Docu: first short notes about configuration tree references Franz Glasner <fzglas.hg@dom66.de> parents: 315 diff changeset	456 Configuration tree references
fe2e28e5fd08 Docu: first short notes about configuration tree references Franz Glasner <fzglas.hg@dom66.de> parents: 315 diff changeset	457 -----------------------------
fe2e28e5fd08 Docu: first short notes about configuration tree references Franz Glasner <fzglas.hg@dom66.de> parents: 315 diff changeset	458
341 ae4b76d0da45 docs: fix example of tree reference syntax Franz Glasner <fzglas.hg@dom66.de> parents: 340 diff changeset	459 With ``{{ref:#my.other.key}}``
316 fe2e28e5fd08 Docu: first short notes about configuration tree references Franz Glasner <fzglas.hg@dom66.de> parents: 315 diff changeset	460
353 a7491f835cb0 Changelog and minimal docu for `None` and `Empty` filters Franz Glasner <f.glasner@feldmann-mg.com> parents: 347 diff changeset	461 - think of it as a sort of a symbolic link to other parts of the
343 c8b98285a7b5 docs: some more docu for tree references Franz Glasner <fzglas.hg@dom66.de> parents: 341 diff changeset	462 configuration tree
c8b98285a7b5 docs: some more docu for tree references Franz Glasner <fzglas.hg@dom66.de> parents: 341 diff changeset	463 - by employing the special namespace ``ref``
340 176e22110fc5 docs, tests: notes and additional tests when quoting the "ref" namespace name Franz Glasner <fzglas.hg@dom66.de> parents: 339 diff changeset	464 - can not be quoted currently in variable interpolation syntax
343 c8b98285a7b5 docs: some more docu for tree references Franz Glasner <fzglas.hg@dom66.de> parents: 341 diff changeset	465 - No special handling when merging is done -- merging is agnostic of
c8b98285a7b5 docs: some more docu for tree references Franz Glasner <fzglas.hg@dom66.de> parents: 341 diff changeset	466 tree references
353 a7491f835cb0 Changelog and minimal docu for `None` and `Empty` filters Franz Glasner <f.glasner@feldmann-mg.com> parents: 347 diff changeset	467 - Keys within :meth:`.Configuration.getvar_s`,
343 c8b98285a7b5 docs: some more docu for tree references Franz Glasner <fzglas.hg@dom66.de> parents: 341 diff changeset	468 :py:meth:`.Configuration.getvar`, :py:meth:`.Configuration.getvarl`
c8b98285a7b5 docs: some more docu for tree references Franz Glasner <fzglas.hg@dom66.de> parents: 341 diff changeset	469 and :py:meth:`.Configuration.getvarl_s` are handled
c8b98285a7b5 docs: some more docu for tree references Franz Glasner <fzglas.hg@dom66.de> parents: 341 diff changeset	470 - in :py:meth:`.Configuration.getvar` only, when it is the directly
333 5ec0ae3bb8db Docs: quoting Franz Glasner <fzglas.hg@dom66.de> parents: 328 diff changeset	471 referenced value
343 c8b98285a7b5 docs: some more docu for tree references Franz Glasner <fzglas.hg@dom66.de> parents: 341 diff changeset	472 - recursive expansion in :py:meth:`.Configuration.getvar_s` and
c8b98285a7b5 docs: some more docu for tree references Franz Glasner <fzglas.hg@dom66.de> parents: 341 diff changeset	473 :py:meth:`.Configuration.getvarl_s`:
c8b98285a7b5 docs: some more docu for tree references Franz Glasner <fzglas.hg@dom66.de> parents: 341 diff changeset	474 beware of recursive (direct or indirect) tree references
333 5ec0ae3bb8db Docs: quoting Franz Glasner <fzglas.hg@dom66.de> parents: 328 diff changeset	475
5ec0ae3bb8db Docs: quoting Franz Glasner <fzglas.hg@dom66.de> parents: 328 diff changeset	476
5ec0ae3bb8db Docs: quoting Franz Glasner <fzglas.hg@dom66.de> parents: 328 diff changeset	477 .. _quoting:
5ec0ae3bb8db Docs: quoting Franz Glasner <fzglas.hg@dom66.de> parents: 328 diff changeset	478
5ec0ae3bb8db Docs: quoting Franz Glasner <fzglas.hg@dom66.de> parents: 328 diff changeset	479 Quoting
5ec0ae3bb8db Docs: quoting Franz Glasner <fzglas.hg@dom66.de> parents: 328 diff changeset	480 -------
5ec0ae3bb8db Docs: quoting Franz Glasner <fzglas.hg@dom66.de> parents: 328 diff changeset	481
5ec0ae3bb8db Docs: quoting Franz Glasner <fzglas.hg@dom66.de> parents: 328 diff changeset	482 When using :py:meth:`.Configuration.getvar` and
5ec0ae3bb8db Docs: quoting Franz Glasner <fzglas.hg@dom66.de> parents: 328 diff changeset	483 :py:meth:`.Configuration.getvar_s` and when retrieving values in the
5ec0ae3bb8db Docs: quoting Franz Glasner <fzglas.hg@dom66.de> parents: 328 diff changeset	484 default namespace the namespace separator ``:`` or the hierarchy
5ec0ae3bb8db Docs: quoting Franz Glasner <fzglas.hg@dom66.de> parents: 328 diff changeset	485 separator ``.`` are characters with a special meaning. When using
5ec0ae3bb8db Docs: quoting Franz Glasner <fzglas.hg@dom66.de> parents: 328 diff changeset	486 :ref:`variable interpolation <variable-interpolation>` the filter
339 ebd662a8376e Docs: fix typo Franz Glasner <fzglas.hg@dom66.de> parents: 333 diff changeset	487 separator ``\|`` is also special. To use them in key names they must be
333 5ec0ae3bb8db Docs: quoting Franz Glasner <fzglas.hg@dom66.de> parents: 328 diff changeset	488 quoted.
5ec0ae3bb8db Docs: quoting Franz Glasner <fzglas.hg@dom66.de> parents: 328 diff changeset	489
5ec0ae3bb8db Docs: quoting Franz Glasner <fzglas.hg@dom66.de> parents: 328 diff changeset	490 Quoting is done with a variant of the well-known percent-encoding in
5ec0ae3bb8db Docs: quoting Franz Glasner <fzglas.hg@dom66.de> parents: 328 diff changeset	491 URIs (:rfc:`3986`).
5ec0ae3bb8db Docs: quoting Franz Glasner <fzglas.hg@dom66.de> parents: 328 diff changeset	492
5ec0ae3bb8db Docs: quoting Franz Glasner <fzglas.hg@dom66.de> parents: 328 diff changeset	493 A percent-encoded character consists of the percent character ``%``,
5ec0ae3bb8db Docs: quoting Franz Glasner <fzglas.hg@dom66.de> parents: 328 diff changeset	494 followed by one of the characters ``x``, ``u`` or ``U``, followed by
5ec0ae3bb8db Docs: quoting Franz Glasner <fzglas.hg@dom66.de> parents: 328 diff changeset	495 the two, four or eight hexadecimal digits of the unicode codepoint
5ec0ae3bb8db Docs: quoting Franz Glasner <fzglas.hg@dom66.de> parents: 328 diff changeset	496 value of the character that is to be quoted. ``x`` must be followed by
5ec0ae3bb8db Docs: quoting Franz Glasner <fzglas.hg@dom66.de> parents: 328 diff changeset	497 two hex digits, ``u`` by four and ``U`` by eight.
5ec0ae3bb8db Docs: quoting Franz Glasner <fzglas.hg@dom66.de> parents: 328 diff changeset	498
5ec0ae3bb8db Docs: quoting Franz Glasner <fzglas.hg@dom66.de> parents: 328 diff changeset	499 Example:
5ec0ae3bb8db Docs: quoting Franz Glasner <fzglas.hg@dom66.de> parents: 328 diff changeset	500
5ec0ae3bb8db Docs: quoting Franz Glasner <fzglas.hg@dom66.de> parents: 328 diff changeset	501 The character ``.`` with the Unicode (and ASCII) value 46 (hex 0x2e)
5ec0ae3bb8db Docs: quoting Franz Glasner <fzglas.hg@dom66.de> parents: 328 diff changeset	502 can be encoded as ``%x2e`` or ``%u002e`` or ``%U0000002e``.
5ec0ae3bb8db Docs: quoting Franz Glasner <fzglas.hg@dom66.de> parents: 328 diff changeset	503
5ec0ae3bb8db Docs: quoting Franz Glasner <fzglas.hg@dom66.de> parents: 328 diff changeset	504 .. note:: Filters neeed no quoting -- and quoting within filters is not
5ec0ae3bb8db Docs: quoting Franz Glasner <fzglas.hg@dom66.de> parents: 328 diff changeset	505 supported.
316 fe2e28e5fd08 Docu: first short notes about configuration tree references Franz Glasner <fzglas.hg@dom66.de> parents: 315 diff changeset	506
340 176e22110fc5 docs, tests: notes and additional tests when quoting the "ref" namespace name Franz Glasner <fzglas.hg@dom66.de> parents: 339 diff changeset	507 .. note:: Quoting the ``ref`` namespace name does not work currently when
176e22110fc5 docs, tests: notes and additional tests when quoting the "ref" namespace name Franz Glasner <fzglas.hg@dom66.de> parents: 339 diff changeset	508 used in variable interpolation syntax.
176e22110fc5 docs, tests: notes and additional tests when quoting the "ref" namespace name Franz Glasner <fzglas.hg@dom66.de> parents: 339 diff changeset	509
316 fe2e28e5fd08 Docu: first short notes about configuration tree references Franz Glasner <fzglas.hg@dom66.de> parents: 315 diff changeset	510
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	511 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	512 ---------------------------------------------
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	513
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	514 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	515 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	516
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	517 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	518 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	519
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	520 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	521
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	522 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	523 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	524
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	525 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	526 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	527
194 0d8dd58afc44 Docu: Enhanced the custom loader section somewhat Franz Glasner <fzglas.hg@dom66.de> parents: 193 diff changeset	528 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	529
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	530 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	531 ...
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	532 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	533
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	534 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	535 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	536 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	537
0d8dd58afc44 Docu: Enhanced the custom loader section somewhat Franz Glasner <fzglas.hg@dom66.de> parents: 193 diff changeset	538 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	539 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	540
fa660f084ceb Docu: an example for configmix.try_determine_filemode() Franz Glasner <fzglas.hg@dom66.de> parents: 202 diff changeset	541 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	542 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	543
fa660f084ceb Docu: an example for configmix.try_determine_filemode() Franz Glasner <fzglas.hg@dom66.de> parents: 202 diff changeset	544 configmix.set_assoc("*", configmix.try_determine_filemode)

Mercurial > hgrepos > Python > libs > ConfigMix

annotate docs/introduction.rst @ 354:bd28fb4565e1