1 .. default-role:: literal
3 The global configuration's consistency
4 ========================================
6 :module: :api:`config.py`
7 :tests: :api:`test_option_consistency.py`
9 Option's values type validation
10 --------------------------------
12 When a value is set to the option, the value is validated by the
13 option's :api:`option.Option()` validator's type.
15 Notice that if the option is `multi`, that is the `multi` attribute is set to
16 `True`, then the validation of the option value accepts a list of values
22 Configuration options can specify requirements as parameters at the init
23 time, the specification of some links between options or groups allows
24 to carry out a dependencies calculation. For example, an option can ben
25 hidden if another option has been set with some expected value. This is
26 just an example, because the possibilities are hudge.
28 A requirement is specified using a list of triplets. The first element
29 of the triplet gives the path of the option that is required, the second
30 element is the value wich is expected to trigger the callback, and the
31 third one is the callback's action name (`hide`, `show`...)::
33 stroption = StrOption('str', 'Test string option', default="abc",
34 requires=[('int', 1, 'hide')])
36 Take a look at an example here
37 :api:`test_option_consistency.test_hidden_if_in()`
42 New configuration options and groups can be dynamically added.
44 The configuration has to be *updated* after that the description has been
45 passed to the Config objet, see:
49 >>> config = Config(descr)
50 >>> newoption = BoolOption('newoption', 'dummy twoo', default=False)
51 >>> descr.add_child(newoption)
58 - :api:`test_option_consistency.test_newoption_add_in_descr()`
59 - :api:`test_option_consistency.test_newoption_add_in_subdescr()`
60 - :api:`test_option_consistency.test_newoption_add_in_config()`
63 Validation upon a whole configuration object
64 ----------------------------------------------
66 An option's integrity can be validated towards a whole configuration.
68 This type of validation is very open. Let's take a use case : an option
69 has a certain value, and the value of this option can change the owner
70 of another option or option group... Everything is possible.
72 For example, the configuration paths have to be unique in the
73 :ref:`glossary#schema`, the validation is carried out at the
74 :api:`config.Config._cfgimpl_build()` time in the
75 :api:`config.Config._validate_duplicates()` method.
77 Other hook are availables to validate upon a whole configuration at any
80 .. FIXME : get the validates hooks from the original config pypy's code
82 Identical option names
83 ----------------------
85 If an :api:`option.Option()` happens to be defined twice in the
86 :ref:`glossary#schema` (e.g. the :api:`option.OptionDescription()`),
87 :that is the two options actually have the same name, an exception is raised.
89 The calculation is currently carried out in the samespace, for example
90 if `config.gc.name` is defined, another option in `gc` with the name
91 `name` is **not** allowed, whereas `config.whateverelse.name` is still
94 .. the calculation was carried out by the requires, wich is not a goog idead
96 Type constraints with the `multi` type
97 ----------------------------------------
99 By convention, if a multi option has somme requires, the constraints on
100 the multi type is in all the OptionGroup (a group has to be `multi`, and
101 a multi of the same length).
103 See :api:`test_option_consistency.test_multi_constraints()`