API Reference#

Configuration#

class configurator.Config(data=None)#

Bases: ConfigNode

The root of the configuration store.

classmethod from_text(text, parser, encoding='ascii')#: Construct a Config from the provided text using the specified parser. If text is provided as bytes, then the encoding specified will be used to decode it.

classmethod from_stream(stream, parser=None)#: Construct a Config from a stream such as a file. If the stream does not have a name attribute from which the correct parser can be guessed, parser must be specified. If text is provided as bytes, then the encoding specified will be used to decode it.

classmethod from_path(path, parser=None, encoding=None, optional=False)#

Construct a Config from file specified as either a string path or a pathlib.Path. This path with have ~ expanded. If specified, encoding will be used to decode the content of the file. An explicit parser can be specified, if necessary, but the correct one will usually be guessed from the file extension.

If optional is True, then an empty Config will be returned if the file does not exist.

classmethod from_env(prefix, types=None)#: Construct a Config from os.environ entries that matches the specified prefix. prefix can either be a simple string prefix or a dict mapping string prefixes to the target paths at which they will be stored. types is an optional dict mapping string suffixes to callables used to convert matching environment values to the correct type.

merge(source=None, mapping=None, mergers=None)#

Modify this Config by merging the provided source into it using any mapping or mergers provided.

See Mapping and Merging for more detail.

clone()#: Clone this Config creating copies of all mutable objects it contains.

__add__(other)#: Configuration stores can be added together. This will result in a new Config object being returned that is created by merging the two original configs.

push(config=None, empty=False)#

Push the provided config onto this instance, replacing the data of this Config.

If empty is False, this is done by merging the existing contents with the provided config, giving precedence to the config passed in.

If empty is True, then the provided config is used to entirely replace the data of this Config.

config may either be a Config instance or anything that would be passed to the Config constructor.

This method returns a context manager that, when its context is left, restores the configuration data used to whatever was in place before push() was called, regardless of any further push() or merge() calls, or other modifications to this Config object.

pop()#: Pop off the top-most data that was last pushed on to this Config.

data#: The underlying python object for this node, often a dict or a list.

Warning

data may be read but should not be modified as problems will occur if the ConfigNode hierarchy and data hierarchy become out of sync.

class configurator.node.ConfigNode(data=None, container=None, accessor=None)#

A node in the configuration store. These are obtained by using the methods below on Config objects or any ConfigNode objects returned by them.

data#: The underlying python object for this node, often a dict or a list.

Warning

data may be read but should not be modified as problems will occur if the ConfigNode hierarchy and data hierarchy become out of sync.

__getattr__(name)#: Obtain a child of this node by attribute access. If the child is a dict or list, a ConfigNode for it will be returned, otherwise the value itself will be returned.

__setattr__(name, value)#: Set a child of this node. This is a convenience helper that calls __setitem__() and can be used when name is a string.

__delattr__(name)#: Remove a child of this node by attribute access. This is a convenience helper that calls __delitem__() and can be used when name is a string.

__getitem__(name)#: Obtain a child of this node by item access. If the child is a dict or list, a ConfigNode for it will be returned, otherwise the value itself will be returned.

__setitem__(name, value)#: Set the value for the supplied name in data. If data is a dict, then name must be a str. If data is a list, then name must be an int.

__delitem__(name)#: Remove the supplied name in data. If data is a dict, then name must be a str. If data is a list, then name must be an int.

get(name=None, default=None)#

Obtain a child of this node by access like dict.get(). If the child is a dict or list, a ConfigNode for it will be returned, otherwise the value itself will be returned.

If name is not specified, the data for this node will be returned. This can be helpful when using node() to return ConfigNode objects for simple values.

items()#: Obtain children of this node by access like dict.items(). If the child is a dict or list, a ConfigNode for it will be returned, otherwise the value itself will be returned.

__iter__()#: Obtain children of this node by either dict or list iteration, depending on the type of the underlying data. If the child is a dict or list, a ConfigNode for it will be returned, otherwise the value itself will be returned.

node(path=None, create=False)#

Obtain a child of this node using a dotted path or Path such as one generated from source. path may also be a simple string or integer, in which case it will be used to obtain a child of this node using item access.

This always returns a ConfigNode or raises an exception if the path cannot be resolved. This allows you to use set() even for values in dictionaries or items in lists.

If create is True, all nodes along the path will be created as dictionaries if they do not exist.

set(value)#: Replace the data of this node with the supplied value.

__repr__()#: Return repr(self).

class configurator.parsers.ParseError#: The exception raised when an appropriate parser cannot be found for a config stream.

Mapping and Merging#

configurator.source#: The root generative source Path for creating mappings.

configurator.target#: The root generative target Path for creating mappings.

configurator.convert(source, callable_)#: A mapping operation that indicates the source value should be converted by calling callable_ with the original value and then using that result from that point in the mapping operation onwards.

configurator.required(source)#: A mapping operation that indicates the source value is required. If it is not present, the exception that occurred when trying to obtain it will be raised.

configurator.if_supplied(source, false_values=(None, ''))#: A mapping operation that indicates the source value should be treated as not present if its value is in the supplied list of false_values.

configurator.value(value)#: A mapping operation that provides a literal source value.

class configurator.path.Path(name, *ops)#

A generative object used for constructing source or target mappings. See Mapping and Merging for details.

__getitem__(name)#: Indicate that the source or target should be traversed by item access.

__getattr__(name)#: Indicate that the source or target should be traversed by attribute access.

insert(index)#: Indicate that a target should be mapped by inserting at the specified index.

append()#: Indicate that a target should be mapped by appending.

merge()#: Indicate that a target should be mapped by merging.

configurator.default_mergers#: The default set of mergers, which recursively merge dicts using the union of their keys and merge lists by appending the contents of the new list to the existing list.

Patterns of use#

configurator.patterns.load_with_extends(path, key='extends', root=None)#

Helper for the “extends” pattern.

Parameters

path – The path of the configuration file to start with.
key – The key to use to indicate that another file should be used as a base.
root – If supplied, configuration is extracted from this key at the root of each configuration file that is loaded, provided it is present. If missing from any file, the whole configuration from that file is used instead.