Mercurial > hgrepos > Python > libs > ConfigMix
annotate doc/introduction.rst @ 114:aa0c61e79660
Add a documentation section about basic API usage: loading (and merging)
| author | Franz Glasner <hg@dom66.de> |
|---|---|
| date | Sat, 24 Mar 2018 22:09:44 +0100 |
| parents | 1b4d95f60650 |
| children | a5339d39af5c |
| rev | line source |
|---|---|
| 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 | |
|
97
1b4d95f60650
Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents:
94
diff
changeset
|
31 An example is: |
|
1b4d95f60650
Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents:
94
diff
changeset
|
32 |
|
1b4d95f60650
Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents:
94
diff
changeset
|
33 .. literalinclude:: ../tests/data/conf10.yml |
|
1b4d95f60650
Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents:
94
diff
changeset
|
34 :language: yaml |
|
1b4d95f60650
Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents:
94
diff
changeset
|
35 |
|
1b4d95f60650
Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents:
94
diff
changeset
|
36 |
| 94 | 37 .. _ini-files: |
| 38 | |
| 39 INI Files | |
| 40 --------- | |
| 41 | |
| 42 Read the file and all sections named in parameter `extract` are flattened | |
| 43 into the resulting dictionary. By default the section named ``config`` is | |
| 44 used. | |
| 45 | |
| 46 Normally all values are returned as Unicode text strings. | |
| 47 But values can be annotated and therefore interpreted as other types: | |
| 48 | |
| 49 ``:int:`` | |
| 50 The value is handled in the same way as a Python :class:`int` | |
| 51 literal | |
| 52 | |
| 53 ``:float:`` | |
| 54 The value is interpreted as :class:`float` | |
| 55 | |
| 56 ``:bool:`` | |
| 57 The resulting value is a :class:`bool` where | |
| 58 | |
| 59 ``1``, ``true``, ``yes``, ``on`` | |
| 60 yield a Python ``True`` | |
| 61 | |
| 62 ``0``, ``false``, ``no``, ``off`` | |
| 63 yield a Python ``False`` | |
| 64 | |
| 65 The evaluation is done *case-insensitively*. | |
| 66 | |
| 67 .. note:: All strings are returned as Unicode text strings. | |
| 68 | |
| 69 .. note:: Contrary to the behaviour of the standard Python :mod:`configparser` | |
| 70 module the INI file reader is *case-sensitive*. | |
| 71 | |
|
97
1b4d95f60650
Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents:
94
diff
changeset
|
72 .. todo:: Document the build of tree-ish configuration settings out of |
|
1b4d95f60650
Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents:
94
diff
changeset
|
73 INI files. |
|
1b4d95f60650
Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents:
94
diff
changeset
|
74 |
|
1b4d95f60650
Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents:
94
diff
changeset
|
75 The example INI style configuration below yields an equivalent |
|
1b4d95f60650
Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents:
94
diff
changeset
|
76 configuration to the YAML configuration above: |
| 94 | 77 |
|
97
1b4d95f60650
Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents:
94
diff
changeset
|
78 .. literalinclude:: ../tests/data/conf10.ini |
|
1b4d95f60650
Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents:
94
diff
changeset
|
79 :language: ini |
|
1b4d95f60650
Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents:
94
diff
changeset
|
80 |
|
1b4d95f60650
Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents:
94
diff
changeset
|
81 As can be seen in thie example -- INI file internal value interpolation |
|
1b4d95f60650
Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents:
94
diff
changeset
|
82 is done as in Python's standard :mod:`configparser` module. |
|
1b4d95f60650
Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents:
94
diff
changeset
|
83 |
|
1b4d95f60650
Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents:
94
diff
changeset
|
84 This example also illustrates how INI sections are used to build a |
|
1b4d95f60650
Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents:
94
diff
changeset
|
85 tree-ish configuration dictionary. |
| 94 | 86 |
| 87 | |
| 88 .. _executable-python-scripts: | |
| 89 | |
| 90 Executable Python Scripts | |
| 91 ------------------------- | |
| 92 | |
| 93 What will be exported: | |
| 94 | |
| 95 1. If loading is done with the `extract` parameter only the given keys are | |
| 96 extracted from the script. | |
| 97 | |
| 98 2. Otherwise it is checked if the scripts defines an ``__all__`` | |
| 99 sequence. If there is one it's contents are the keys to be | |
| 100 extracted. | |
| 101 | |
| 102 3. If there is no ``__all__`` object all names not starting with an | |
| 103 underscore ``_`` are found. | |
| 104 | |
| 105 This is analogous to as Python modules behave when importing them with | |
| 106 ``from module import *``. | |
| 107 | |
| 108 .. note:: The Python configuration files are evaluated with ``exec`` and not | |
| 109 imported. | |
|
97
1b4d95f60650
Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents:
94
diff
changeset
|
110 |
|
1b4d95f60650
Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents:
94
diff
changeset
|
111 The example configuration by Python script below yields an equivalent |
|
1b4d95f60650
Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents:
94
diff
changeset
|
112 configuration to the YAML configuration above: |
|
1b4d95f60650
Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents:
94
diff
changeset
|
113 |
|
1b4d95f60650
Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents:
94
diff
changeset
|
114 .. literalinclude:: ../tests/data/conf10.py |
|
1b4d95f60650
Build a tree-ish configuration from an INI style configuration file
Franz Glasner <hg@dom66.de>
parents:
94
diff
changeset
|
115 :language: python |
|
114
aa0c61e79660
Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents:
97
diff
changeset
|
116 |
|
aa0c61e79660
Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents:
97
diff
changeset
|
117 |
|
aa0c61e79660
Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents:
97
diff
changeset
|
118 .. _loading-and-merging: |
|
aa0c61e79660
Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents:
97
diff
changeset
|
119 |
|
aa0c61e79660
Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents:
97
diff
changeset
|
120 Loading and Merging |
|
aa0c61e79660
Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents:
97
diff
changeset
|
121 ------------------- |
|
aa0c61e79660
Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents:
97
diff
changeset
|
122 |
|
aa0c61e79660
Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents:
97
diff
changeset
|
123 Basic usage of the API is as follows in this example:: |
|
aa0c61e79660
Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents:
97
diff
changeset
|
124 |
|
aa0c61e79660
Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents:
97
diff
changeset
|
125 import configmix |
|
aa0c61e79660
Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents:
97
diff
changeset
|
126 |
|
aa0c61e79660
Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents:
97
diff
changeset
|
127 # |
|
aa0c61e79660
Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents:
97
diff
changeset
|
128 # Note: With conf10 merging is rather pointless because the tree |
|
aa0c61e79660
Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents:
97
diff
changeset
|
129 # files # are really the same configuration. But is doesn't harm |
|
aa0c61e79660
Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents:
97
diff
changeset
|
130 # also here. |
|
aa0c61e79660
Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents:
97
diff
changeset
|
131 # |
|
aa0c61e79660
Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents:
97
diff
changeset
|
132 config = configmix.load("conf10.yml", "conf10.ini", "conf10.py") |
|
aa0c61e79660
Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents:
97
diff
changeset
|
133 |
|
aa0c61e79660
Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents:
97
diff
changeset
|
134 # Get a -- possibly interpolated -- configuration variable's value |
|
aa0c61e79660
Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents:
97
diff
changeset
|
135 value1 = config.getvar_s("key1") |
|
aa0c61e79660
Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents:
97
diff
changeset
|
136 |
|
aa0c61e79660
Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents:
97
diff
changeset
|
137 # Get a -- possibly interpolated -- variable from within the tree |
|
aa0c61e79660
Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents:
97
diff
changeset
|
138 value2 = config.getvar_s("tree1.tree2.key4") |
|
aa0c61e79660
Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents:
97
diff
changeset
|
139 |
|
aa0c61e79660
Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents:
97
diff
changeset
|
140 |
|
aa0c61e79660
Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents:
97
diff
changeset
|
141 The filenames of the configuration files must have the extensions |
|
aa0c61e79660
Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents:
97
diff
changeset
|
142 (case-insensitively): |
|
aa0c61e79660
Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents:
97
diff
changeset
|
143 |
|
aa0c61e79660
Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents:
97
diff
changeset
|
144 ``.py`` |
|
aa0c61e79660
Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents:
97
diff
changeset
|
145 for Python configuration files |
|
aa0c61e79660
Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents:
97
diff
changeset
|
146 |
|
aa0c61e79660
Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents:
97
diff
changeset
|
147 ``.yml`` or ``.yaml`` |
|
aa0c61e79660
Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents:
97
diff
changeset
|
148 for YAML configuration files |
|
aa0c61e79660
Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents:
97
diff
changeset
|
149 |
|
aa0c61e79660
Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents:
97
diff
changeset
|
150 ``.ini`` |
|
aa0c61e79660
Add a documentation section about basic API usage: loading (and merging)
Franz Glasner <hg@dom66.de>
parents:
97
diff
changeset
|
151 for INI configuration files |