Mercurial > hgrepos > Python > libs > ConfigMix

comparison doc/introduction.rst @ 94:2b79ddc0f92b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Begin a basic introduction chapter
author Franz Glasner <hg@dom66.de>
date Sun, 18 Mar 2018 16:45:51 +0100
parents
children 1b4d95f60650
comparison
equal deleted inserted replaced
93:84b9578cacce 94:2b79ddc0f92b
1 .. -*- coding: utf-8; indent-tabs-mode: nil; -*-
2
3 .. _introduction:
4
5 Introduction
6 ============
7
8 The configurations can be read from different types of files:
9
10 - :ref:`YAML files <yaml-files>`
11 - :ref:`INI files <ini-files>`
12 - :ref:`executable Python scripts <executable-python-scripts>`
13
14 .. todo:: Describe evaluation syntax
15
16 .. todo:: Describe available filter functions (and syntax)
17
18 .. todo:: Describe late evaluation of interpolation strings
19
20
21 .. _yaml-files:
22
23 YAML Files
24 ----------
25
26 Need the :mod:`yaml` package (e.g. ``pip install pyyaml``)
27
28 .. note:: All strings are returned as Unicode text strings.
29
30
31 .. _ini-files:
32
33 INI Files
34 ---------
35
36 Read the file and all sections named in parameter `extract` are flattened
37 into the resulting dictionary. By default the section named ``config`` is
38 used.
39
40 Normally all values are returned as Unicode text strings.
41 But values can be annotated and therefore interpreted as other types:
42
43 ``:int:``
44 The value is handled in the same way as a Python :class:`int`
45 literal
46
47 ``:float:``
48 The value is interpreted as :class:`float`
49
50 ``:bool:``
51 The resulting value is a :class:`bool` where
52
53 ``1``, ``true``, ``yes``, ``on``
54 yield a Python ``True``
55
56 ``0``, ``false``, ``no``, ``off``
57 yield a Python ``False``
58
59 The evaluation is done *case-insensitively*.
60
61 .. note:: All strings are returned as Unicode text strings.
62
63 .. note:: Contrary to the behaviour of the standard Python :mod:`configparser`
64 module the INI file reader is *case-sensitive*.
65
66 .. todo:: Implement tree-ish interpretation of INI files
67
68 Currently there is no tree.
69
70
71 .. _executable-python-scripts:
72
73 Executable Python Scripts
74 -------------------------
75
76 What will be exported:
77
78 1. If loading is done with the `extract` parameter only the given keys are
79 extracted from the script.
80
81 2. Otherwise it is checked if the scripts defines an ``__all__``
82 sequence. If there is one it's contents are the keys to be
83 extracted.
84
85 3. If there is no ``__all__`` object all names not starting with an
86 underscore ``_`` are found.
87
88 This is analogous to as Python modules behave when importing them with
89 ``from module import *``.
90
91 .. note:: The Python configuration files are evaluated with ``exec`` and not
92 imported.