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

comparison 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

comparison

equal deleted inserted replaced

-:aa0c61e79660
+:a5339d39af5c
 - :ref:`YAML files <yaml-files>`
 - :ref:`INI files <ini-files>`
 - :ref:`executable Python scripts <executable-python-scripts>`
-.. todo:: Describe evaluation syntax
-.. todo:: Describe available filter functions (and syntax)
-.. todo:: Describe late evaluation of interpolation strings
 .. _yaml-files:
 YAML Files
 ----------
 .. note:: All strings are returned as Unicode text strings.
 .. note:: Contrary to the behaviour of the standard Python :mod:`configparser`
 module the INI file reader is *case-sensitive*.
-.. todo:: Document the build of tree-ish configuration settings out of
-INI files.
 The example INI style configuration below yields an equivalent
 configuration to the YAML configuration above:
 .. literalinclude:: ../tests/data/conf10.ini
 ``.yml`` or ``.yaml``
 for YAML configuration files
 ``.ini``
 for INI configuration files
+.. _variable-expansion:
+Variable Names and Expansion
+----------------------------
+Variables are fetched with the API method :py:meth:`.Configuration.getvar`
+or :py:meth:`.Configuration.getvar_s`.
+Variable tree levels are separated with a point ``.`` when trying to
+fetch them.
+Looking at the example in chapter :ref:`yaml-files` -- when calling
+``myconfig.getvar_s("tree1.tree2.key4")`` you will get the value
+``get this as `tree1.tree2.key4'``.
+Additionally -- configuration variable values that are read with
+:py:meth:`.Configuration.getvar_s` are subject to
+variable expansion. The general syntactic pattern for this is::
+{{[namespace:]variable[|filter[|filter...]]}}
+I.e.: between double curly braces an optional `namespace` name followed by
+a colon ``:``, the `variable` and then zero or more filters, each one
+introduced by a pipe symbol ``|``.
+Variables are expanded at request at runtime -- exactly when calling
+:py:meth:`.Configuration.getvar_s`.
+Variable Namespaces
+~~~~~~~~~~~~~~~~~~~
+There are 4 namespaces currently:
+1. The unnamed namespace (which is also default).
+All the configuration variables are part of this namespace.
+2. The namespace ``OS``
+Available functions:
+``cwd``
+Contains the current working directory of the process
+3. The namespace ``ENV``
+This namespace contains all the environment variables as they are
+available from :py:data:`os.environ`.
+4. The namespace ``PY``
+Contains selected values from the running Python:
+``version``
+The return value of :py:func:`platform.python_version`
+``version_maj_min``
+Just the major and minor version of the running Python
+(``.`` separated)
+``version_maj``
+Just the major version of the running Python
+``implementation``
+The return value of :py:func:`platform.python_implementation`
+Filter functions
+~~~~~~~~~~~~~~~~
+Interpolated values can be processed through a series of filter functions::
+{{my.variable|filter1|filter2}}
+Available filter functions are:
+``urlquote``
+``saslprep``
+``normpath``
+``abspath``
+``posixpath``
+``lower``
+``upper``
+Examples
+~~~~~~~~
+::
+{{OS:cwd|posixpath}}
+yields the current working directory as POSIX path: on Windows all backslashes
+are replaced by forward slashes.
+::
+{{ENV:PATH}}
+gives the current search path from the process environment.
+::
+{{PY:version}}
+returns the current running Python version (e.g. ``3.6.4``).
+::
+{{PY::implementation|upper}}
+yields something like ``CPYTHON`` when using the standard Python interpreter
+written in C.

Mercurial > hgrepos > Python > libs > ConfigMix

comparison doc/introduction.rst @ 115:a5339d39af5c