API Reference

Changed in version 0.2.0: Interpolation of values in configuration files now works with default values from the specification.

Easy and simple configuration.

See also: Introduction

Overview

NOTFOUND	Special value for options that are not found and have no default.
NOVALUE	Special value for options without a value.
Config	Configuration class.
ConfigError	Raised if there is a problem with the configuration.
DuplicateError	Raised if an option already exists in a section.
Error	Base Exception.
ReadonlyError	Raised on an attempt to set a readonly option.
SpecError	Raised if there is a problem with the specification.
configure	For an explanation see the Introduction.
convert_choice	Return a function that can be used as a converter.
convert_loglevel	Return a converter function for logging levels.
convert_predicate	Return a converter function with a predicate.
convert_string	Return a function that can be used as a converter.

easimpconf.NOTFOUND

Special value for options that are not found and have no default.

The truth value is False.

easimpconf.NOVALUE

Special value for options without a value (see Introduction).

The truth value is True

class easimpconf.Config(options, create_props, kwargs)

Configuration class.

An instance of this class is returned by the function configure().

If create_properties=True it will have a property for each configuration option named as explained in the Introduction. For extra data this is just the name given in the add() method.

Options can also be accessed like this: config[secname, optname]. To check if an option exists, the in operator can be used: (secname, optname) in config.

For extra data either None must be used for the section name or only the name of the data, i.e. config[None, name] and config[name] are equivalent as are (None, name) in config and name in config.

When a Config object is used as an iterator it yields 3-tuples for each option: (secname, optname, value).

add(key, value, readonly=True)

Add extra data to configuration or an option to a section.

Parameters

• key – either a name of extra data or a tuple ('secname', 'optname')

• value – the value of the data

• readonly (bool) – if True the data cannot be changed

Type

str or tuple

Raises

• DuplicateError – if an option already exists in a section

• AttributeError – if an attribute with the same name already exists (only if create_properties=True)

• ConfigError – if create_properties=True and name or secname_optname is not a valid Python identifier; the data can still be accessed with cfg['name'] or cfg['secname', 'optname']

sections()

Return section names.

Returns

list with section names

Return type

list

options(section)

Return option names in the specified section.

Parameters

section (str) – a section name

Returns

list with option names

Return type

list

extras()

Return names of extra data added with add().

Returns

list with names of extra data

Return type

list

as_dict(section)

Return options and values in a section as a dict.

Parameters

section (str) – a section name

Returns

mapping option names => values

Return type

dict

write(file, space_around_delimiters=True)

Write a representation of the configuration to the specified file.

Extra data added with add() will be excluded.

Parameters

• file (path-like object or text file opened for writing) – the file

• space_around_delimiters (bool) – if True, delimiters between keys and values are surrounded by spaces

debug_info()

Return an iterator for debugging.

It yields 5-tuples (sec, opt, name, value, readonly) for each option.

exception easimpconf.ConfigError

Raised if there is a problem with the configuration.

exception easimpconf.DuplicateError

Raised if an option already exists in a section.

exception easimpconf.Error

Base Exception.

exception easimpconf.ReadonlyError

Raised on an attempt to set a readonly option.

exception easimpconf.SpecError

Raised if there is a problem with the specification.

easimpconf.configure(conf, spec, *, create_properties=True, converters=None, **kwargs)

For an explanation see the Introduction.

Parameters

• conf (path-like object or text file opened for reading or ConfigParser object) – the configuration

• spec (path-like object or text file opened for reading or None) – the specification

• create_properties (bool) – if True properties will be created, else only item access with [sec,opt] can be used

• converters (dict) – same as the converters argument of ConfigParser but used directly by this function

• kwargs – arguments for the ConfigParser (ignored if conf is a ConfigParser object)

Returns

configuration object

Return type

Config

Raises

• SpecError – if there is a problem with the specification

• ConfigError – if there is a problem with the configuration

• configparser.Error – from ConfigParser

easimpconf.convert_choice(choices, *, converter=None, default=None)

Return a function that can be used as a converter.

For an example see the source code of convert_loglevel().

Parameters

• choices – any container type that supports the in operator with acceptable values

• converter – a callable that takes one string argument and returns an object of the desired type; None means no conversion

• default – a default value of the desired type or a subclass of Exception which will be raised

Returns

converter function

Return type

function(str)

easimpconf.convert_loglevel(default_level=None, *, numeric=False)

Return a converter function for logging levels.

Valid values are the logging levels as defined in the logging module.

Parameters

• default_level (str) – the default logging level

• numeric (bool) – if True the numeric value of the log level will be returned

Raises

ValueError – if not a valid logging level and default_level=None

Returns

converter function

Return type

function(str)

easimpconf.convert_predicate(predicate, *, converter=None, default=None)

Return a converter function with a predicate.

>>> positive_float = convert_predicate(lambda x: x > 0.0,
... converter=float, default=0.0)
>>> positive_float('1.2')
1.2
>>> positive_float('-1.2')
0.0

Parameters

• predicate – a callable that takes one argument of the desired type and returns True if it is acceptable

• converter – a callable that takes one string argument and returns an object of the desired type; None means no conversion

• default – a default value of the desired type or a subclass of Exception which will be raised instead

Returns

converter function

Return type

function(str)

easimpconf.convert_string(*, start='|', newlines=True)

Return a function that can be used as a converter.

The default converter str handles multiline values like ConfigParser, i.e. preserving newlines but ignoring indentations (because nothing gets realy converted).

A converter returned by this function can handle such values different.

>>> s = '''
... |def add(a, b):
... |    return a + b
'''
>>> print(convert_string()(s))
def add(a, b):
    return a + b

Parameters

• start (str) – a single none-whitspace character that starts a line

• newlines (bool) – if True newlines will be preserved

Raises

ValueError – if start is not a single character

Returns

converter function

Return type

function(str)