API Reference¶

@confugue.configurable(*, params=ALL, cfg_property='_cfg', cfg_param='_cfg')¶

A decorator that makes a function or a class configurable.

The decorator may be used with or without parentheses (i.e. both @configurable and @configurable() is valid).

If the decorated callable is a function or method, it needs to define a keyword-only argument _cfg, which will be automatically filled with an instance of Configuration when the function is called. If the decorated callable is a class, a _cfg property will be created holding the Configuration instance.

The decorated function/class can be called/instantiated normally (without passing the _cfg argument), or via Configuration.configure().

Parameters

params – A list of configuration keys to pass as keyword arguments. The default behavior is to include all keys matching the function’s signature, or all keys if the signature contains a ** parameter.
cfg_property – The name of the property that will hold the Configuration object in the case where a class is beging decorated.
cfg_param – The name of the parameter that will receive the Configuration object in the case where a function is being decorated. This needs to be a keyword-only parameter.

class confugue.Configuration(value: Any = MISSING_VALUE, name: str = '<root>')¶

Wrapper for nested configuration dictionaries or lists.

The core functionality is provided by the configure() method, which calls a given callable with the arguments from the wrapped dictionary.

If the wrapped value is a dictionary or a list, basic operations such as indexing and iteration are supported, with the values recursively wrapped in Configuration objects. If the user tries to access a key or index which is missing, an “empty” configuration object is returned; this can still be used normally and behaves more or less as if it contained an empty dictionary.

The wrapped value may be of any other type, but in this case, most of the methods will raise an exception. To retrieve the raw wrapped value (whatever the type), use the get() method with no arguments.

configure(constructor: Optional[Callable] = None, /, **kwargs) → Any¶

Configure a callable using this configuration.

Calls constructor with the keyword arguments specified in this configuration object or passed to this method. Note that the constructor is called even if this configuration object corresponds to a missing key. constructor may be overridden in by a class configuration key (if the constructor parameter is not given, then the class key is required).

Any keyword arguments passed to this method are treated as defaults and can be overridden by the configuration. A special Configuration.REQUIRED value can be used to mark a given key as required.

Returns: The return value of constructor, or None if the wrapped value is None.
Raises: ConfigurationError – If the wrapped value is not a dict, if required arguments are missing, or if any exception occurs while calling constructor.

maybe_configure(constructor: Optional[Callable] = None, /, **kwargs) → Any¶

Configure a callable only if the configuration is present.

Like configure(), but returns None if the configuration is missing.

Returns: The return value of constructor, or None if the wrapped value is missing or None.
Raises: ConfigurationError – If the wrapped value is not a dict, if required arguments are missing, or if any exception occurs while calling constructor.

configure_list(constructor: Optional[Callable] = None, /, **kwargs) → Optional[List]¶

Configure a list of objects.

This method should be used if the configuration is expected to be a list. Every item of this list will then be used to configure a new object, as if configure() was called on it. Any defaults supplied to this method will be used for all the items.

Returns: A list containing the values obtained by configuring constructor, in turn, using all the dicts in the wrapped list; None if the wrapped value is None.
Raises: ConfigurationError – If the wrapped value is not a list of dicts, if required arguments are missing, or if any exception occurs while calling constructor.

bind(constructor: Optional[Callable] = None, /, **kwargs) → Optional[Callable]¶

Configure a callable without calling it.

Like configure(), but instead of calling constructor directly, it returns a new function that calls constructor with parameters bound to the supplied values. The function may still accept other parameters.

Returns: A function, or None if the wrapped value is None.
Raises: ConfigurationError – If the wrapped value is not a dict, or if required arguments are missing.

maybe_bind(constructor: Optional[Callable] = None, /, **kwargs) → Optional[Callable]¶

Configure a callable without calling it, but only if the configuration is present.

Like bind(), but returns None if the configuration is missing.

Returns: A function, or None if the wrapped value is missing or None.
Raises: ConfigurationError – If the wrapped value is not a dict, or if required arguments are missing.

get(key: Hashable = None, default: Any = NO_DEFAULT) → Any¶

Return an item from this configuration object (assuming the wrapped value is indexable).

Returns

If key is given, the corresponding item from the wrapped object. Otherwise, the entire wrapped value. If the value is missing, default is returned instead (if given).

Raises

KeyError – If the value is missing and no default was given.
IndexError – If the value is missing and no default was given.
TypeError – If the wrapped object does not support indexing.

get_unused_keys(warn: bool = False) → List[Hashable]¶

Recursively find keys that were never accessed.

Parameters: warn – If True, a warning will be issued if unused keys are found.
Returns: A list of unused keys.

classmethod from_yaml(stream: str | bytes | TextIO | BinaryIO, loader=yaml.Loader) → Configuration¶

Create a configuration from YAML.

The configuration is loaded using PyYAML’s (potentially unsafe) Loader by default. If you wish to load configuration files from untrusted sources, you should pass loader=yaml.SafeLoader.

Parameters

stream – A YAML string or an open file object.
loader – One of PyYAML’s loader classes.

Returns

A Configuration instance wrapping the loaded configuration.

classmethod from_yaml_file(stream: str | TextIO | BinaryIO, loader=yaml.Loader) → Configuration¶

Create a configuration from a YAML file.

The configuration is loaded using PyYAML’s (potentially unsafe) Loader by default. If you wish to load configuration files from untrusted sources, you should pass loader=yaml.SafeLoader.

Parameters

stream – A path to a YAML file, or an open file object.
loader – One of PyYAML’s loader classes.

Returns

A Configuration instance wrapping the loaded configuration.

class confugue.interactive(mode: str = 'all')¶

A context manager that enables or disables the interactive editing mode.

Parameters: mode – ‘all’ to edit all values, ‘missing’ to edit only missing values, or ‘none’ to disable the interactive mode.

class confugue.ConfigurationError¶

class confugue.ConfigurationWarning¶