ImportTool

Reads Confugami-compatible .cfg.json files: a folder into a configurable unit facade, a file into one configuration.

Member Functions:

import_configuration_file

import_configuration_file(model_type: type[T], file_path: str | Path)

Read one .cfg.json file into a configuration instance.

The file counterpart of import_config_unit, for converters and standalone configurations that do not belong to a configurable unit.

Parameters
Name Type Description

model_type

type[T]

The configuration class the file is written against.

file_path

str | Path

The file to read.

Returns

T — The validated configuration.

Raises:

  • FileNotFoundError — If file_path does not exist.

  • ValueError — If file_path is not a file, or the document is not a JSON object. Also for a form that Confugami rejects, with the file and the key path in the message: a duplicated key of an entity or struct, NaN or Infinity, a wrapper key that does not fit the field, a $type that names no union member, an object that no union member reads, an entity with both name and id or a non-string id, and an id: reference.

  • OSError — If file_path cannot be read.

  • ValidationError — If $definition or the version does not fit model_type.

  • pydantic.ValidationError — If the data fails model validation.

import_config_unit

import_config_unit(
    folder_path: str,
    *,
    data_model_type: type[ConfigUnitDataModel] | None = None,
    facade_name: str | None = None,
)

Read a folder of .cfg.json files into a configurable unit facade.

Files are recognized by their $definition, never by file name. Without data_model_type the configurable unit is detected from the definitions the folder holds.

Parameters
Name Type Description

folder_path

str

Path to a folder containing the configurable unit’s configuration files.

data_model_type

type[ConfigUnitDataModel] | None

Optional explicit ConfigUnitDataModel type.

facade_name

str | None

Optional name of the returned facade. Without it the facade is named imported_<registration name>. Give the name when the facade writes it into the configuration, for example into the name of an entity.

Returns

ConfigUnitFacade — Imported configurable unit facade.

Raises:

  • FileNotFoundError — If folder_path does not exist, or a required configuration has no file.

  • ValueError — If folder_path is not a directory or auto-detection fails. Also for each form that import_configuration_file rejects.

  • TypeError — If no registration exists for the resolved model type.

try_import_config_units

try_import_config_units(root_folder_path: str)

Import all configurable units found in immediate subfolders of a root directory.

The counterpart of ExportTool.export_config_units: the result is keyed by subfolder name, and each facade is named after its subfolder, so several units of one type are all kept. A subfolder that cannot be imported is skipped with a warning.

Parameters
Name Type Description

root_folder_path

str

Root directory whose subdirectories each represent one configurable unit.

Returns

dict[str, ConfigUnitFacade] — Mapping from subfolder name to the facade imported from it.

Raises:

  • FileNotFoundError — If root_folder_path does not exist.

  • ValueError — If root_folder_path is not a directory.