API

Config

The primary API classes.

class profig.Config(*sources, **kwargs)

The root configuration object.

Any number of sources can be set using sources. These are the sources that will be using when calling sync().

The format of the sources can be set using format. This can be the registered name of a format, such as “ini”, or a Format class or instance.

An encoding can be set using encoding. If encoding is not specified the encoding used is platform dependent: locale.getpreferredencoding(False).

Strict mode can be enabled by setting strict to True. In strict mode, accessing keys that have not been initialized will raise an InvalidSectionError.

The dict class used internally can be set using dict_type. By default an OrderedDict is used.

A Coercer can be set using coercer. If no coercer is passed in, a default will be created. If None is passed in, no coercer will be set and values will be read from and written to sources directly.

This is a subclass of ConfigSection.

classmethod known_formats()

Returns the formats registered with this class.

set_format(format)

Sets the format to use when processing sources.

format can be the registered name of a format, such as “ini”, or a Format class or instance.

format

The Format to use to process sources.

class profig.ConfigSection(name, parent)

Represents a group of configuration options.

This class is not meant to be instantiated directly.

adapt(encode=True)

value -> str

as_dict(flat=False, dict_type=None)

Returns the configuration’s keys and values as a dictionary.

If flat is True, returns a single-depth dict with . delimited keys.

If dict_type is not None, it should be the mapping class to use for the result. Otherwise, the dict_type set by __init__() will be used.

convert(string, decode=True)

str -> value

default()

Get the section’s default value.

get(key, default=None)

If key exists, returns the value. Otherwise, returns default.

If default is not given, it defaults to None, so that this method never raises an exception.

init(key, default, type=None, comment=None)

Initializes key to the given default value.

If type is not provided, the type of the default value will be used.

If a value is already set for the section at key, it will be coerced to type.

If a comment is provided, it may be written out to the config file in a manner consistent with the active Format.

read(*sources, **kwargs)

Reads config values.

If sources are provided, read only from those sources. Otherwise, write to the sources in sources. A format for sources can be set using format.

reset(recurse=True, clean=True)

Resets this section to it’s default value, leaving it in the same state as after a call to ConfigSection.init().

If recurse is True, does the same to all the section’s children. If clean is True, also clears the dirty flag on all sections.

section(key, create=None)

Returns a section object for key.

create will default to False when in strict mode. Otherwise it defaults to True.

If there is no existing section for key, and create is False, an InvalidSectionError is thrown.

sections(recurse=False, only_valid=False)

Returns the sections that are children to this section.

If recurse is True, returns grandchildren as well. If only_valid is True, returns only valid sections.

set_default(value)

Set the section’s default value.

set_value(value)

Set the section’s value.

sync(*sources, **kwargs)

Reads from sources and writes any changes back to the first source.

If sources are provided, syncs only those sources. Otherwise, syncs the sources in sources.

format can be used to override the format used to read/write from the sources.

value()

Get the section’s value.

write(source=None, format=None)

Writes config values.

If source is provided, write only to that source. Otherwise, write to the first source in sources. A format for source can be set using format. format is otherwise ignored.

dirty

True if this section’s value has changed since the last write. Read-only.

has_children

True if this section has child sections. Read-only.

is_default

True if this section has a default value and its current value is equal to the default value. Read-only.

key

The section’s key. Read-only.

name

The section’s name. Read-only.

parent

The section’s parent or None. Read-only.

root

Returns the root ConfigSection object. Read-only.

type

The type used for coercing the value for this section. Read only.

valid

True if this section has a valid value. Read-only.

Formats

Formats define de/serialization specifics.

class profig.Format

close(file)

flush(file)

open(cfg, source, mode='r', binary=True)

Returns a file object.

If source is a file object, returns source. mode can be ‘r’ or ‘w’. If mode is ‘w’, The file object will be truncated. If binary is True, the file will be opened in binary mode (‘rb’ or ‘wb’).

read(cfg, file)

Reads file to update cfg. Must be implemented in a subclass.

write(cfg, file, values=None)

Writes cfg to file. Must be implemented in a subclass.

error_mode

Specifies how the format should react to errors raised when processing a source.

Must be one of the following:

• ignore - Ignore all errors completely.
• warning - Log a warning for any errors.
• exception - Raise an exception for any error.

Only ‘exception’ will cause the format to stop processing a source.

error_modes = frozenset({'warning', 'exception', 'ignore'})

The supported error modes.

name = None

A convenient name for the format.

class profig.INIFormat

Implements reading/writing configurations from/to INI formatted files.

A header will be written for each section in the root config object.

class profig.RegistryFormat

Implements reading/writing configurations from/to the Windows registry.

Sections with children will be created as keys. Those without children will be created as values.

Keys will be created relative to RegistryFormat.base_key, which defaults to HKEY_CURRENT_USER.

Coercer

A Coercer handles the conversion of values to/from a human-readable string representation.

class profig.Coercer(register_defaults=True, register_qt=None)

The coercer class, with which adapters and converters can be registered.

adapt(value, type=None)

Adapt a value from the given type (type to string). If type is not provided the type of the value will be used.

convert(value, type)

Convert a value to the given type (string to type).

register(type, adapter, converter)

Register an adapter and converter for the given type.

register_adapter(type, adapter)

Register an adapter (type to string) for the given type.

register_choice(type, choices)

Registers an adapter and converter for a choice of values. Values passed into adapt() or convert() for type will have to be one of the choices. choices must be a dict that maps converted->adapted representations.

register_converter(type, converter)

Register a converter (string to type) for the given type.