ExportTool

The export entry point: writes configurable units as folders and single configurations as files.

Every export checks the model before it writes a file. If the check fails, nothing is written and one fsp_config_foundation.error.ValidationError lists every finding. The check covers the constraints of each configuration and its references; it does not run fsp_config_foundation.validation.ValidationTool or domain validation rules.

Member Functions:

export_configuration_file

export_configuration_file(config: ConfigurationSchema, output_path: str)

Write one configuration to a .cfg.json file.

This is the file counterpart of export_config_unit, for converters and standalone configurations that do not belong to a configurable unit.

Only this configuration is checked. A reference whose path starts with another definition is written as it is, also when that definition belongs to the same configurable unit. A reference that is not found in this configuration is written as it is too, since it can point into another file of a MultipleFiles definition. Export the whole unit with export_config_unit to check them.

Parameters
Name Type Description

config

ConfigurationSchema

The configuration instance to write.

output_path

str

Target file, or a folder in which the file is named after the configuration class (for example MyRuntime.cfg.json). A path without suffix counts as a folder.

Returns

ExportedFiles — A one-entry mapping of the written file stem to its JSON content.

Raises:

  • ValueError — If output_path is empty.

  • ValidationError — If the configuration is invalid. Nothing is written.

  • RuntimeError — If writing the file fails.

export_config_unit

export_config_unit(
    facade: ConfigUnitFacade,
    output_path: str,
    *,
    file_names: Mapping[type[ConfigurationSchema], str] | None = None,
    hook: Callable[[Any], None] | None = None,
)

Write a configurable unit facade as one .cfg.json file per configuration into a folder.

The steps run in this order: ConfigUnitFacade.prepare_export, then facade.data, then hook, then the check, then the write. The check follows both hooks, so what they change is checked too. References between the configurations of the unit are checked; a reference into a definition outside the unit is written as it is, since only runtime can check it.

Parameters
Name Type Description

facade

ConfigUnitFacade

The configurable unit facade to export.

output_path

str

Folder the files are written to.

file_names

Mapping[type[ConfigurationSchema], str] | None

Optional file path, relative to output_path, for each configuration class whose file must not follow the naming convention, such as a path a build system expects. The path must stay inside output_path. fsp_config_foundation.import_tool.ImportTool reads only the files directly in a folder, so it does not read back a file in a subfolder.

hook

Callable[[Any], None] | None

Optional adjustment for what the facade does not cover. It receives the live model, so its changes stay after the export, also when the export is refused.

Returns

ExportedFiles — A mapping of written file stems to their JSON content. For a file placed by file_names, the key is that path without .cfg.json. A path that does not end in .cfg.json is the key as it is.

Raises:

  • ValueError — If output_path is empty, or file_names names a configuration class the unit does not hold exactly once, gives a path that is not inside output_path, or gives two files the same path. The comparison ignores case. Nothing is written.

  • ValidationError — If the model is invalid. Nothing is written.

  • RuntimeError — If creating the folder or writing a file fails.

export_config_units

export_config_units(config_units: list[ConfigUnitFacade], root_output_folder: str)

Export several configurable units into subfolders of root_output_folder.

Each unit is checked before its own files are written, so a refused unit stops the batch after the units before it have been written.

Parameters
Name Type Description

config_units

list[ConfigUnitFacade]

Facades to export.

root_output_folder

str

Root folder in which one subfolder per facade is created.

Returns

BatchExportResult — A mapping from subfolder name to that unit’s exported files.

Raises:

  • ValueError — If root_output_folder is empty or is not a directory.

  • ValidationError — If a unit is invalid. Nothing of that unit or of the units after it is written.

  • RuntimeError — If creating a folder or writing a file fails.