trac.config

class trac.config.Configuration(filename, params={})

Bases: object

Thin layer over ConfigParser from the Python standard library.

In addition to providing some convenience methods, the class remembers the last modification time of the configuration file, and reparses it when the file has changed.

defaults(compmgr=None)

Returns a dictionary of the default configuration values.

If compmgr is specified, return only options declared in components that are enabled in the given ComponentManager.

exists

Return boolean indicating configuration file existence.

Since:1.0.11
get(section, key, default='')

Return the value of the specified option.

Valid default input is a string. Returns a string.

getbool(section, key, default='')

Return the specified option as boolean value.

If the value of the option is one of “yes”, “true”, “enabled”, “on”, or “1”, this method wll return True, otherwise False.

Valid default input is a string or a bool. Returns a bool.

getfloat(section, key, default='')

Return the value of the specified option as float.

If the specified option can not be converted to a float, a ConfigurationError exception is raised.

Valid default input is a string, float or int. Returns a float.

getint(section, key, default='')

Return the value of the specified option as integer.

If the specified option can not be converted to an integer, a ConfigurationError exception is raised.

Valid default input is a string or an int. Returns an int.

getlist(section, key, default='', sep=', ', keep_empty=False)

Return a list of values that have been specified as a single comma-separated option.

A different separator can be specified using the sep parameter. The sep parameter can specify multiple values using a list or a tuple. If the keep_empty parameter is set to True, empty elements are included in the list.

Valid default input is a string or a list. Returns a string.

getpath(section, key, default='')

Return a configuration value as an absolute path.

Relative paths are resolved relative to the location of this configuration file.

Valid default input is a string. Returns a normalized path.

has_option(section, option, defaults=True)

Returns True if option exists in section in either the project trac.ini or one of the parents, or is available through the Option registry.

options(section, compmgr=None)

Return a list of (name, value) tuples for every option in the specified section.

This includes options that have default values that haven’t been overridden. If compmgr is specified, only return default option values for components that are enabled in the given ComponentManager.

remove(section, key)

Remove the specified option.

save()

Write the configuration options to the primary file.

sections(compmgr=None, defaults=True, empty=False)

Return a list of section names.

If compmgr is specified, only the section names corresponding to options declared in components that are enabled in the given ComponentManager are returned.

Parameters:empty – If True, include sections from the registry that contain no options.
set(section, key, value)

Change a configuration value.

These changes are not persistent unless saved with save().

set_defaults(compmgr=None, component=None)

Retrieve all default values and store them explicitly in the configuration, so that they can be saved to file.

Values already set in the configuration are not overwritten.

class trac.config.ConfigSection(name, doc, doc_domain='tracini', doc_args=None)

Bases: object

Descriptor for configuration sections.

Create the configuration section.

doc

Return localized document of the section

static get_registry(compmgr=None)

Return the section registry, as a dict mapping section names to ConfigSection objects.

If compmgr is specified, only return sections for components that are enabled in the given ComponentManager.

class trac.config.Option(section, name, default=None, doc='', doc_domain='tracini', doc_args=None)

Bases: object

Descriptor for configuration options.

Create the configuration option.

Parameters:
  • section – the name of the configuration section this option belongs to
  • name – the name of the option
  • default – the default value for the option
  • doc – documentation of the option
doc

Return localized document of the option

dumps(value)

Return the value as a string to write to a trac.ini file

static get_registry(compmgr=None)

Return the option registry, as a dict mapping (section, key) tuples to Option objects.

If compmgr is specified, only return options for components that are enabled in the given ComponentManager.

normalize(value)

Normalize the given value to write to a trac.ini file

class trac.config.BoolOption(section, name, default=None, doc='', doc_domain='tracini', doc_args=None)

Bases: trac.config.Option

Descriptor for boolean configuration options.

Create the configuration option.

Parameters:
  • section – the name of the configuration section this option belongs to
  • name – the name of the option
  • default – the default value for the option
  • doc – documentation of the option
class trac.config.IntOption(section, name, default=None, doc='', doc_domain='tracini', doc_args=None)

Bases: trac.config.Option

Descriptor for integer configuration options.

Create the configuration option.

Parameters:
  • section – the name of the configuration section this option belongs to
  • name – the name of the option
  • default – the default value for the option
  • doc – documentation of the option
class trac.config.FloatOption(section, name, default=None, doc='', doc_domain='tracini', doc_args=None)

