doc/status.txt

   1 .. default-role:: literal
   2
   3 Configuration status
   4 ======================
   5
   6 :module: :api:`config.py`
   7 :tests: - :api:`test_option_owner.py`
   8         - :api:`test_option_type.py`
   9         - :api:`test_option_default.py`
  10
  11 Available configuration statuses
  12 ----------------------------------
  13
  14 These configuration statuses corresponds to specific global attributes :
  15
  16 **read write status**
  17
  18     The configuration can be accessed by `__get__` and `__set__`
  19     properties, except for the `hidden` configuration options but, yes, it is
  20     possible to modify a disabled option.
  21
  22     To enable read-write status, call
  23     :api:`config.Config.cfgimpl_read_write()`
  24
  25 **read only status**
  26
  27     The whole configuration is `frozen`, that is modifiying a value is
  28     forbidden. We can access to a configuration option only with the
  29     `__getattr__` property.
  30
  31     The configuration has not an access to the hidden options
  32     but can read the disabled options.
  33
  34     To enable read only status, call :api:`config.Config.cfgimpl_read_only()`
  35
  36 .. csv-table:: **Configuration's statuses summary**
  37    :header: " ", "Hidden", "Disabled", "Mandatory"
  38
  39     "read only status", `False`, `True`, `True`
  40     "read-write status", `True`, `False`, `False`
  41
  42 Freezing a configuration
  43 ---------------------------
  44
  45 It is possible to *freeze* a single `Option` object with
  46 :api:`option.Option.freeze()`. If you try to modify a frozen option, it
  47 raises a `TypeError: trying to change a frozen option object`.
  48
  49 At the configuration level, :api:`config.Config.cfgimpl_freeze()` freeze
  50 the whole configuration options.
  51
  52 - :api:`test_option_type.test_freeze_one_option()`
  53 - :api:`test_option_type.test_frozen_value()`
  54 - :api:`test_option_type.test_freeze()`
  55
  56
  57 Restricted access to an `Option()`
  58 -----------------------------------
  59
  60 Configuration options access statuses are defined at configuration level
  61 that corresponds to theses :api:`option.Option()`'s attribute:
  62
  63 **hidden**
  64
  65     This means that an option raises an `HiddenOptionError` if we try to access
  66     the value of the option.
  67
  68     See `hide()` or `show()` in `Option()` that comes from
  69     :api:`option.HiddenBaseType`
  70
  71 corresponding convenience API provided:
  72
  73     `hide()`:
  74         set the `hidden` attribute to `True`
  75
  76     `show()`:
  77         set the `hidden` attribute to `False`
  78
  79 **disabled**
  80
  81     This means that an option *doesn't exists* (doesn't say anything
  82     much more thant an `AttibuteAccess` error)
  83
  84     See in :api:`option.DisabledBaseType` the origins of
  85     `Option.enable()` or `Option.disable()`
  86
  87 corresponding convenience API provided:
  88
  89     `disable()`:
  90         set the `disabled` attribute to `True`
  91
  92     `enable()`:
  93         set the `disabled` attribute to `False`
  94
  95 mode
  96
  97     a mode is `normal` or `expert`, just a category of `Option()` or
  98     group wich determines if an option is easy to choose or not,
  99     available methods are:
 100
 101     `get_mode()`:
 102         returns the current mode
 103
 104     `set_mode(mode)`:
 105         sets a new mode
 106
 107     see it in :api:`option.ModeBaseType`
 108
 109 Value owners
 110 -------------
 111
 112 Every configuration option has a **owner**. When the option is
 113 instanciated, the owner is `default` because a default value has been
 114 set (including `None`, take a look at the tests).
 115
 116 The `value_owner` is the man who did it. Yes, the man who changed the value of the
 117 configuration option.
 118
 119 - At the instance of the `Config` object, the value owner is `default` because
 120   the default values are set at the instance of the configuration option object,
 121
 122 ::
 123
 124     # let's expect there is an option named 'name'
 125     config = Config(descr, bool=False)
 126     # the override method has been called
 127     config._cfgimpl_value_owners['name'] == 'default'
 128
 129 - at the modification of an option, the owner is `default_owner`, (which is `user`)
 130
 131 ::
 132
 133     # modification of the value by attribute access
 134     config.gc.dummy = True
 135     assert config.gc._cfgimpl_value_owners['dummy'] == 'user'
 136     assert config._cfgimpl_values['gc']._cfgimpl_value_owners['dummy'] == 'user'
 137
 138 - the default owner can be set with the `set_owner()` method
 139
 140 ::
 141
 142     config.set_owner('spam')
 143     config.set(dummy=True)
 144     assert config.gc._cfgimpl_value_owners['dummy'] == 'spam'
 145     assert config._cfgimpl_values['gc']._cfgimpl_value_owners['dummy'] == 'spam'
 146
 147 Special owners
 148 ---------------
 149
 150 If the owner of a configuration option is `auto` or `fill` the behavior of the
 151 access of the value changes. In fact, there is nothing in the value.
 152 The value comes from somewhere else (typically, it is calculated by the
 153 operation system).
 154
 155 **auto**
 156
 157     This means that it is a calculated value and therefore automatically
 158     protected it cannot be modified by attribute access once the owner
 159     is `auto`.
 160
 161     The configuration option is hidden and a fonction in a specific
 162     library is called for the computation of the value.
 163
 164 **fill**
 165
 166     if the configuration option has a default value, the default is
 167     returned, otherwise the value is calculated
 168
 169 The default values behavior
 170 ----------------------------
 171
 172 Configuration options have default values that are stored in the
 173 `Option()` object itself. Default values, the `default`, can be set in
 174 various ways.
 175
 176 .. FIXME : ADD DETAILS HERE
 177
 178 If a default value is modified by overriding it, not only the value of
 179 the option resets to the default that is proposed, but the owner is
 180 modified too, it is reseted to `default`.
 181