Context Navigation

Changes between Version 8 and Version 9 of TracDev/ConfigApi

Timestamp:: Feb 3, 2015, 7:31:29 PM (9 years ago)
Author:: figaro
Comment:: Cosmetic changes

Legend:

: Unmodified
: Added
: Removed
: Modified

TracDev/ConfigApi

-              v8
+              v9
+= Configuration (trac.ini) API =
+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.
+= Configuration (trac.ini) API
 For the sake of this article, here's a quick reminder of the structure of `trac.ini`:
+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. The `trac.ini` file has the following structure:
 {{{
 …
 }}}
 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.
+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.
 '''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.
+== Retrieving arbitrary option values ==
+== Retrieving arbitrary option values
 The easiest way to retrieve the value of a certain option is to use:
 …
 }}}
 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:
+The 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:
 {{{
 …
 ''Note:'' Most options have some meta data (data type, description) associated with them. For getting those meta data, see [#listing_options Listing Options] below.
+== Setting arbitrary option values ==
+Setting an option value is almost as easy as retrieving one. For this purpose, you need to use the method `set()`:
+== Setting arbitrary option values
+Setting an option value is almost as easy as retrieving one. Use the method `set()`:
 {{{
 …
 == Defining options == #defining_options
 While 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:
 …
 }}}
 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).
+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, regardless which of the two previously mentioned method is used.
 Last, 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.
 == Retrieving the value of previously defined options == #retrieving_defined_options
+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).
+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.
 For 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:
 …
 }}}
 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`).
+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.
 Beside these "simple" types (`BoolOption`, `IntOption`, `FloatOption`) there are also options with a little bit more "magic":
+Beside these simple types (`BoolOption`, `IntOption`, `FloatOption`), there are also options with a little bit more complexity:
  * `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.
 …
 }}}
 ''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.
+''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.
+=== Why does this work? ===
+=== Why does this work?
 So, 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.
 …
 }}}
 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.
+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.
 When you try to access another component's defined options the difference between these two ways is less obvious, so be careful:
 …
 }}}
 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.
+For 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.
 == Listing known options == #listing_options
+Beside retrieving the value of a certain option, there are also methods for listing all known options.
+Beside retrieving the value of a certain option, there are also methods for listing all known options:
  * `config.sections()`: Returns a list of the names of all known sections.
 …
  * `config.defaults()`: Returns a dict with the default values of all known options (that have one) in all known sections.
 A "known option" in this context is an option that
+A "known option" in this context is an option that:
  * is defined like described in the section [#defining_options Defining Options] above
  * and/or has value assigned to it.
 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:
+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 lists the descriptions of all defined options:
 {{{