Mercurial > hgrepos > Python > libs > ConfigMix
changeset 94:2b79ddc0f92b
Begin a basic introduction chapter
| author | Franz Glasner <hg@dom66.de> |
|---|---|
| date | Sun, 18 Mar 2018 16:45:51 +0100 |
| parents | 84b9578cacce |
| children | a0ed95975980 |
| files | README.txt doc/conf.py doc/index.rst doc/introduction.rst doc/todo.rst |
| diffstat | 5 files changed, 108 insertions(+), 1 deletions(-) [+] |
line wrap: on
line diff
--- a/README.txt Sun Mar 18 14:44:41 2018 +0100 +++ b/README.txt Sun Mar 18 16:45:51 2018 +0100 @@ -19,7 +19,7 @@ - YAML files - INI files -- executable Python files +- executable Python scripts It then merges them together into a tree-ish configuration dictionary and presents them as such to the API user. Reading can be done with
--- a/doc/conf.py Sun Mar 18 14:44:41 2018 +0100 +++ b/doc/conf.py Sun Mar 18 16:45:51 2018 +0100 @@ -200,6 +200,8 @@ # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = True +# Kein Link auf Pfad und Zeile +todo_link_only = True # -- Options for autodoc -----------------------------------------------------
--- a/doc/index.rst Sun Mar 18 14:44:41 2018 +0100 +++ b/doc/index.rst Sun Mar 18 16:45:51 2018 +0100 @@ -16,8 +16,10 @@ :maxdepth: 3 readme + introduction apidoc changes + todo authors license
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/introduction.rst Sun Mar 18 16:45:51 2018 +0100 @@ -0,0 +1,92 @@ +.. -*- coding: utf-8; indent-tabs-mode: nil; -*- + +.. _introduction: + +Introduction +============ + +The configurations can be read from different types of files: + +- :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 +---------- + +Need the :mod:`yaml` package (e.g. ``pip install pyyaml``) + +.. note:: All strings are returned as Unicode text strings. + + +.. _ini-files: + +INI Files +--------- + +Read the file and all sections named in parameter `extract` are flattened +into the resulting dictionary. By default the section named ``config`` is +used. + +Normally all values are returned as Unicode text strings. +But values can be annotated and therefore interpreted as other types: + + ``:int:`` + The value is handled in the same way as a Python :class:`int` + literal + + ``:float:`` + The value is interpreted as :class:`float` + + ``:bool:`` + The resulting value is a :class:`bool` where + + ``1``, ``true``, ``yes``, ``on`` + yield a Python ``True`` + + ``0``, ``false``, ``no``, ``off`` + yield a Python ``False`` + + The evaluation is done *case-insensitively*. + +.. 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:: Implement tree-ish interpretation of INI files + + Currently there is no tree. + + +.. _executable-python-scripts: + +Executable Python Scripts +------------------------- + +What will be exported: + +1. If loading is done with the `extract` parameter only the given keys are + extracted from the script. + +2. Otherwise it is checked if the scripts defines an ``__all__`` + sequence. If there is one it's contents are the keys to be + extracted. + +3. If there is no ``__all__`` object all names not starting with an + underscore ``_`` are found. + +This is analogous to as Python modules behave when importing them with +``from module import *``. + +.. note:: The Python configuration files are evaluated with ``exec`` and not + imported.