cfglib package¶
Top-level package for cfglib.
Objects from the config and spec submodules are reexported to the root, so you can use e.g. cfglib.Config.
Submodules¶
cfglib.config module¶
-
class
cfglib.config.
Config
[source]¶ Bases:
collections.abc.Mapping
An abstract configuration interface
A config is really just a dict with some extra methods.
In a custom implementation you need to define at least:
- __getitem__(item)
- __iter__()
- __len__()
- reload()
-
class
cfglib.config.
MutableConfig
[source]¶ Bases:
abc.ABC
,collections.abc.MutableMapping
,cfglib.config.Config
An abstract base class for mutable configs (with __setitem__)
-
class
cfglib.config.
DictConfig
[source]¶ Bases:
dict
,cfglib.config.MutableConfig
A config backed by its own dictionary stored in memory. In other words, a fancy dict.
-
class
cfglib.config.
ProxyConfig
(source: Mapping[KT, VT_co])[source]¶ Bases:
cfglib.config.MutableConfig
A config that uses a separate mapping as source.
Unlike DictConfig, this is not by itself a dict, it only references a dict.
Althouth this class has basically zero logic, it’s useful to: - Wrap any mapping to conform to the Config interface - Be a level of indirection to switch source configs easily by changing .source field.
-
class
cfglib.config.
CachingConfig
(wrapped_config: cfglib.config.Config)[source]¶ Bases:
cfglib.config.DictConfig
A config that copies data from a wrapped config once and returns data from this copy, until manually reloaded.
-
class
cfglib.config.
CompositeConfig
(subconfigs: Iterable[cfglib.config.Config])[source]¶ Bases:
cfglib.config.Config
A config backed by multiple configs
Entries are searched in subconfigs in reverse order and the first found value is returned. That is, the first subconfig has the lowest priority, and the last subconfig takes precedence over all others.
-
class
cfglib.config.
ConfigProjection
[source]¶ Bases:
abc.ABC
ABC for a projection to be passed to a ProjectedConfig.
The projection should be consistent, that is:
- k2sk(sk2k(sk)) == sk for all sk that are relevant
- sk2k(k2sk(k)) == k for all k that are relevant
- is_relevant(key) <=> is_relevant_sourcekey(k2sk(k))
-
is_relevant_key
(key: str) → bool[source]¶ Should a projected config key be accepted by the ProjectedConfig?
-
class
cfglib.config.
BasicConfigProjection
(is_relevant_key: Optional[Callable] = None, is_relevant_sourcekey: Optional[Callable] = None, key_to_sourcekey: Optional[Callable] = None, sourcekey_to_key: Optional[Callable] = None)[source]¶ Bases:
cfglib.config.ConfigProjection
A helper to easily create a ConfigProjection
-
is_relevant_key
(key: str) → bool[source]¶ Check that sk2k(k2sk(k)) maps key to itself and, by default, compute source key and defer to is_relevant_sourcekey.
-
-
class
cfglib.config.
ProjectedConfig
(subconfig: cfglib.config.Config, projection: cfglib.config.ConfigProjection)[source]¶ Bases:
cfglib.config.MutableConfig
Config that renames or filters source config’s keys.
cfglib.spec module¶
-
cfglib.spec.
MISSING
= MISSING¶ A singleton marker object denoting that a setting value is (or should be) absent. Absence here means not being in the config at all (raising KeyError on access).
-
class
cfglib.spec.
MissingSettingAction
[source]¶ Bases:
enum.Enum
Action to do when a setting is missing
-
ERROR
= 1¶ Raise an error
-
LEAVE
= 3¶ Leave as it is (missing or None)
-
USE_DEFAULT
= 2¶ Set it to the provided default
-
-
class
cfglib.spec.
Setting
(*, name: Optional[str] = None, default: Union[cfglib.spec.Marker, None, Any] = MISSING, on_missing: cfglib.spec.MissingSettingAction = <MissingSettingAction.USE_DEFAULT: 2>, on_null: cfglib.spec.MissingSettingAction = <MissingSettingAction.LEAVE: 3>, validators: Optional[Iterable[Callable[[cfglib.validation.ValidationContext, Any], Any]]] = None)[source]¶ Bases:
object
Specification for one config’s setting.
Parameters: - name – Name of the setting. Only needs to be specified if passed to a ConfigSpec instead of a SpecValidatedConfig.
- default – The default value to be used when source config doesn’t provide this setting. If the default is needed but was not specified, an error will be raised.
- on_missing – Action to do if this setting is entirely absent from source configs.
- on_null – Action to do if this setting is None in the source configs.
-
class
cfglib.spec.
StringSetting
(*, default: Union[cfglib.spec.Marker, None, str] = MISSING, **kwargs)[source]¶ Bases:
cfglib.spec.Setting
-
class
cfglib.spec.
BoolSetting
(*, default: Union[cfglib.spec.Marker, None, bool] = MISSING, **kwargs)[source]¶ Bases:
cfglib.spec.Setting
-
class
cfglib.spec.
IntSetting
(*, default: Union[cfglib.spec.Marker, None, int] = MISSING, **kwargs)[source]¶ Bases:
cfglib.spec.Setting
-
class
cfglib.spec.
FloatSetting
(*, default: Union[cfglib.spec.Marker, None, float] = MISSING, **kwargs)[source]¶ Bases:
cfglib.spec.Setting
-
class
cfglib.spec.
DictSetting
(*, default: Union[cfglib.spec.Marker, None, Mapping[KT, VT_co]] = MISSING, subtype: Union[cfglib.spec.ConfigSpec, Type[cfglib.spec.SpecValidatedConfig], None] = None, **kwargs)[source]¶ Bases:
cfglib.spec.Setting
-
class
cfglib.spec.
ListSetting
(*, default: Union[cfglib.spec.Marker, None, List[Any]] = MISSING, on_empty: cfglib.spec.MissingSettingAction = <MissingSettingAction.LEAVE: 3>, subsetting: Optional[cfglib.spec.Setting] = None, **kwargs)[source]¶ Bases:
cfglib.spec.Setting
-
class
cfglib.spec.
ConfigSpec
(settings_iterable: Iterable[cfglib.spec.Setting], allow_extra: bool = False)[source]¶ Bases:
object
A set of settings specifying some config.
-
class
cfglib.spec.
SpecValidatedConfig
(subconfigs: Union[Mapping[KT, VT_co], Iterable[Mapping[KT, VT_co]]], validate=True)[source]¶ Bases:
cfglib.config.CompositeConfig
An all-in-one class that allows to specify settings and validate values; takes an iterable of configs as its source of values.
Also defines __getattr__ so settings can be accessed as properties instead of indexing.
Parameters: - subconfigs – A number of source configs, from lowest priority to highest.
- validate – Whether to validate the config right after initialization.
Example:
class ExampleToolConfig(cfglib.SpecValidatedConfig): message = cfglib.StringSetting(default='Hello!') config_file = cfglib.StringSetting(default=None)
-
SPEC
= None¶ ConfigSpec of this config.
-
allow_extra
= False¶ Whether source configs can include extra keys not from the spec.