factory

class BuildInfo(module, config_cls, class_str, field_locations, location_str)

Bases: object

Information required to construct an object from a configuration dictionary.

module

Imported module containing the object class and validation model.

Type:

ModuleType

config_cls

Pydantic model used to validate the configuration.

Type:

type[BaseModel]

class_str

Name of the class to instantiate.

Type:

str

field_locations

Mapping between configuration fields and their source locations in the configuration file.

Type:

dict | None

location_str

Human-readable location of the object definition in the configuration file.

Type:

str

class_str: str

config_cls: type[BaseModel]

field_locations: dict | None

location_str: str

module: ModuleType

class ElementRegistry

Bases: object

Singleton registry of all instantiated Elements.

Elements are registered by name and can later be retrieved individually, by wildcard pattern, or by type.

Return the singleton registry instance.

clear()

Remove all registered elements.

get(name)

Return an Element by name.

Parameters:

name (str) – Element name.

Returns:

Element – Registered element.

Raises:

PyAMLConfigException – If the element is not registered.

get_by_name(wildcard)

Return all elements whose name matches a wildcard pattern.

Parameters:

wildcard (str) – Wildcard expression compatible with fnmatch.

Returns:

list[Element] – Matching elements.

get_by_type(element_type)

Return all registered elements of the given type.

Parameters:

element_type (type[Element]) – Element type to match.

Returns:

list[TElement] – Matching elements.

register(element)

Register an Element by name.

Parameters:

element (Element) – Element to register.

Raises:

PyAMLConfigException – If the object is not an Element or if another element with the same name is already registered.

class PyAMLFactory

Bases: object

Factory for constructing PyAML objects from configuration data.

build(data, ignore_external)

Recursively build objects from configuration data.

Lists are traversed recursively and configuration dictionaries are converted into instantiated objects.

Parameters:

• data (dict | list) – Configuration data to build.

• ignore_external (bool) – Ignore missing external modules and return None for objects that cannot be constructed.

Returns:

Any – Built object, list of objects, or native value.

build_object(data, ignore_external=False)

Build a single object from a configuration dictionary.

The configuration is validated using the associated Pydantic model before the target class is instantiated.

Parameters:

• data (dict) – Object configuration.

• ignore_external (bool) – Ignore missing external modules.

Returns:

Any – Instantiated object or UnboundElement.

clear()

Remove all registered elements from the global registry.

get_field_type(config_cls, field_name)

Return the annotated type of a configuration field.

Parameters:

• config_cls (type[BaseModel] | None) – Pydantic configuration model.

• field_name (str) – Name of the field.

Returns:

type | None – Annotated field type, or None if the field is not defined in the model.

handle_validation_error(exc, type_str, location_str, field_locations)

Convert a Pydantic validation error into a PyAMLConfigException.

Validation errors are reformatted to include the corresponding configuration field and, when available, the source file location of the field in the configuration file.

Parameters:

• exc (ValidationError) – Pydantic validation error.

• type_str (str) – Name of the object type being validated.

• location_str (str) – Human-readable location of the object definition in the configuration file.

• field_locations (dict | None) – Mapping between field names and their source locations in the configuration file.

Raises:

PyAMLConfigException – Always raised with a formatted summary of the validation errors. The original Pydantic exception traceback is suppressed.

resolve_build_info(data, ignore_external)

Resolve the information required to construct an object.

The configuration dictionary is inspected to determine the module, object class and validation model to use. The referenced module is imported and the corresponding validation class is retrieved.

Parameters:

• data (dict) – Configuration dictionary describing the object.

• ignore_external (bool) – Ignore missing modules and return None instead of raising an exception.

Returns:

BuildInfo | None – Information required to construct the object, or None when ignore_external is enabled and the referenced module cannot be imported.

Raises:

PyAMLConfigException – If the configuration is invalid, the referenced class cannot be resolved, or the validation model cannot be found.