API Reference¶
-
class
clac.
CLAC
(*layers)[source]¶ Configuration container/manager.
__init__()
parameters are the same asadd_layers()
.-
add_layers
(*layers)[source]¶ 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]][source]¶ 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[source]¶ 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. Ifcallback
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 aNoConfigKey
exception. However, the__getitem__
syntax does not support additional arguments. This means that onlyget()
will support defaults and coercion, and only__getitem__
will support exception bubbling.
-
insert_layers
(*layers, raise_on_replace=True)[source]¶ 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 ifraise_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)[source]¶ 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 anderror_ok
is False
-
-
class
clac.
BaseConfigLayer
(name: str, mutable: bool = False)[source]¶ 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 namedConfLayer
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 themutable()
property.
-
get
(key: str, default=None) → Any[source]¶ Gets the value for the specified
key
Returns
default
ifkey
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__()
orsetdefault()
must manually perform the check by callingself.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-specificget
andset
-type calls.
-
names
¶ Returns the full list of keys in the Layer
-
class
clac.
DictLayer
(name: str, config_dict: Optional[dict] = None, mutable: bool = False, dot_strategy: clac.core.DictStructure = <DictStructure.Flat: 2>)[source]¶ 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 toDictStructure.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