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 providedtext
using the specified parser. Iftext
is provided asbytes
, then theencoding
specified will be used to decode it.
- classmethod from_stream(stream, parser=None)#
Construct a
Config
from a stream such as afile
. If the stream does not have aname
attribute from which the correct parser can be guessed, parser must be specified. Iftext
is provided asbytes
, then theencoding
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 apathlib.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
isTrue
, then an emptyConfig
will be returned if the file does not exist.
- classmethod from_env(prefix, types=None)#
Construct a
Config
fromos.environ
entries that matches the specifiedprefix
.prefix
can either be a simple string prefix or adict
mapping string prefixes to the target paths at which they will be stored.types
is an optionaldict
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 providedsource
into it using anymapping
ormergers
provided.See Mapping and Merging for more detail.
- __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 thisConfig
.If
empty
isFalse
, this is done by merging the existing contents with the providedconfig
, giving precedence to theconfig
passed in.If
empty
isTrue
, then the providedconfig
is used to entirely replace the data of thisConfig
.config
may either be aConfig
instance or anything that would be passed to theConfig
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 furtherpush()
ormerge()
calls, or other modifications to thisConfig
object.
- 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 anyConfigNode
objects returned by them.- data#
The underlying python object for this node, often a
dict
or alist
.Warning
data
may be read but should not be modified as problems will occur if theConfigNode
hierarchy anddata
hierarchy become out of sync.
- __getattr__(name)#
Obtain a child of this node by attribute access. If the child is a
dict
orlist
, aConfigNode
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 whenname
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 whenname
is a string.
- __getitem__(name)#
Obtain a child of this node by item access. If the child is a
dict
orlist
, aConfigNode
for it will be returned, otherwise the value itself will be returned.
- __setitem__(name, value)#
Set the
value
for the suppliedname
indata
. Ifdata
is adict
, thenname
must be astr
. Ifdata
is alist
, thenname
must be anint
.
- __delitem__(name)#
Remove the supplied
name
indata
. Ifdata
is adict
, thenname
must be astr
. Ifdata
is alist
, thenname
must be anint
.
- get(name=None, default=None)#
Obtain a child of this node by access like
dict.get()
. If the child is adict
orlist
, aConfigNode
for it will be returned, otherwise the value itself will be returned.If
name
is not specified, thedata
for this node will be returned. This can be helpful when usingnode()
to returnConfigNode
objects for simple values.
- items()#
Obtain children of this node by access like
dict.items()
. If the child is adict
orlist
, aConfigNode
for it will be returned, otherwise the value itself will be returned.
- __iter__()#
Obtain children of this node by either
dict
orlist
iteration, depending on the type of the underlyingdata
. If the child is adict
orlist
, aConfigNode
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 fromsource
.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 useset()
even for values in dictionaries or items in lists.If
create
isTrue
, all nodes along the path will be created as dictionaries if they do not exist.
- __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.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
.
- 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.
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.