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.

Subpackages

• cfglib.sources package
  • Submodules
  • cfglib.sources.args module
  • cfglib.sources.env module

Submodules

cfglib.config module

class cfglib.config.Config

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()

reload()

Reload all config items from its backing store. The contents may change arbitrarily.

Not all configs can meaningfully reload. In this case this method will do nothing. Some configs always pull fresh data. In that case this method also does nothing.

snapshot() → DictConfig

Return a copied snapshot of this config, backed by memory

class cfglib.config.MutableConfig

Bases: abc.ABC, collections.abc.MutableMapping, cfglib.config.Config

An abstract base class for mutable configs (with __setitem__)

class cfglib.config.DictConfig

Bases: dict, cfglib.config.MutableConfig

A config backed by its own dictionary stored in memory. In other words, a fancy dict.

reload()

Does nothing.

replace(other: cfglib.config.Config)

Update self in place to become a shallow copy of other

class cfglib.config.ProxyConfig(source: Mapping[KT, VT_co])

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.

reload()

Reload source if it’s a Config, otherwise do nothing.

class cfglib.config.CachingConfig(wrapped_config: cfglib.config.Config)

Bases: cfglib.config.DictConfig

A config that copies data from a wrapped config once and returns data from this copy, until manually reloaded.

reload()

Refresh the underlying config and update the cache.

class cfglib.config.CompositeConfig(subconfigs: Iterable[cfglib.config.Config])

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.

reload()

Reload subconfigs.

class cfglib.config.ConfigProjection

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

Should a projected config key be accepted by the ProjectedConfig?

is_relevant_sourcekey(sourcekey: str) → bool

Should a source config key be used by the ProjectedConfig?

key_to_sourcekey(key: str) → str

Map a ProjectedConfig’s key to a source config’s key

sourcekey_to_key(sourcekey: str) → str

Map source config’s key to a a ProjectedConfig’s key

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)

Bases: cfglib.config.ConfigProjection

A helper to easily create a ConfigProjection

is_relevant_key(key: str) → bool

Check that sk2k(k2sk(k)) maps key to itself and, by default, compute source key and defer to is_relevant_sourcekey.

is_relevant_sourcekey(sourcekey: str) → bool

Check that k2sk(sk2k(sk)) maps sourcekey to itself and, by default, return True.

key_to_sourcekey(key: str) → str

By default, identity function.

sourcekey_to_key(sourcekey: str) → str

By default, identity function.

class cfglib.config.ProjectedConfig(subconfig: cfglib.config.Config, projection: cfglib.config.ConfigProjection)

Bases: cfglib.config.MutableConfig

Config that renames or filters source config’s keys.

reload()

Reload the source config.

cfglib.config.to_cfg(value: Any) → cfglib.config.Config

cfglib.config.to_cfg_list(value: Any) → List[cfglib.config.Config]

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

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)

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.

apply_validators(value: Any) → Any

validate_value(value: Any) → Any

Validate a value and return the result (with default possibly replacing null values)

validate_value_custom(value: Any) → Any

Override this method to implement custom setting type-specific validation logic.

class cfglib.spec.StringSetting(*, default: Union[cfglib.spec.Marker, None, str] = MISSING, **kwargs)

Bases: cfglib.spec.Setting

validate_value_custom(value: Any) → Optional[str]

class cfglib.spec.BoolSetting(*, default: Union[cfglib.spec.Marker, None, bool] = MISSING, **kwargs)

Bases: cfglib.spec.Setting

validate_value_custom(value: Any) → Optional[bool]

class cfglib.spec.IntSetting(*, default: Union[cfglib.spec.Marker, None, int] = MISSING, **kwargs)

Bases: cfglib.spec.Setting

validate_value_custom(value: Any) → Optional[int]

class cfglib.spec.FloatSetting(*, default: Union[cfglib.spec.Marker, None, float] = MISSING, **kwargs)

Bases: cfglib.spec.Setting

validate_value_custom(value: Any) → Optional[float]

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)

Bases: cfglib.spec.Setting

validate_value_custom(value: Any) → Optional[Mapping[KT, VT_co]]

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)

Bases: cfglib.spec.Setting

validate_value_custom(value: Any) → Union[cfglib.spec.Marker, None, List[Any]]

class cfglib.spec.ConfigSpec(settings_iterable: Iterable[cfglib.spec.Setting], allow_extra: bool = False)

Bases: object

A set of settings specifying some config.

validate_config(config: cfglib.config.Config)

Validate all settings of a config.

validate_setting(config: cfglib.config.Config, setting_name: str)

Validate one setting of a config.

class cfglib.spec.SpecValidatedConfig(subconfigs: Union[Mapping[KT, VT_co], Iterable[Mapping[KT, VT_co]]], validate=True)

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.

validate()

Revalidate this config according to the spec.

cfglib.validation module

class cfglib.validation.ValidationContext(field_name: Optional[str])

Bases: object

exception cfglib.validation.ValidationError

Bases: Exception

Raised when a setting value is not valid according to the setting parameters

cfglib.validation.value_type(type_spec: Union[type, Tuple[type, ...]])