Application configuration

Main configuration - principles

The main configuration conf/config.xml is processed and provided by the settings module.

In general, the configuration file has a two-level structure: sections and key-value items. An item can be either a string or a list of items.

The structure can be understood from the following example:

<kontext>
  <global> <!-- a section -->
    <key1>value1</key>
  </global>
  <some_other_section>
    <key2>value2</key>
    <key3>
      <!-- array value -->
      <item>value3a</item>
      <item>value3b</item>
    </key3>
  </some_other_section>
</kontext>

The settings module offers a bunch of methods to access the values.

settings.get('section_name', 'key_name')  # returns either a string or a list

settings.get_int('section_name', 'key_name')  # converts the value to an int; may throw an exception

settings.get_bool('section_name', 'key_name') # converts the value to a bool; may throw an exception

settings.get_list('section_name', 'key_name')  # converts the value into a list 
                                               # (even if the value is single/empty)

settings.get_meta('section_name', 'key_name')  # returns values defined in element's attributes

settings.get_full('section_name', 'key_name')  # returns a 2-tuple (value, metadata)

Please note that if you need to access deeper levels of the configuration (which is a typical situation when configuring plug-ins) you have to use Python's standard methods of accessing dictionaries' contents:

settings.get('foo', 'bar')['baz']

settings.get('foo', 'bar').get('baz')

Customization

Because KonText is highly customizable its configuration must be able to reflect non-core settings too. Even though the customization can be defined anywhere in the config.xml file, it should be kept within the plugins element where custom modules (aka plug-ins) are configured.

KonText distinguishes between core and non-core values via an attribute extension-by.

<kontext>
    <global>
    ...
    </global>
    <corpora>
    ...
    </corpora>
    <plugins>
      <auth>
        <module>my_auth_implementation</module>
        <organization extension-by="foo">department of linguistics</organization>
      </auth>
    </plugins>
</kontext>

The value of the extension-by attribute is then used as a prefix to access custom configuration items:

settings.get('plugins', 'auth')['foo:organization']

Validation

To make sure everything is OK with the configuration you can always validate the conf/config.xml file:

python ./scripts/validate_xml.py ./conf/config.xml ./conf/config.rng