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

comparison doc/introduction.rst @ 117:c5b638f9c607

- More on getting variable values - Reorga of the variable documentation

author	Franz Glasner <hg@dom66.de>
date	Thu, 29 Mar 2018 08:58:34 +0200
parents	a5339d39af5c
children	21d92ff8cf31

comparison

equal deleted inserted replaced

-:c37fa787c022
+:c5b638f9c607
 ``.ini``
 for INI configuration files
+.. _getting-values:
+Getting configuration variables
+-------------------------------
+Get a -- possibly expanded -- configuration variable's value with::
+value1 = config.getvar_s("key1")
+Get a raw configuration variable's value with::
+value1_raw = config.getvar("key1")
+Because the configuration is not only a plain list of but a tree of
+key-value pairs you will want to fetch them by separating the individual
+level keys with a point ``.``.
+Looking at the example in chapter :ref:`yaml-files` -- when calling
+``config.getvar_s("tree1.tree2.key4")`` you will get the value
+``get this as `tree1.tree2.key4'``.
+This is true for both methods :py:meth:`.Configuration.getvar` and
+:py:meth:`.Configuration.getvar_s`.
+Both methods also perform :ref:`variable-expansion` and handle
+:ref:`variable-namespaces`. Filtering is not supported. So -- the
+variable name arguments of :py:meth:`.Configuration.getvar` and
+:py:meth:`.Configuration.getvar_s` are of the form
+``[namespace:]variable``.
+.. _variable-namespaces:
+Variable Namespaces
+-------------------
+Currently there are 4 namespaces:
+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`
+Examples
+~~~~~~~~
+::
+config.getvar("OS:cwd")
+yields the current working directory as :py:func:`os.getcwd` does.
 .. _variable-expansion:
-Variable Names and Expansion
+Variable Expansion
-----------------------------
+------------------
-Variables are fetched with the API method :py:meth:`.Configuration.getvar`
+Configuration variable values that are read with
-or :py:meth:`.Configuration.getvar_s`.
+:py:meth:`.Configuration.getvar_s` are subject to variable
+expansion. The general syntactic pattern for this is::
-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
+Variables are expanded lately at runtime -- exactly when calling
-:py:meth:`.Configuration.getvar_s`.
+:py:meth:`.Configuration.getvar_s` or :py:meth:`.Configuration.getvar`.
-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
 ~~~~~~~~~~~~~~~~
 ::
 {{OS:cwd|posixpath}}
-yields the current working directory as POSIX path: on Windows all backslashes
+expands to the current working directory as POSIX path: on Windows all
-are replaced by forward slashes.
+backslashes are replaced by forward slashes.
 ::
 {{ENV:PATH}}
-gives the current search path from the process environment.
+expands to the current search path from the process environment.
 ::
 {{PY:version}}
-returns the current running Python version (e.g. ``3.6.4``).
+expands to the current running Python version (e.g. ``3.6.4``).
 ::
 {{PY::implementation|upper}}
-yields something like ``CPYTHON`` when using the standard Python interpreter
+expands to something like ``CPYTHON`` when using the standard Python
-written in C.
+interpreter written in C.

Mercurial > hgrepos > Python > libs > ConfigMix

comparison doc/introduction.rst @ 117:c5b638f9c607