doc/consistency.txt

   1 .. default-role:: literal
   2
   3 The global configuration's consistency
   4 ========================================
   5
   6 :module: :api:`config.py`
   7 :tests: :api:`test_option_consistency.py`
   8
   9 Option's values type validation
  10 --------------------------------
  11
  12 When a value is set to the option, the value is validated by the
  13 option's :api:`option.Option()` validator's type.
  14
  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
  17 of the same type.
  18
  19 Requirements
  20 ------------
  21
  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.
  27
  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`...)::
  32
  33     stroption = StrOption('str', 'Test string option', default="abc",
  34                           requires=[('int', 1, 'hide')])
  35
  36 Take a look at an example here
  37 :api:`test_option_consistency.test_hidden_if_in()`
  38
  39 Config updates
  40 ---------------
  41
  42 New configuration options and groups can be dynamically added.
  43
  44 The configuration has to be *updated* after that the description has been
  45 passed to the Config objet, see:
  46
  47 ::
  48
  49     >>> config = Config(descr)
  50     >>> newoption = BoolOption('newoption', 'dummy twoo', default=False)
  51     >>> descr.add_child(newoption)
  52     >>> config.update()
  53     >>> config.newoption
  54     False
  55
  56 in
  57
  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()`
  61
  62
  63 Validation upon a whole configuration object
  64 ----------------------------------------------
  65
  66 An option's integrity can be validated towards a whole configuration.
  67
  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.
  71
  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.
  76
  77 Other hook are availables to validate upon a whole configuration at any
  78 time.
  79
  80 .. FIXME : get the validates hooks from the original config pypy's code
  81
  82 Identical option names
  83 ----------------------
  84
  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.
  88
  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
  92 allowed.
  93
  94 .. the calculation was carried out by the requires, wich is not a goog idead
  95
  96     Type constraints with the `multi` type
  97     ----------------------------------------
  98
  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).
 102
 103     See :api:`test_option_consistency.test_multi_constraints()`
 104