API Reference

The Configuration Entry class

class aegir.ConfigEntry

Base class for configuration entries.

Values of class attributes can be overwritten by loading YAML configuration files. Otherwise, their given default values will be used. The exception is class attributes whose names begin with an underscore; they always behave like normal class attributes and therefore their values cannot be overwritten by config files.

Parameters

path (str) – Path to use for attribute lookup in the config. Default to the containing module’s fully-qualified name when the value is None or an empty string.
check_attributes (bool) – True if a check should be performed for attributes without defined values. If False, check_attributes() can be manually called later. Default to True.

Raises

PathConflict – An entry is already registered at path.
ConfigurationError – A node along path is not a mapping node.
ConfigurationKeyError – A class attribute doesn’t have a defined value.
InvalidOperation – This class or a subclass of it is instantiated.

Return type

NoReturn

Loading your Configuration

aegir.load(path, encoding=None, check_constructors=True, yaml_loader=<class 'aegir.file.AegirYamlFullLoader'>)

Read a YAML file at path and update the configuration with its values.

Overwrite default values set in ConfigEntry objects with values from the YAML file. A YAML node overwrites an attribute of a ConfigEntry if their paths are equal. The path of the node is the dot-delimited concatenation of its parents’ keys with its own key. In the following example, the path of the node ‘class’ is ‘module.class’.

module:
    class:
        attribute_1: value

Nodes may be fully expanded (like above), partially collapsed, or fully collapsed. A ConfigEntry node’s definition could be split by using different levels of expansion. For example,

module:
    class:
        attribute_1: value

module.class:
    attribute_2: value

module.class:
    attribute_3: value

would overwrite attribute_1 and attribute_3 of the ConfigEntry for the path ‘package.module’. When a key is defined multiple times, the last definition is the one used. Therefore, attribute_2 is not included.

The YAML does not strictly have to contain nodes that correspond to ConfigEntry objects. For example, it’s valid to have a non-ConfigEntry node marked by an anchor which is later referenced in some node that does correspond to a ConfigEntry. There could be nodes that are simply not used at all. It’s even valid for the root to not be a mapping node. Such file would effectively configure nothing, but loading it is still supported.

A !REF constructor can be used to reference another attribute of a ConfigEntry. For example,

module_1:
    class:
        attribute_1: value

module_2:
    class:
        attribute_2: !REF module_1.class.attribute_1

would make attribute_2 have the same value as attribute_1. As described above, the value of attribute_1 follows the same behaviour expected for any other attribute.

Parameters

path (Union[AnyStr, PathLike]) – The path to the configuration file.
encoding (Optional[str]) – The encoding with which to open the file. Same as the encoding parameter of the open() built-in. PyYAML only supports utf-16-le, utf-16-be, and utf-8. utf-8 is assumed if the former two are not detected.
check_constructors (bool) – True if constructors should be validated right after loading. If False, check_constructors() can be manually called later. Default to True.
yaml_loader (Type[Loader]) – The YAML loader to use. Default to a full loader with the !REF constructor added.

Raises

FileNotFoundError – The configuration file doesn’t exist.
IOError – An error occurred while reading the file.
yaml.YAMLError – PyYAML failed to load the YAML.
ConfigurationError – A !REF constructor contains a circular reference.

Return type

None

aegir.load_stream(stream, check_constructors=True, yaml_loader=<class 'aegir.file.AegirYamlFullLoader'>)

Read a YAML config from stream and update the configuration with its values.

See the documentation of aegir.load().

Parameters

stream (Union[AnyStr, IO]) – The content of the YAML config to load. Must be a str, Unicode-encoded bytes, or readable file-like object which yields one of the former.
check_constructors (bool) – True if constructors should be validated right after loading. If False, check_constructors() can be manually called later. Default to True.
yaml_loader (Type[Loader]) – The YAML loader to use. Default to a full loader with the !REF constructor added.

Raises

IOError – An error occurred while reading the stream.
yaml.YAMLError – PyYAML failed to load the YAML.
ConfigurationError – A !REF constructor contains a circular reference.

Return type

None

Exceptions

exception aegir.AegirException

Bases: Exception

Base exception of the aegir library.

exception aegir.ConfigurationError

Bases: ValueError, AegirException

The provided configuration is invalid.

exception aegir.ConfigurationKeyError

Bases: AttributeError, AegirException

An invalid key name has been used.

exception aegir.InvalidOperation

Bases: RuntimeError, AegirException

An invalid operation has been performed.

exception aegir.PathConflict

Bases: ValueError, AegirException

Two configuration entries point to the same path.

Specify a different path through the path argument of the metaclass.