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

annotate doc/introduction.rst @ 115:a5339d39af5c

Begin the documentation of variables and its expansion

author	Franz Glasner <hg@dom66.de>
date	Sun, 25 Mar 2018 16:45:15 +0200
parents	aa0c61e79660
children	c5b638f9c607

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>`
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	11 - :ref:`INI files <ini-files>`
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	12 - :ref:`executable Python scripts <executable-python-scripts>`
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	13
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 .. _yaml-files:
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	16
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	17 YAML Files
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 Need the :mod:`yaml` package (e.g. ``pip install pyyaml``)
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 .. note:: All strings are returned as Unicode text strings.
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
97 1b4d95f60650 Build a tree-ish configuration from an INI style configuration file Franz Glasner <hg@dom66.de> parents: 94 diff changeset	25 An example is:
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file Franz Glasner <hg@dom66.de> parents: 94 diff changeset	26
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file Franz Glasner <hg@dom66.de> parents: 94 diff changeset	27 .. 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	28 :language: yaml
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
94 2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	31 .. _ini-files:
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	32
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	33 INI Files
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	34 ---------
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	35
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	36 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	37 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	38 used.
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	39
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	40 Normally all values are returned as Unicode text strings.
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	41 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	42
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	43 ``:int:``
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	44 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	45 literal
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	46
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	47 ``:float:``
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	48 The value is interpreted as :class:`float`
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	49
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	50 ``:bool:``
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	51 The resulting value is a :class:`bool` where
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	52
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	53 ``1``, ``true``, ``yes``, ``on``
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	54 yield a Python ``True``
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	55
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	56 ``0``, ``false``, ``no``, ``off``
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	57 yield a Python ``False``
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	58
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	59 The evaluation is done case-insensitively.
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 .. note:: All strings are returned as Unicode text strings.
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 .. 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	64 module the INI file reader is case-sensitive.
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	65
97 1b4d95f60650 Build a tree-ish configuration from an INI style configuration file Franz Glasner <hg@dom66.de> parents: 94 diff changeset	66 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	67 configuration to the YAML configuration above:
94 2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	68
97 1b4d95f60650 Build a tree-ish configuration from an INI style configuration file Franz Glasner <hg@dom66.de> parents: 94 diff changeset	69 .. 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	70 :language: ini
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file Franz Glasner <hg@dom66.de> parents: 94 diff changeset	71
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file Franz Glasner <hg@dom66.de> parents: 94 diff changeset	72 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	73 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	74
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file Franz Glasner <hg@dom66.de> parents: 94 diff changeset	75 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	76 tree-ish configuration dictionary.
94 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
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	79 .. _executable-python-scripts:
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 Executable Python Scripts
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
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	84 What will be exported:
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 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	87 extracted from the script.
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 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	90 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	91 extracted.
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 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	94 underscore ``_`` are found.
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	95
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	96 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	97 ``from module import *``.
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	98
2b79ddc0f92b Begin a basic introduction chapter Franz Glasner <hg@dom66.de> parents: diff changeset	99 .. 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	100 imported.
97 1b4d95f60650 Build a tree-ish configuration from an INI style configuration file Franz Glasner <hg@dom66.de> parents: 94 diff changeset	101
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file Franz Glasner <hg@dom66.de> parents: 94 diff changeset	102 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	103 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	104
1b4d95f60650 Build a tree-ish configuration from an INI style configuration file Franz Glasner <hg@dom66.de> parents: 94 diff changeset	105 .. 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	106 :language: python
114 aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	107
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	108
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	109 .. _loading-and-merging:
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	110
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	111 Loading and Merging
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	112 -------------------
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	113
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	114 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	115
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	116 import configmix
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	117
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	118 #
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	119 # 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	120 # 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	121 # also here.
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	122 #
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	123 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	124
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	125 # 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	126 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	127
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	128 # 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	129 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	130
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	131
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	132 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	133 (case-insensitively):
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	134
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	135 ``.py``
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	136 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	137
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	138 ``.yml`` or ``.yaml``
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	139 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	140
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	141 ``.ini``
aa0c61e79660 Add a documentation section about basic API usage: loading (and merging) Franz Glasner <hg@dom66.de> parents: 97 diff changeset	142 for INI configuration files
115 a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	143
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	144
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	145 .. _variable-expansion:
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	146
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	147 Variable Names and Expansion
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	148 ----------------------------
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	149
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	150 Variables are fetched with the API method :py:meth:`.Configuration.getvar`
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	151 or :py:meth:`.Configuration.getvar_s`.
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	152
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	153 Variable tree levels are separated with a point ``.`` when trying to
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	154 fetch them.
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	155
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	156 Looking at the example in chapter :ref:`yaml-files` -- when calling
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	157 ``myconfig.getvar_s("tree1.tree2.key4")`` you will get the value
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	158 ``get this as `tree1.tree2.key4'``.
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	159
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	160 Additionally -- configuration variable values that are read with
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	161 :py:meth:`.Configuration.getvar_s` are subject to
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	162 variable expansion. The general syntactic pattern for this is::
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	163
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	164 {{[namespace:]variable[\|filter[\|filter...]]}}
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	165
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	166 I.e.: between double curly braces an optional `namespace` name followed by
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	167 a colon ``:``, the `variable` and then zero or more filters, each one
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	168 introduced by a pipe symbol ``\|``.
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	169
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	170 Variables are expanded at request at runtime -- exactly when calling
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	171 :py:meth:`.Configuration.getvar_s`.
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	172
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	173
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	174 Variable Namespaces
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	175 ~~~~~~~~~~~~~~~~~~~
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	176
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	177 There are 4 namespaces currently:
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	178
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	179 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	180
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	181 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	182
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	183 2. The namespace ``OS``
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	184
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	185 Available functions:
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	186
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	187 ``cwd``
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	188 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	189
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	190 3. The namespace ``ENV``
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	191
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	192 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	193 available from :py:data:`os.environ`.
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	194
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	195 4. The namespace ``PY``
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	196
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	197 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	198
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	199 ``version``
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	200 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	201
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	202 ``version_maj_min``
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	203 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	204 (``.`` separated)
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 ``version_maj``
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	207 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	208
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	209 ``implementation``
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	210 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	211
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 Filter functions
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
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	216 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	217
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	218 {{my.variable\|filter1\|filter2}}
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	219
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	220 Available filter functions are:
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 ``urlquote``
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 ``saslprep``
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	225
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	226 ``normpath``
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	227
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	228 ``abspath``
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	229
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	230 ``posixpath``
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	231
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	232 ``lower``
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 ``upper``
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	235
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	236
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	237 Examples
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	238 ~~~~~~~~
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	239
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	240 ::
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	241
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	242 {{OS:cwd\|posixpath}}
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 yields the current working directory as POSIX path: on Windows all backslashes
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	245 are replaced by forward slashes.
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	246
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	247 ::
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	248
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	249 {{ENV:PATH}}
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	250
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	251 gives the current search path from the process environment.
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	252
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	253
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	254 ::
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	255
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	256 {{PY:version}}
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	257
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	258 returns the current running Python version (e.g. ``3.6.4``).
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	259
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	260 ::
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	261
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	262 {{PY::implementation\|upper}}
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	263
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	264 yields something like ``CPYTHON`` when using the standard Python interpreter
a5339d39af5c Begin the documentation of variables and its expansion Franz Glasner <hg@dom66.de> parents: 114 diff changeset	265 written in C.

Mercurial > hgrepos > Python > libs > ConfigMix

annotate doc/introduction.rst @ 115:a5339d39af5c