doc/config.txt

   1 .. default-role:: literal
   2
   3 =======================
   4 Configuration Handling
   5 =======================
   6
   7 :module: :api:`config.py`
   8 :tests:  - :api:`test_config.py`
   9          - :api:`test_option_setting.py`
  10
  11 Main Assumption
  12 ===============
  13
  14 Configuration option objects :api:`config.Config()` are produced at the
  15 entry points and handed down to where they are actually used. This keeps
  16 configuration local but available everywhere and consistent.
  17
  18 `Config` and `Option` objects
  19 ==============================
  20
  21 Configuration option objects can be created in different ways. Let's perform
  22 very basic `Config` object manipulations:
  23
  24 ::
  25
  26     >>> from tiramisu.config import Config
  27     >>> from tiramisu.option import OptionDescription, BoolOption
  28     >>> descr = OptionDescription("optgroup", "", [
  29     ...     BoolOption("bool", "", default=False)])
  30     >>>
  31     >>> config = Config(descr)
  32     >>> config.bool
  33     False
  34     >>> config.bool = True
  35     >>> config.bool
  36     True
  37
  38 Take a look at :api:`test_config.test_base_config()` or
  39 :api:`test_config.test_base_config_and_groups()`.
  40
  41
  42 Accessing the configuration `Option`'s
  43 -----------------------------------------
  44
  45 The `Config` object attribute access notation stands for the value of the
  46 configuration's `Option`. That is, the `Config`'s object attribute is the name
  47 of the `Option`, and the value is the value accessed by the `__getattr__`
  48 attribute access mechanism.
  49
  50 If the attribute of the `Config` called by `__getattr__` has not been set before
  51 (by the classic `__setattr__` mechanism), the default value of the `Option`
  52 object is returned, and if no `Option` has been declared in the
  53 `OptionDescription` (that is the schema of the configuration), an
  54 `AttributeError` is raised.
  55
  56 ::
  57
  58     >>> gcdummy = BoolOption('dummy', 'dummy', default=False)
  59     >>> gcdummy._name
  60     'dummy'
  61     >>> gcdummy.getdefault()
  62     False
  63     >>> descr = OptionDescription('tiramisu', '', [gcdummy])
  64     >>> cfg = Config(descr)
  65     >>> cfg.dummy
  66     False
  67     >>> cfg.dummy = True
  68     >>> cfg.dummy
  69     True
  70     >>> cfg.idontexist
  71     AttributeError: 'OptionDescription' object has no attribute 'idontexist'
  72
  73 The configuration `Option` objects (in this case the `BoolOption`), are
  74 organized into a tree into nested `OptionDescription` objects. Every
  75 option has a name, as does every option group. The parts of the full
  76 name of the option are separated by dots: e.g.
  77 ``config.optgroup.optname``.
  78
  79 **Can you repeat it, what is the protocol of accessing a config's attribute ?**
  80
  81 1. If the option has not been declared, an `AttributeError` is raised,
  82
  83 2. If an option is declared, but neither a value nor a default value has
  84    been set, the returned value is `None`,
  85
  86 3. If an option is declared and a default value has been set, but no value
  87    has been set, the returned value is the default value of the option,
  88
  89 4. If an option is declared, and a value has been set, the returned value is
  90    the value of the option.
  91
  92 If you do not want to use the pythonic way, that is the attribute access
  93 way to obtain the value of the configuration option, you can also search
  94 for it recursively in the whole config namespaces with the ``get()``
  95 method :
  96
  97 ::
  98
  99     >>> config.get('bool')
 100     True
 101
 102
 103 To find the right option, `get()` searches recursively into the whole
 104 tree. For example, to find an option which is in the `gc` namespace
 105 there are two possibilites.
 106
 107 If you know the path:
 108
 109 ::
 110
 111     >>> config.gc.dummy
 112     False
 113
 114 If you don't remember the path:
 115
 116 ::
 117
 118     >>> config.get('dummy')
 119     False
 120
 121 Setting the values of the options
 122 ----------------------------------------
 123
 124 An important part of the setting of the configuration consists of setting the
 125 values of the configuration options. There are different ways of setting values,
 126 the first one is of course the `__setattr__` method
 127
 128 ::
 129
 130     cfg.name = value
 131
 132 wich has the same effect that the "global" `set()` method : it expects that
 133 the value owner is the default :ref:`glossary#valueowner`
 134
 135 ::
 136
 137      cfg.set(name=value)
 138
 139 The global `setoption()` method of the config objects can set a value with a specific owner
 140
 141 ::
 142
 143     cfg.setoption('name', value, 'owner')
 144
 145
 146 Finally, the local `setoption()` method directly in the `Option` object can be
 147 used. While the `Option` object refers to his parent, the config knows that the
 148 value has been changed and no bad side effect won't occur
 149
 150 ::
 151
 152     >>> booloption = BoolOption('bool', 'Test boolean option', default=True)
 153     >>> descr = OptionDescription('descr', '', [booloption])
 154     >>> cfg = Config(descr)
 155     >>> booloption.setoption(cfg, False, 'owner')
 156     >>> cfg.bool
 157     >>> False
 158