Edgewall Software

Changes between Version 8 and Version 9 of TracDev/ConfigApi


Ignore:
Timestamp:
Feb 3, 2015, 7:31:29 PM (5 years ago)
Author:
figaro
Comment:

Cosmetic changes

Legend:

Unmodified
Added
Removed
Modified
  • TracDev/ConfigApi

    v8 v9  
    1 = Configuration (trac.ini) API =
    2 Most of Trac's configuration is stored in the [TracIni trac.ini] file. Trac provides an API to retrieve and set the settings in this configuration file.
     1= Configuration (trac.ini) API
    32
    4 For the sake of this article, here's a quick reminder of the structure of `trac.ini`:
     3Most of Trac's configuration is stored in the [TracIni trac.ini] file. Trac provides an API to retrieve and set the settings in this configuration file. The `trac.ini` file has the following structure:
    54
    65{{{
     
    1110}}}
    1211
    13 The file consists of multiple ''sections'' (written as `[sectionname]`). Each section consists of multiple ''options'' with their ''option values'' (like `ignore_missing_pages = false` in the example above). All options that come after the beginning of a section belong to this section - until a new section begins.
     12The file consists of multiple ''sections'', written as `[sectionname]`. Each section consists of multiple ''options'' with their ''option values'', like `ignore_missing_pages = false` in the example above. All options that come after the beginning of a section belong to this section - until a new section begins.
    1413
    1514'''Note:''' The following examples will use `env.config` to access the configuration API. From within a [TracDev/ComponentArchitecture component] method you can use `self.config` to access the configuration API as well.
    1615
    17 == Retrieving arbitrary option values ==
     16== Retrieving arbitrary option values
     17
    1818The easiest way to retrieve the value of a certain option is to use:
    1919
     
    2323}}}
    2424
    25 The method `get()` will return the option value as string (type `unicode`). Of course, there are also methods to retrieve the option value in several other data formats:
     25The method `get()` will return the option value as string, type `unicode`. Of course, there are also methods to retrieve the option value in other data formats:
    2626
    2727{{{
     
    3737''Note:'' Most options have some meta data (data type, description) associated with them. For getting those meta data, see [#listing_options Listing Options] below.
    3838
    39 == Setting arbitrary option values ==
    40 Setting an option value is almost as easy as retrieving one. For this purpose, you need to use the method `set()`:
     39== Setting arbitrary option values
     40
     41Setting an option value is almost as easy as retrieving one. Use the method `set()`:
    4142
    4243{{{
     
    6364
    6465== Defining options == #defining_options
     66
    6567While you can use `config.set()` to store values for arbitrary options, there's also a way to tell Trac which options are available. To do this, create a component and specify the option like this:
    6668
     
    9294}}}
    9395
    94 Secondly, you can define a default value for the option. If no value has been defined in `trac.ini` for this specific option, the default value will used as value (no matter which of the two previously mentioned method is used).
     96Secondly, you can define a default value for the option. If no value has been defined in `trac.ini` for this specific option, the default value will used as value, regardless which of the two previously mentioned method is used.
    9597
    9698Last, this allows plugins like [th:IniAdminPlugin] or [th:TracIniAdminPanelPlugin] to work. These plugins allow the user to edit `trac.ini` via the webadmin interface. For this purpose they need to know which options exist which is done like described in this section.
    9799
    98100== Retrieving the value of previously defined options == #retrieving_defined_options
    99 As describes in the previous section, defining an option (in a component) allows you to retrieve its value more easily. Furthermore, this definition also allows for automatic type conversion. For this you need to use one of the child classes of `Option` (instead of `Option` itself).
     101
     102As describes in the previous section, defining an option (in a component) allows you to retrieve its value more easily. Furthermore, this definition also allows for automatic type conversion. For this you need to use one of the child classes of `Option` instead of `Option` itself.
    100103
    101104For example, let's assume the option `my_option` defined in the next example has the value `1.234`. Now consider calling `my_method` in the following code:
     
    113116}}}
    114117
    115 The option value has automatically been converted to `float`. If you had simply used `Option` (instead of `FloatOption`), the value would have been a string (instead of a `float`).
     118The option value has automatically been converted to `float`. If you had simply used `Option` instead of `FloatOption`, the value would have been a string.
    116119
    117 Beside these "simple" types (`BoolOption`, `IntOption`, `FloatOption`) there are also options with a little bit more "magic":
     120Beside these simple types (`BoolOption`, `IntOption`, `FloatOption`), there are also options with a little bit more complexity:
    118121
    119122 * `PathOption` simply describes a path that can be absolute or relative. The option always returns an absolute path. Relative paths are resolved relative to the `conf` directory of the environment.
     
    135138}}}
    136139
    137 ''Note:'' Currently (as with Trac ''0.12.1'') you can't ''set'' an option's value this way (e.g. with `self.my_option = new_option_value`). This will raise an !AttributeError, but there's ticket #9967 that aims to fix this problem.
     140''Note:'' Currently (as with Trac ''0.12.1'') you can't ''set'' an option's value this way, eg with `self.my_option = new_option_value`. This will raise an !AttributeError, but ticket #9967 aims to fix this.
    138141
    139 === Why does this work? ===
     142=== Why does this work?
     143
    140144So, how can one define an option as `ListOption` but end up with a list? This works because there are two ways to access the option: as class variable or as instance variable.
    141145
     
    155159}}}
    156160
    157 The first way uses the ''instance'' attribute which is the actual list, while the second way uses the ''class'' attribute which is the actual `ListOption` object.
     161The first way uses the ''instance'' attribute, which is the actual list, while the second way uses the ''class'' attribute which is the actual `ListOption` object.
    158162
    159163When you try to access another component's defined options the difference between these two ways is less obvious, so be careful:
     
    170174}}}
    171175
    172 For a more deeper understanding of how this implementation works, see the official [http://docs.python.org/howto/descriptor.html Descriptor HowTo Guide] - since the `Option` class is a data descriptor. 
     176For a deeper understanding of how this implementation works, see the official [http://docs.python.org/howto/descriptor.html Descriptor HowTo Guide], since the `Option` class is a data descriptor. 
    173177
    174178== Listing known options == #listing_options
    175 Beside retrieving the value of a certain option, there are also methods for listing all known options.
     179
     180Beside retrieving the value of a certain option, there are also methods for listing all known options:
    176181
    177182 * `config.sections()`: Returns a list of the names of all known sections.
     
    179184 * `config.defaults()`: Returns a dict with the default values of all known options (that have one) in all known sections.
    180185
    181 A "known option" in this context is an option that
     186A "known option" in this context is an option that:
    182187
    183188 * is defined like described in the section [#defining_options Defining Options] above
    184189 * and/or has value assigned to it.
    185190
    186 Furthermore, there is a way to list all ''defined'' options. This is done by using `Option.registry` which is a dict with `(section_name, option_name)` keys. The value for each key is the `Option` object that defines the option (not its current value). The following example will list the descriptions of all defined options:
     191Furthermore, there is a way to list all ''defined'' options. This is done by using `Option.registry` which is a dict with `(section_name, option_name)` keys. The value for each key is the `Option` object that defines the option, not its current value. The following example lists the descriptions of all defined options:
    187192
    188193{{{