qmi.core.config_struct

Routines for structured configuration data.

This module provides functions for loading configuration data into a tree structure of Python data classes. This provides two advantages:

  1. The configuration file is validated and type-checked against the expected structure immediately when the file is loaded.

  2. The configuration data can be accessed through attributes of well-typed data classes instead of through dictionary lookups.

The structure of the configuration data is defined as a set of data classes. Each structure is defined using the @configstruct decorator.

Only the following data types are allowed for fields of configuration structures:

  • int, float, str, bool

  • another configuration structure type;

  • list[T] where T is a supported field type

  • dict[str, T] where T is a supported field type

  • tuple[T1, T2, T3] or tuple[T, ...] where T, T1, etc are supported field types

  • Optional[T] where T is a supported field type

  • Any

A default value may be specified in the data class definition. The default value, if present, will be used when the field is not present in the configuration data. Fields without default value are mandatory.

Existing structure definitions may be extended (for example at application level). This is done by subclassing the existing definition and adding more fields.

Functions

config_struct_from_dict(data, cls)

Convert configuration data from a dictionary to a dataclass instance.

config_struct_to_dict(cfg)

Convert configuration data from a dataclass instance to a dict.

configstruct(cls)

Class decorator to mark classes that hold QMI configuration data.
qmi.core.config_struct.configstruct(cls: type[_T]) → type[_T]

Class decorator to mark classes that hold QMI configuration data.

This decorator is based on the standard @dataclass decorator. It calls @dataclass(init=False) to do most of the work, then adds a custom __init__() method.

qmi.core.config_struct.config_struct_to_dict(cfg: Any) → dict[str, Any]

Convert configuration data from a dataclass instance to a dict.

The returned dict will be suitable for serialization to JSON.

Parameters:

cfg – Configuration data (an instance of a dataclass).

Returns:

The configuration data converted to a dictionary.

qmi.core.config_struct.config_struct_from_dict(data: dict[str, Any], cls: type[_T]) → _T

Convert configuration data from a dictionary to a dataclass instance.

The input data is typically obtained by parsing a JSON file.

Parameters:

  • data – Configuration data as a dict instance.

  • cls – Dataclass type to be used for holding the configuration data.

Returns:

An instance of the specified dataclass containing the configuration data.

Raises:

QMI_ConfigurationException – If the configuration data does not match the expected structure.