|
94
|
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. |
