doc/config.txt

   1 .. default-role:: literal
   2
   3 ===============================
   4 Options 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 `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 `Option` objects (in this case the `BoolOption`), are organized into a tree
  45 into nested `OptionDescription` objects. Every option has a name, as does every
  46 option group. The parts of the full name of the option are separated by dots:
  47 e.g. ``cfg.optgroup.optname``.
  48
  49 Let's make the protocol of accessing a config's attribute explicit
  50 (because explicit is better than implicit):
  51
  52 1. If the option has not been declared, an `AttributeError` is raised,
  53
  54 2. If an option is declared, but neither a value nor a default value has
  55    been set, the returned value is `None`,
  56
  57 3. If an option is declared and a default value has been set, but no value
  58    has been set, the returned value is the default value of the option,
  59
  60 4. If an option is declared, and a value has been set, the returned value is
  61    the value of the option.
  62
  63 But there are special exceptions. We will see later on that an option can be a
  64 :term:`mandatory option`. A mandatory option is an option that must have a defined value.
  65 If no value have been set yet, the value is `None`.
  66 When the option is called to retrieve a value, an exception is raised.
  67
  68 What if a value has been set and `None` is to be returned again ? Don't
  69 worry, an option value can be "reseted" with the help of the `option.Option.reset()`
  70 method.
  71
  72 If you know the path:
  73
  74 ::
  75
  76     >>> config.gc.dummy
  77     False
  78
  79 Setting the values of the options
  80 ----------------------------------------
  81
  82 An important part of the setting of the configuration consists of setting the
  83 values of the configuration options. There are different ways of setting values,
  84 the first one is of course the `__setattr__` method
  85
  86 ::
  87
  88     cfg.name = value
  89
  90 And if you wanna come back to a default value, use the builtin `del()` function::
  91
  92     del(cfg.name)
  93
  94 .. module:: tiramisu.config
  95
  96 .. _`tree`:
  97
  98 The handling of options
  99 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 100
 101 The handling of options is split into two parts: the description of
 102 which options are available, what their possible values and defaults are
 103 and how they are organized into a tree. A specific choice of options is
 104 bundled into a configuration object which has a reference to its option
 105 description (and therefore makes sure that the configuration values
 106 adhere to the option description).
 107
 108
 109 Common manipulations
 110 ------------------------
 111
 112 Let's perform some common manipulation on some options:
 113
 114 >>> from tiramisu.config import Config
 115 >>> from tiramisu.option import UnicodeOption, OptionDescription
 116 >>>
 117 >>> var1 = UnicodeOption('var1', 'first variable')
 118 >>> var2 = UnicodeOption('var2', '', u'value')
 119 >>>
 120 >>> od1 = OptionDescription('od1', 'first OD', [var1, var2])
 121 >>> rootod = OptionDescription('rootod', '', [od1])
 122
 123 let's set somme access rules on the main namespace
 124
 125 >>> c = Config(rootod)
 126 >>> c.read_write()
 127
 128 let's travel the namespaces
 129
 130 >>> print c
 131 [od1]
 132 >>> print c.od1
 133 var1 = None
 134 var2 = value
 135 >>> print c.od1.var1
 136 None
 137 >>> print c.od1.var2
 138 value
 139
 140 let's modify a value (careful to the value's type...)
 141
 142 >>> c.od1.var1 = 'value'
 143 Traceback (most recent call last):
 144 [...]
 145 ValueError: invalid value value for option var1
 146 >>> c.od1.var1 = u'value'
 147 >>> print c.od1.var1
 148 value
 149 >>> c.od1.var2 = u'value2'
 150 >>> print c.od1.var2
 151 value2
 152
 153 let's come back to the default value
 154
 155 >>> del(c.od1.var2)
 156 >>> print c.od1.var2
 157 value
 158
 159 The value is saved in a :class:`~tiramisu.value.Value` object.
 160 It is on this object that we have to trigger the `reset`
 161
 162
 163
 164
 165 Configuration's interesting methods
 166 ------------------------------------------
 167
 168 A `Config` object is informed by an `option.OptionDescription`
 169 instance. The attributes of the ``Config`` objects are the names of the
 170 children of the ``OptionDescription``.
 171
 172 Here are the (useful) methods on ``Config`` (or `SubConfig`).
 173
 174 .. currentmodule:: tiramisu.config
 175
 176 .. class:: Config
 177
 178 .. autoclass:: SubConfig
 179     :members: find, find_first, __iter__, iter_groups, iter_all, make_dict
 180
 181     .. automethod:: __init__
 182
 183     .. rubric:: Summary
 184
 185     .. autosummary::
 186
 187        find
 188        find_first
 189
 190        __iter__
 191        iter_groups
 192        iter_all
 193
 194        make_dict
 195
 196     .. rubric:: Methods
 197
 198
 199 A :class:`~config.CommonConfig` is a abstract base class. A
 200 :class:`~config.SubConfig` is an just in time created objects that wraps an
 201 ::class:`~option.OptionDescription`. A SubConfig differs from a Config in the
 202 ::fact that a config is a root object and has an environnement, a context wich
 203 ::defines the different properties, access rules, vs... There is generally only
 204 ::one Config, and many SubConfigs.