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

annotate doc/introduction.rst @ 132:4ec783899835

Note that the root object of a YAML style configuration must be a dict alike (mapping)

author	Franz Glasner <hg@dom66.de>
date	Wed, 04 Apr 2018 23:50:37 +0200
parents	b34ad08e7198
children	05cb18c8697a

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
132 4ec783899835 Note that the root object of a YAML style configuration must be a dict alike (mapping) Franz Glasner <hg@dom66.de> parents: 131 diff changeset	25 .. note:: The root object must be a mapping and therefore decode into
4ec783899835 Note that the root object of a YAML style configuration must be a dict alike (mapping) Franz Glasner <hg@dom66.de> parents: 131 diff changeset	26 a Python :class:`dict` alike.
94 2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	27
97 1b4d95f60650 Build a tree-ish configuration from an INI style configuration file Franz Glasner <hg@dom66.de> parents: 94 diff changeset	28 An example is:
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file Franz Glasner <hg@dom66.de> parents: 94 diff changeset	29
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file Franz Glasner <hg@dom66.de> parents: 94 diff changeset	30 .. 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	31 :language: yaml
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file Franz Glasner <hg@dom66.de> parents: 94 diff changeset	32
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file Franz Glasner <hg@dom66.de> parents: 94 diff changeset	33
122 21d92ff8cf31 Begin the handling of JSON-style configuration files Franz Glasner <hg@dom66.de> parents: 117 diff changeset	34 .. _json-files:
21d92ff8cf31 Begin the handling of JSON-style configuration files Franz Glasner <hg@dom66.de> parents: 117 diff changeset	35
21d92ff8cf31 Begin the handling of JSON-style configuration files Franz Glasner <hg@dom66.de> parents: 117 diff changeset	36 JSON files
21d92ff8cf31 Begin the handling of JSON-style configuration files Franz Glasner <hg@dom66.de> parents: 117 diff changeset	37 ----------
21d92ff8cf31 Begin the handling of JSON-style configuration files Franz Glasner <hg@dom66.de> parents: 117 diff changeset	38
131 b34ad08e7198 Document the JSON files Franz Glasner <hg@dom66.de> parents: 122 diff changeset	39 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	40
b34ad08e7198 Document the JSON files Franz Glasner <hg@dom66.de> parents: 122 diff changeset	41 .. note:: All strings are returned as Unicode text strings.
b34ad08e7198 Document the JSON files Franz Glasner <hg@dom66.de> parents: 122 diff changeset	42
b34ad08e7198 Document the JSON files Franz Glasner <hg@dom66.de> parents: 122 diff changeset	43 .. note:: The root object must be an object and therefore decode into
b34ad08e7198 Document the JSON files Franz Glasner <hg@dom66.de> parents: 122 diff changeset	44 a Python :class:`dict` alike.
b34ad08e7198 Document the JSON files Franz Glasner <hg@dom66.de> parents: 122 diff changeset	45
b34ad08e7198 Document the JSON files Franz Glasner <hg@dom66.de> parents: 122 diff changeset	46 .. todo:: Handle JSON comments by special attributes which will
b34ad08e7198 Document the JSON files Franz Glasner <hg@dom66.de> parents: 122 diff changeset	47 filtered out on further processing. Javascript comments are
b34ad08e7198 Document the JSON files Franz Glasner <hg@dom66.de> parents: 122 diff changeset	48 not allowed by the JSON specification.
b34ad08e7198 Document the JSON files Franz Glasner <hg@dom66.de> parents: 122 diff changeset	49
b34ad08e7198 Document the JSON files Franz Glasner <hg@dom66.de> parents: 122 diff changeset	50 An example is:
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 .. literalinclude:: ../tests/data/conf10.json
b34ad08e7198 Document the JSON files Franz Glasner <hg@dom66.de> parents: 122 diff changeset	53 :language: js
122 21d92ff8cf31 Begin the handling of JSON-style configuration files Franz Glasner <hg@dom66.de> parents: 117 diff changeset	54
21d92ff8cf31 Begin the handling of JSON-style configuration files Franz Glasner <hg@dom66.de> parents: 117 diff changeset	55
94 2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	56 .. _ini-files:
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	57
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
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	61 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	62 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	63 used.
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 Normally all values are returned as Unicode text strings.
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	66 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	67
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	68 ``:int:``
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	69 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	70 literal
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	71
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	72 ``:float:``
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	73 The value is interpreted as :class:`float`
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	74
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	75 ``:bool:``
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	76 The resulting value is a :class:`bool` where
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	77
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	78 ``1``, ``true``, ``yes``, ``on``
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	79 yield a Python ``True``
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	80
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	81 ``0``, ``false``, ``no``, ``off``
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	82 yield a Python ``False``
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	83
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	84 The evaluation is done case-insensitively.
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 .. note:: All strings are returned as Unicode text strings.
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:: Contrary to the behaviour of the standard Python :mod:`configparser`
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	89 module the INI file reader is case-sensitive.
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	90
97 1b4d95f60650 Build a tree-ish configuration from an INI style configuration file Franz Glasner <hg@dom66.de> parents: 94 diff changeset	91 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	92 configuration to the YAML configuration above:
94 2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	93
97 1b4d95f60650 Build a tree-ish configuration from an INI style configuration file Franz Glasner <hg@dom66.de> parents: 94 diff changeset	94 .. 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	95 :language: ini
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file Franz Glasner <hg@dom66.de> parents: 94 diff changeset	96
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file Franz Glasner <hg@dom66.de> parents: 94 diff changeset	97 As can be seen in thie example -- INI file internal value interpolation
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file Franz Glasner <hg@dom66.de> parents: 94 diff changeset	98 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	99
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file Franz Glasner <hg@dom66.de> parents: 94 diff changeset	100 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	101 tree-ish configuration dictionary.
94 2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	102
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	103
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	104 .. _executable-python-scripts:
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
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	109 What will be exported:
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 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	112 extracted from the script.
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	113
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	114 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	115 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	116 extracted.
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	117
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	118 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	119 underscore ``_`` are found.
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	120
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	121 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	122 ``from module import *``.
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	123
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	124 .. 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	125 imported.
97 1b4d95f60650 Build a tree-ish configuration from an INI style configuration file Franz Glasner <hg@dom66.de> parents: 94 diff changeset	126
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file Franz Glasner <hg@dom66.de> parents: 94 diff changeset	127 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	128 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	129
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file Franz Glasner <hg@dom66.de> parents: 94 diff changeset	130 .. 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	131 :language: python
114 aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	132
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	133
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	134 .. _loading-and-merging:
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
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	139 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	140
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	141 import configmix
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 #
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	144 # 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	145 # 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	146 # also here.
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	147 #
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	148 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	149
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	150 # 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	151 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	152
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	153 # 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	154 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	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 The filenames of the configuration files must have the extensions
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	158 (case-insensitively):
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	159
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	160 ``.py``
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	161 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	162
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	163 ``.yml`` or ``.yaml``
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	164 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	165
122 21d92ff8cf31 Begin the handling of JSON-style configuration files Franz Glasner <hg@dom66.de> parents: 117 diff changeset	166 ``.json``
21d92ff8cf31 Begin the handling of JSON-style configuration files Franz Glasner <hg@dom66.de> parents: 117 diff changeset	167 for JSON configuration files
21d92ff8cf31 Begin the handling of JSON-style configuration files Franz Glasner <hg@dom66.de> parents: 117 diff changeset	168
114 aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	169 ``.ini``
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	170 for INI configuration files
115 a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	171
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	172
117 c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	173 .. _getting-values:
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 configuration variables
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	176 -------------------------------
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	177
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	178 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	179
117 c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	180 value1 = config.getvar_s("key1")
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	181
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	182 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	183
117 c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	184 value1_raw = config.getvar("key1")
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	185
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	186 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	187 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	188 level keys with a point ``.``.
115 a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	189
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	190 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	191 ``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	192 ``get this as `tree1.tree2.key4'``.
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	193
117 c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	194 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	195 :py:meth:`.Configuration.getvar_s`.
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	196
117 c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	197 Both methods also perform :ref:`variable-expansion` and handle
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	198 :ref:`variable-namespaces`. Filtering is not supported. So -- the
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	199 variable name arguments of :py:meth:`.Configuration.getvar` and
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	200 :py:meth:`.Configuration.getvar_s` are of the form
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	201 ``[namespace:]variable``.
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
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	204 .. _variable-namespaces:
115 a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	205
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	206 Variable Namespaces
117 c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	207 -------------------
115 a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	208
117 c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	209 Currently there are 4 namespaces:
115 a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	210
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	211 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	212
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	213 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	214
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	215 2. The namespace ``OS``
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 Available functions:
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 ``cwd``
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	220 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	221
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	222 3. The namespace ``ENV``
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 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	225 available from :py:data:`os.environ`.
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	226
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	227 4. The namespace ``PY``
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 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	230
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	231 ``version``
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	232 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	233
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	234 ``version_maj_min``
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	235 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	236 (``.`` separated)
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	237
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	238 ``version_maj``
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	239 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	240
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	241 ``implementation``
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	242 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	243
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	244
117 c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	245 Examples
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	246 ~~~~~~~~
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	247
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 config.getvar("OS:cwd")
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 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	253
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	254
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	255 .. _variable-expansion:
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
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	260 Configuration variable values that are read with
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	261 :py:meth:`.Configuration.getvar_s` are subject to variable
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	262 expansion. The general syntactic pattern for this is::
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	263
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	264 {{[namespace:]variable[\|filter[\|filter...]]}}
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 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	267 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	268 introduced by a pipe symbol ``\|``.
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	269
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	270 Variables are expanded lately at runtime -- exactly when calling
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	271 :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	272
c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	273
115 a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	274 Filter functions
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	275 ~~~~~~~~~~~~~~~~
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	276
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	277 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	278
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	279 {{my.variable\|filter1\|filter2}}
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 Available filter functions are:
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 ``urlquote``
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 ``saslprep``
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 ``normpath``
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 ``abspath``
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 ``posixpath``
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 ``lower``
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 ``upper``
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
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	298 Examples
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
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 {{OS:cwd\|posixpath}}
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	304
117 c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	305 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	306 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	307
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	308 ::
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 {{ENV:PATH}}
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	311
117 c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	312 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	313
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	314 ::
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	315
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	316 {{PY:version}}
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	317
117 c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	318 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	319
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	320 ::
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	321
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	322 {{PY::implementation\|upper}}
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	323
117 c5b638f9c607 - More on getting variable values Franz Glasner <hg@dom66.de> parents: 115 diff changeset	324 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	325 interpreter written in C.

Mercurial > hgrepos > Python > libs > ConfigMix

annotate doc/introduction.rst @ 132:4ec783899835