Bases: trac.config.Option

Descriptor for float configuration options.

Create the configuration option.

Parameters:
  • section – the name of the configuration section this option belongs to
  • name – the name of the option
  • default – the default value for the option
  • doc – documentation of the option
class trac.config.ListOption(section, name, default=None, sep=', ', keep_empty=False, doc='', doc_domain='tracini', doc_args=None)

Bases: trac.config.Option

Descriptor for configuration options that contain multiple values separated by a specific character.

class trac.config.ChoiceOption(section, name, choices, doc='', doc_domain='tracini', doc_args=None, case_sensitive=True)

Bases: trac.config.Option

Descriptor for configuration options providing a choice among a list of items.

The default value is the first choice in the list.

class trac.config.PathOption(section, name, default=None, doc='', doc_domain='tracini', doc_args=None)

Bases: trac.config.Option

Descriptor for file system path configuration options.

Relative paths are resolved to absolute paths using the directory containing the configuration file as the reference.

Create the configuration option.

Parameters:
  • section – the name of the configuration section this option belongs to
  • name – the name of the option
  • default – the default value for the option
  • doc – documentation of the option
class trac.config.ExtensionOption(section, name, interface, default=None, doc='', doc_domain='tracini', doc_args=None)

Bases: trac.config.Option

Name of a component implementing interface. Raises a ConfigurationError if the component cannot be found in the list of active components implementing the interface.

class trac.config.OrderedExtensionsOption(section, name, interface, default=None, include_missing=True, doc='', doc_domain='tracini', doc_args=None)

Bases: trac.config.ListOption

A comma separated, ordered, list of components implementing interface. Can be empty.

If include_missing is true (the default) all components implementing the interface are returned, with those specified by the option ordered first.

exception trac.config.ConfigurationError(message=None, title=None, show_traceback=False)

Bases: trac.core.TracError

Exception raised when a value in the configuration file is not valid.

class trac.config.UnicodeConfigParser(ignorecase_option=True, **kwargs)

Bases: ConfigParser.ConfigParser

A Unicode-aware version of ConfigParser. Arguments are encoded to UTF-8 and return values are decoded from UTF-8.

class trac.config.Section(config, name)

Bases: object

Proxy for a specific configuration section.

Objects of this class should not be instantiated directly.

get(key, default='')

Return the value of the specified option.

Valid default input is a string. Returns a string.

getbool(key, default='')

Return the value of the specified option as boolean.

This method returns True if the option value is one of “yes”, “true”, “enabled”, “on”, or non-zero numbers, ignoring case. Otherwise False is returned.

Valid default input is a string or a bool. Returns a bool.

getfloat(key, default='')

Return the value of the specified option as float.

If the specified option can not be converted to a float, a ConfigurationError exception is raised.

Valid default input is a string, float or int. Returns a float.

getint(key, default='')

Return the value of the specified option as integer.

If the specified option can not be converted to an integer, a ConfigurationError exception is raised.

Valid default input is a string or an int. Returns an int.

getlist(key, default='', sep=', ', keep_empty=True)

Return a list of values that have been specified as a single comma-separated option.

A different separator can be specified using the sep parameter. The sep parameter can specify multiple values using a list or a tuple. If the keep_empty parameter is set to True, empty elements are included in the list.

Valid default input is a string or a list. Returns a list.

getpath(key, default='')

Return the value of the specified option as a path, relative to the location of this configuration file.

Valid default input is a string. Returns a normalized path.

iterate(compmgr=None, defaults=True)

Iterate over the options in this section.

If compmgr is specified, only return default option values for components that are enabled in the given ComponentManager.

options(compmgr=None)

Return (key, value) tuples for every option in the section.

This includes options that have default values that haven’t been overridden. If compmgr is specified, only return default option values for components that are enabled in the given ComponentManager.

remove(key)

Delete a key from this section.

Like for set(), the changes won’t persist until save() gets called.

set(key, value)

Change a configuration value.

These changes are not persistent unless saved with save().

trac.config.get_configinfo(env)

Returns a list of dictionaries containing the name and options of each configuration section. The value of options is a list of dictionaries containing the name, value and modified state of each configuration option. The modified value is True if the value differs from its default.

Since:version 1.1.2

Components

class trac.config.ConfigurationAdmin

Bases: trac.core.Component

trac-admin command provider for trac.ini administration.