lir.config.base module

class lir.config.base.ConfigParser[source]

Bases: ABC

Abstract base configuration parser class.

Each implementation should implement a custom parse() method which is dedicated to parsing a specific aspect, e.g. the configuration for setting up the numpy CSV writer.

static get_type_name(obj: Any) → str[source]

Return the fully qualified type name.

Parameters:

obj (Any) – Class or object with __module__ and __qualname__ attributes.

Returns:

Fully qualified name.

Return type:

str

abstractmethod parse(config: ContextAwareDict, output_dir: Path) → Any[source]

Parse a specific configuration section.

Parameters:

  • config (ContextAwareDict) – Configuration section to parse.

  • output_dir (Path) – Directory where produced outputs may be written.

Returns:

Object configured from config.

Return type:

Any

reference() → str[source]

Return the full class name that was used to initialize this parser.

By default, return the name of this class. In a subclass that was initialized with another class or function that does the actual work, the name of that class is returned.

Returns:

Fully qualified class name for this parser instance.

Return type:

str

class lir.config.base.ContextAwareDict(context: list[str], *args: Any, **kwargs: Any)[source]

Bases: dict

Dictionary wrapper which has knowledge about its context.

Parameters:

  • context (list[str]) – YAML path used for contextual error messages.

  • *args (Any) – Positional arguments passed to dict.

  • **kwargs (Any) – Keyword arguments passed to dict.

clone(context: list[str] | None = None) → ContextAwareDict[source]

Create a cloned dictionary with expanded nested context.

Parameters:

context (list[str] | None, optional) – Replacement context. If omitted, the current context is reused.

Returns:

Cloned and context-aware dictionary.

Return type:

ContextAwareDict

class lir.config.base.ContextAwareList(context: list[str], *args: Any, **kwargs: Any)[source]

Bases: list

List wrapper which has knowledge about its context.

Parameters:

  • context (list[str]) – YAML path used for contextual error messages.

  • *args (Any) – Positional arguments passed to list.

  • **kwargs (Any) – Keyword arguments passed to list.

clone(context: list[str] | None = None) → ContextAwareList[source]

Create a cloned list with expanded nested context.

Parameters:

context (list[str] | None, optional) – Replacement context. If omitted, the current context is reused.

Returns:

Cloned and context-aware list.

Return type:

ContextAwareList

class lir.config.base.GenericConfigParser(component_class: type[Any])[source]

Bases: ConfigParser

Return an instantiation of a class, initialized with the specified arguments.

Parameters:

component_class (type[Any]) – Class to instantiate from configuration values.

parse(config: ContextAwareDict, output_dir: Path) → Any[source]

Instantiate the configured component class.

Parameters:

  • config (ContextAwareDict) – Keyword arguments for class initialisation.

  • output_dir (Path) – Unused output directory argument required by the parser API.

Returns:

Instantiated object.

Return type:

Any

reference() → str[source]

Return the fully qualified name of the wrapped class.

Returns:

Fully qualified class name.

Return type:

str

class lir.config.base.GenericFunctionConfigParser(component_class: Callable)[source]

Bases: ConfigParser

Parser for callable functions or component classes.

Parameters:

component_class (Callable) – Callable that should be exposed by this parser.

parse(config: ContextAwareDict, output_dir: Path) → Callable[source]

Parse configuration into a callable.

Parameters:

  • config (ContextAwareDict) – Configuration section for validation context.

  • output_dir (Path) – Unused output directory argument required by the parser API.

Returns:

Resolved callable object.

Return type:

Callable

reference() → str[source]

Return the fully qualified name of the wrapped callable.

Returns:

Fully qualified callable name.

Return type:

str

exception lir.config.base.YamlParseError(config_context_path: list[str], message: str)[source]

Bases: ValueError

Error raised when parsing YAML configuration fails, mentioning specific YAML path.

Parameters:

  • config_context_path (list[str]) – Dot-path to the failing configuration node.

  • message (str) – Human-readable validation or parsing message.

