doc/status.txt

   1 .. default-role:: literal
   2
   3 Local statuses and global setting
   4 =====================================
   5
   6 Available configuration statuses
   7 ----------------------------------
   8
   9 .. currentmodule:: tiramisu
  10
  11 The configuration's status lives in an :class:`setting.Setting()` object.
  12 This configuration status corresponds to specific attributes or bunch of
  13 attributes that can be accessed together with some `setting.Setting`
  14 method:
  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     :class:`config.CommonConfig.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 :class:`config.SubConfig.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 .. _`frozenconfig`:
  43
  44 Freezing a configuration
  45 ---------------------------
  46
  47 .. todo:: freeze at configuration level
  48
  49 At the configuration level, `setting.Setting.freeze` freezes
  50 the whole configuration options.
  51
  52 .. _`frozen`:
  53
  54 It is possible to *freeze* a single :class:`option.Option()` object with
  55 :meth:`config.SubConfig.cfgimpl_get_settings()`. If you try to modify a frozen
  56 :option, it raises a `TypeError: trying to change a frozen option object`.
  57
  58 To find out if an option `myoption` is frozen, just make an assertion on the
  59 settings like that::
  60
  61     'frozen' in cfg.cfgimpl_get_settings()[myoption]
  62
  63 Moreover, frozen option can return their default values if
  64 `option.Option.force_default()` is called on this option.
  65
  66 Restricted access to an `Option()`
  67 -----------------------------------
  68
  69 .. currentmodule:: tiramisu.setting
  70
  71 .. autoclass:: Property
  72
  73 The `properties` attribute is in charge of the access rules' option's value.
  74
  75 Configuration options access statuses are defined at configuration level
  76 that corresponds to the `option.Option()`'s `properties` attribute,
  77 for example: hidden, disabled.
  78
  79 Use the pythonic way to know if a property is there::
  80
  81     'hidden' in c.cfgimpl_get_settings()
  82     'frozen' in c.cfgimpl_get_settings()[opt]
  83
  84 To access to the global settings::
  85
  86     cfg.cfgimpl_get_settings()
  87     cfg.cfgimpl_get_settings()[option1]
  88
  89 to add, or suppress a global property::
  90
  91     cfg.cfgimpl_get_settings()[option1].append('hidden')
  92     cfg.cfgimpl_get_settings()[option1].remove('hidden')
  93
  94 to activate, deactivate properties::
  95
  96     cfg.cfgimpl_get_settings().append('hidden')
  97     cfg.cfgimpl_get_settings().remove('hidden')
  98
  99 Value owners
 100 -------------
 101
 102
 103 Every configuration option has a **owner**. When the option is instanciated,
 104 the owner is :obj:`setting.owners.default` because a default value has been set
 105 (including `None`, wich means that no value has been set yet).
 106
 107 .. method:: config.CommonConfig.getowner()
 108
 109    This method can retrieve an Option's owner.
 110
 111 - At the instance of the `Config` object, the value owner is
 112   :obj:`setting.owners.default` because
 113   the default values are set at the instance of the configuration option
 114   object,
 115
 116 - at the modification of an option, the owner is `owners.default`, (which is
 117   :obj:`owners.user`)
 118
 119 Special behaviors for an option
 120 ---------------------------------
 121
 122 **mandatory**
 123
 124     A mandatory option shall return a value. If a value, or a default value
 125     has not been set, a error is raised.
 126
 127 **has a callback**
 128
 129     This means that it is a calculated value and therefore automatically
 130     protected it cannot be modified by attribute access.
 131
 132 **force_store_value**
 133
 134     if the configuration option has a default value, the default is
 135     returned, otherwise the value is calculated.
 136
 137     Its inner state is represented by `option.Option.force_default()`
 138
 139 Configuration options have default values that are stored in the
 140 `Option()` object itself. Default values, the `default`, can be set in
 141 various ways.
 142
 143 If a default value is modified by overriding it, not only the value of
 144 the option resets to the default that is proposed, but the owner is
 145 modified too, it is reseted to `owners.default`.