API Reference

class clac.CLAC(*layers)

Configuration container/manager.

__init__() parameters are the same as add_layers().

add_layers(*layers)

Adds layers to the lookup set. Called by __init__()

Parameters:layers – A FIFO list of ConfigLayer instances. The first layer in this list will be the first layer queried.

build_lri() → Set[Tuple[str, Any]]

Returns the Layer Resolution Index (LRI)

The LRI is a set of 2-tuples which contain the first layer that a key can be found in, and the key itself.

get(key: str, default: Any = None, layer_name: str = None, callback: Callable = None) → Any

Gets values from config layers according to key.

Returns default if value is not found or LookupError is raised.

If layer_name is specified, the method will perform all of the same actions, but only against the layer with the specified name. Must be a str or None. Defaults to None.

If callback is specified, the method will pass the retrieved value to the callback, and return the result. If callback is None, the original result is returned as-is.

Warning

If the value is not found, callback will not be executed on the default value. Applications should provide complete and prepared default values to the method.

Raises:MissingLayer – if layer_name is specified but no layer with that name has been added. Returns:The value retrieved from the config layers, or default if no entry was found.

Note

If an exception is desired instead of a default value, __getitem__ syntax (clac_instance[key]) should be used instead. This will raise a NoConfigKey exception. However, the __getitem__ syntax does not support additional arguments. This means that only get() will support defaults and coercion, and only __getitem__ will support exception bubbling.

insert_layers(*layers, raise_on_replace=True)

Inserts layers into the start of the lookup.

If any layer name already exists, it will be inserted in the new position instead of retaining its old position. This can be used to reorder the priority of any or all of the layers. If a layer name is duplicated in the provided layers parameter, then the first value is taken, and the others are silently ignored.

If any layer name conflicts are detected while moving old layers into the rebuilt lookup, the objects are compared for identity. If the identities match, the new position of the layer is not overwritten with the layer’s previous position. If the identities do not match, LayerOverwriteError is raised, and the operation is cancelled, having no effect on the original lookup. This check is ignored if raise_on_replace is False (default is True).

Warning

This function will rebuild the internal lookup, which can be expensive if there are a large number of entries. However, having a large number of configuration sources is an unusual use case, and should not be considered a major performance impact which needs optimization.

layers

A copy of the internal layer lookup.

names

Returns a set of all unique config keys from all layers.

remove_layer(name: str, error_ok: bool = True)

Remove layer name from the manager.

Parameters:

• name – The name of the layer to be removed.
• error_ok – bool specificying whether to ignore errors. Defaults to True. Will check to make sure layer is missing.

Raises:

MissingLayer if name is not found in lookup and error_ok is False

resolve(key: str) → Tuple[str, Any]

Returns that name of the layer accessed, and the value retrieved.

Parameters:key – The key to search for. Raises:NoConfigKey – key not in any layer. Returns:2-tuple: (layer, value)

setdefault(key: str, default: Any = None) → Any

Call BaseConfigLayer.set_default() on the first mutable layer.

class clac.BaseConfigLayer(name: str, mutable: bool = False)

Abstract Base class for ConfigLayer Implementation

This class cannot be used directly, and will raise TypeError if instantiated. Rather, it is meant to be subclassed to perform its own application-specific configuration handling. For example, a subclass named ConfLayer might be created to read UNIX-style configuration files.

Important

Because this class is based off of the stdlib collections.abc.Mapping abstract class, there are abstract methods not defined in this class which must still be defined by subclasses.

Parameters:

• name – The qualified name of the config layer instance. Will be used to look up the specified layer by the CLAC. This name should not be changed after instantiation.
• mutable – bool representing whether the layer allows mutation. Readable using the mutable() property.

assert_mutable()

Raises ImmutableLayer if layer is not mutable.

get(key: str, default=None) → Any

Gets the value for the specified key

Returns default if key is not found.

mutable

Whether the layer instance is mutable or not.

This value is checked before all internal set-style calls. Any method which overrides __setitem__() or setdefault() must manually perform the check by calling self.assert_mutable() with no arguments.

name

The name of the layer.

The CLAC instance will use this name as a lookup key for all layer-specific operations. This will have no effect on non-specific get and set -type calls.

names

Returns the full list of keys in the Layer

setdefault(key: str, default: Any = None) → Any

If key is in the lookup, return its value.

If key is not in the lookup, insert key with a value of default and return default. default defaults to None.

class clac.DictLayer(name: str, config_dict: Optional[dict] = None, mutable: bool = False, dot_strategy: clac.core.DictStructure = <DictStructure.Flat: 2>)

A config layer based on the python dict type.

name

Behaves the same as all other layers. See BaseConfigLayer for more details.

config_dict

An optional mapping object which contains the initial state of the configuration layer.

mutable

A boolean representing whether the layer should allow mutation.

dot_strategy

One of the variants of the DictStructure enum. Defaults to DictStructure.Flat.

DictStructure.Split will assume a nested dict structure. Keys

will be split by the . character.

DictStructure.Flat will assume a flat dict structure. Keys are

not modified before querying the underlying dict.

This example illustrates both usages

split = {
    'a': {
        'b': {
            'c': 'd'
        }
    }
}

flat = {'a.b.c': 'd')

layer1 = DictLayer('name', split, dot_strategy=DictStructure.Split)
assert layer1['a.b.c'] == 'd'

layer2 = DictLayer('name', flat, dot_strategy=DictStructure.Flat)
assert layer2['a.b.c'] == 'd'

names

Returns a strategy-aware set of valid keys

class clac.DictStructure

Enum for DictLayer structuring strategy.

This enum class exposes two variants:

• Split
• Flat

See DictLayer for more info.