lir.config.base.check_is_empty(config: ContextAwareDict, accept_keys: Sequence[str] | None = None) → None[source]

Ensure all defined expected arguments are parsed and warn about ignored arguments.

If any unexpected arguments remain, a YamlParseError is raised indicating the argument was unexpected and not taken into account (i.e. not parsed). This methodology ensures the user does not assume arguments are parsed that are in fact not recognized.

Parameters:

  • config (ContextAwareDict) – Configuration to validate for remaining keys.

  • accept_keys (Sequence[str] | None, optional) – Keys that may remain without raising an error.

Returns:

This function raises on invalid input and otherwise returns None.

Return type:

None

lir.config.base.check_not_none(v: AnyType | None, message: str | None = None) → AnyType[source]

Validate a value is not None.

Parameters:

  • v (AnyType | None) – Value to validate.

  • message (str | None, optional) – Error message used when v is None.

Returns:

Original non-None value.

Return type:

AnyType

lir.config.base.check_type(type_class: Any, v: ContextAwareDict | ContextAwareList | None | int | float | str, message: str | None = None) → Any[source]

Check whether a value is an instance of a type.

Returns the value if successful, raises an exception otherwise.

Value types that may be found in YAML configurations: - dict - list - int - float - str - NoneType

Parameters:

  • type_class (Any) – Target type or tuple of target types.

  • v (YamlValueType) – Value to validate.

  • message (str | None, optional) – Error message used when validation fails.

Returns:

Original value when type validation succeeds.

Return type:

Any

lir.config.base.config_parser(func: Callable[[ContextAwareDict, Path], Any] | None = None, /, reference: str | Any | None = None) → Callable[source]

Wrap a parsing function in a ConfigParser object using a decorator.

The resulting ConfigParser instance exposes a parse() method, as required by the API. The body of the decorated function is executed when the parse() method is called.

This decorator can be used as follows:

@config_parser
def foo(config, config_context_path, output_dir):
    if "some_argument" not in config or "another_argument" not in config:
        raise YamlParseError(
            config_context_path,
            "a required argument is missing",
        )
    return Bar(config["some_argument"], config["another_argument"])

After decoration, foo is replaced by a ConfigParser instance whose parse() method executes the original function body. See the documentation of ConfigParser for the meaning of the arguments.

The annotated function will be the reference object that users will be referred to for documentation. If the annotation has a reference argument, that value will be used instead. The reference value may be a str or a Python object. Example of use:

@config_parser(reference=Bar)
def foo(config, config_context_path, output_dir):
    if "some_argument" not in config or "another_argument" not in config:
        raise YamlParseError(
            config_context_path,
            "a required argument is missing",
        )
    return Bar(config["some_argument"], config["another_argument"])
Parameters:

  • func (Callable[[ContextAwareDict, Path], Any] | None, optional) – Function to wrap as a config parser.

  • reference (str | Any | None, optional) – Explicit reference name or object used in generated metadata.

Returns:

Decorator result or wrapped ConfigParser implementation.

Return type:

Callable

lir.config.base.get_full_name(obj: Any) → str[source]

Return the full name of an importable object.

from lir import FeatureData
print(get_full_name(FeatureData))
'lir.FeatureData'
Parameters:

obj (Any) – Importable object.

Returns:

Fully qualified object name.

Return type:

str

lir.config.base.pop_field(config: ContextAwareDict | Any, field: str, default: Any = None, required: bool | None = None, validate: Callable[[Any], Any] | None = None) → Any[source]

Validate and retrieve the value for a given field, after which it is removed from the configuration.

Parameters:

  • config (ContextAwareDict | Any) – Configuration object to pop from.

  • field (str) – Field name to retrieve.

  • default (Any, optional) – Value to return when field is absent.

  • required (bool | None, optional) – Whether to raise when the field is absent. Defaults to True when default is None.

  • validate (Callable[[Any], Any] | None, optional) – Optional validator applied to the popped value.

Returns:

Popped field value or default.

Return type:

Any