doc/config.txt

   1 .. default-role:: literal
   2
   3 ===============================
   4 Configuration handling basics
   5 ===============================
   6
   7 Tiramisu is made of almost three main objects :
   8
   9 - :class:`tiramisu.config.Config` witch is the whole configuration entry point
  10 - :class:`tiramisu.option.Option` stands for the option types
  11 - :class:`tiramisu.option.OptionDescription` is the shema, the option's structure
  12
  13 Accessing the configuration `Option`'s
  14 -----------------------------------------
  15
  16 The `Config` object attribute access notation stands for the value of the
  17 configuration's `Option`. That is, the `Config`'s object attribute is the name
  18 of the `Option`, and the value is the value accessed by the `__getattr__`
  19 attribute access mechanism.
  20
  21 If the attribute of the `Config` called by `__getattr__` has not been set before
  22 (by the classic `__setattr__` mechanism), the default value of the `Option`
  23 object is returned, and if no `Option` has been declared in the
  24 `OptionDescription` (that is the schema of the configuration), an
  25 `AttributeError` is raised.
  26
  27 ::
  28
  29     >>> gcdummy = BoolOption('dummy', 'dummy', default=False)
  30     >>> gcdummy._name
  31     'dummy'
  32     >>> gcdummy.getdefault()
  33     False
  34     >>> descr = OptionDescription('tiramisu', '', [gcdummy])
  35     >>> cfg = Config(descr)
  36     >>> cfg.dummy
  37     False
  38     >>> cfg.dummy = True
  39     >>> cfg.dummy
  40     True
  41     >>> cfg.idontexist
  42     AttributeError: 'OptionDescription' object has no attribute 'idontexist'
  43
  44 The configuration `Option` objects (in this case the `BoolOption`), are
  45 organized into a tree into nested `OptionDescription` objects. Every
  46 option has a name, as does every option group. The parts of the full
  47 name of the option are separated by dots: e.g.
  48 ``config.optgroup.optname``.
  49
  50 Let's make the protocol of accessing a config's attribute explicit
  51 (because explicit is better than implicit):
  52
  53 1. If the option has not been declared, an `AttributeError` is raised,
  54
  55 2. If an option is declared, but neither a value nor a default value has
  56    been set, the returned value is `None`,
  57
  58 3. If an option is declared and a default value has been set, but no value
  59    has been set, the returned value is the default value of the option,
  60
  61 4. If an option is declared, and a value has been set, the returned value is
  62    the value of the option.
  63
  64 But there are special exceptions. We will see later on that an option can be a
  65 :term:`mandatory option`. A mandatory option is an option that must have a defined value.
  66 If no value have been set yet, the value is `None`.
  67 When the option is called to retrieve a value, an exception is raised.
  68
  69 What if a value has been set and `None` is to be returned again ? Don't
  70 worry, an option value can be "reseted" with the help of the `option.Option.reset()`
  71 method.
  72
  73 If you know the path:
  74
  75 ::
  76
  77     >>> config.gc.dummy
  78     False
  79
  80 Setting the values of the options
  81 ----------------------------------------
  82
  83 An important part of the setting of the configuration consists of setting the
  84 values of the configuration options. There are different ways of setting values,
  85 the first one is of course the `__setattr__` method
  86
  87 ::
  88
  89     cfg.name = value
  90
  91 And if you wanna come back to a default value, use the builtin `del()` function::
  92
  93     del(cfg.name)
  94
  95 .. module:: tiramisu.config
  96
  97 .. _`tree`:
  98
  99 The handling of options
 100 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 101
 102 The handling of options is split into two parts: the description of
 103 which options are available, what their possible values and defaults are
 104 and how they are organized into a tree. A specific choice of options is
 105 bundled into a configuration object which has a reference to its option
 106 description (and therefore makes sure that the configuration values
 107 adhere to the option description).
 108
 109 Configuration's interesting methods
 110 ------------------------------------------
 111
 112 A `Config` object is informed by an `option.OptionDescription`
 113 instance. The attributes of the ``Config`` objects are the names of the
 114 children of the ``OptionDescription``.
 115
 116 Here are the (useful) methods on ``Config`` (or `SubConfig`).
 117
 118 .. currentmodule:: tiramisu.config
 119
 120 .. class:: Config
 121
 122 .. autoclass:: SubConfig
 123     :members: find, find_first, __iter__, iter_groups, iter_all, make_dict
 124
 125     .. automethod:: __init__
 126
 127     .. rubric:: Summary
 128
 129     .. autosummary::
 130
 131        find
 132        find_first
 133
 134        __iter__
 135        iter_groups
 136        iter_all
 137
 138        make_dict
 139
 140     .. rubric:: Methods
 141
 142
 143 A :class:`~config.CommonConfig` is a abstract base class. A
 144 :class:`~config.SubConfig` is an just in time created objects that wraps an
 145 ::class:`~option.OptionDescription`. A SubConfig differs from a Config in the
 146 ::fact that a config is a root object and has an environnement, a context wich
 147 ::defines the different properties, access rules, vs... There is generally only
 148 ::one Config, and many SubConfigs.