mafw.steering.builder

Editable steering configuration builder independent from the execution engine.

Author:

Bulgheroni Antonio

Description:

Provides helpers to construct steering metadata without running processors.

Classes

SteeringBuilder()	Editable domain model for building MAFw steering files.
ValidationLevel(*values)	Validation tiers that can be requested from the steering builder.

class mafw.steering.builder.SteeringBuilder

Bases: object

Editable domain model for building MAFw steering files.

classmethod from_toml(path: Path | str) → SteeringBuilder

Create a builder from an existing steering file while keeping TOML metadata.

classmethod from_toml_text(text: str) → SteeringBuilder

Create a builder from TOML text while keeping TOML metadata.

_parse_storage_configuration(value: Any) → None

Parse a storage table while retaining malformed values for validation.

add_group(name: str, processors: Iterable[str], description: str | None = None) → None

Register a processor group.

add_processor(base_name: str, replica: str | None = None) → None

Add a processor reference to the global processors_to_run list.

add_replica(base_name: str, replica: str) → None

Create a replica entry without touching the base configuration.

add_storage_volume(name: str, *, root: str, access: StorageAccess | str = StorageAccess.FULL, type: VolumeStorageType | str = VolumeStorageType.FILESYSTEM, parameters: Mapping[str, Mapping[str, Any]] | None = None, attributes: Mapping[str, Any] | None = None) → StorageVolumeConfiguration

Add a named storage volume to the optional global configuration.

Parameters:

• name – Stable logical name of the volume; : is reserved for the logical file-reference separator.

• root – Literal filesystem root expression.

• access – Access policy, defaulting to full.

• type – Backend type, defaulting to filesystem.

• parameters – Backend-specific values grouped by backend name.

• attributes – Additional volume-level TOML values to preserve.

Returns:

The newly created volume configuration.

Raises:

• ValueError – If the name is empty or contains :.

• KeyError – If the volume name is already present.

Added in version 2.4.

clear_parameters(processor_full_name: str) → None

Clear every parameter override for a processor.

disable_db_configuration() → None

Prevent the DBConfiguration section from being emitted.

disable_storage_configuration() → None

Disable the StorageConfiguration section while retaining its values.

Added in version 2.4.

enable_db_configuration() → None

Ensure the DBConfiguration section will be serialized.

enable_storage_configuration() → None

Enable the StorageConfiguration section for serialization.

Added in version 2.4.

ensure_processor_section(base_name: str) → None

Create an empty processor section without adding it to the run list.

get_group(name: str) → GroupConfig

Return the stored configuration for a group section.

get_processor_config(full_name: str) → ProcessorConfig

Return the stored configuration for a processor or replica.

get_storage_volume(name: str) → StorageVolumeConfiguration

Return the named storage volume.

Parameters:

name – Configured volume name.

Returns:

The mutable volume configuration.

Added in version 2.4.

is_db_configuration_enabled() → bool

Return whether the DBConfiguration section should be present.

is_storage_configuration_enabled() → bool

Return whether the StorageConfiguration section will be serialized.

Added in version 2.4.

list_groups() → list[str]

Return every group section name currently configured.

list_processors() → list[str]

Return every processor section name currently configured.

remove_filter(processor_full_name: str, model_name: str) → None

Remove a filter model definition.

remove_group(name: str) → None

Delete a group by name.

remove_parameter(processor_full_name: str, key: str) → None

Remove a processor parameter override if present.

remove_processor(full_name: str) → None

Remove a processor or replica from the run list.

remove_storage_volume(name: str) → None

Remove a named volume and omit the section when it becomes empty.

Parameters:

name – Configured volume name.

Added in version 2.4.

remove_storage_volume_parameter(name: str, backend: str, key: str) → None

Remove one backend-specific parameter from a named volume.

Parameters:

• name – Configured volume name.

• backend – Backend subsection key.

• key – Backend parameter name.

Added in version 2.4.

set_analysis_description(description: str | None) → None

Set analysis_description.

set_analysis_name(name: str | None) → None

Set analysis_name.

set_create_standard_tables(value: bool | None) → None

Set create_standard_tables.

set_db_attribute(key: str, value: Any | None) → None

Store a generic key/value pair inside DBConfiguration.

set_db_authentication(authentication: Mapping[str, Any] | None) → None

Set the database authentication mapping.

set_db_parameters(parameters: Mapping[str, Mapping[str, Any]] | None) → None

Set the backend-specific database parameters mapping.

set_db_pragmas(pragmas: dict[str, Any]) → None

Set database pragmas.

set_db_url(url: str | None) → None

Override the database URL.

set_default() → None

Initialize globals, database, and UI defaults for a fresh builder.

set_env_files(paths: Iterable[str]) → None

Replace the literal dotenv path list in steering globals.

set_filter_conditionals(processor_full_name: str, model_name: str, conditionals: list[dict[str, Any]] | None) → None

Assign __conditional__ blocks to a filter model.

set_filter_config(processor_full_name: str, model_name: str, config: dict[str, Any]) → None

Replace the configuration for a given filter model.

set_filter_field(processor_full_name: str, model_name: str, field: str, value: Any) → None

Set or update a single field within a filter model.

set_filter_logic(processor_full_name: str, logic: str | None) → None

Set the global __logic__ string for the processor filters.

set_migration_directory(directory: str | None) → None

Set the schema-migration directory in the database configuration.

Added in version 2.4.

Parameters:

directory (str | None) – The migration directory value, or None to remove it.

set_new_only(value: bool | None) → None

Set the top-level new_only flag.

set_parameter(processor_full_name: str, key: str, value: Any) → None

Set a processor parameter.

set_processor_documentation(processor_full_name: str, description: str | None, parameter_help: Mapping[str, str | None] | None = None) → None

Store processor and parameter documentation used for generated TOML comments.

set_processor_filters(processor_full_name: str, filters: dict[str, list[FilterConfig]], logic: str | None) → None

Update the filters and logic for a given processor.

set_processor_new_only(processor_full_name: str, new_only: bool | None) → None

Explicitly set __new_only__ for a processor or replica.

set_processors_to_run(processors: Iterable[str]) → None

Overwrite the processors_to_run list.

set_replica_inheritance(replica_full_name: str, inheritance: bool | None) → None

Toggle the inheritance behaviour for a replica.

set_storage_volume_parameter(name: str, backend: str, key: str, value: Any) → None

Set one backend-specific parameter on a named volume.

Parameters:

• name – Configured volume name.

• backend – Backend subsection key, such as filesystem.

• key – Backend parameter name.

• value – TOML-compatible parameter value.

Added in version 2.4.

set_ui_interface(interface: str) → None

Pick the interface used by UserInterface.

to_config_dict() → dict[str, Any]

Return a plain dictionary representing the steering configuration.

to_document(*, validation_level: ValidationLevel | None = None) → TOMLDocument

Serialize the builder state into a TOML document.

update_storage_volume(name: str, *, root: str | None = None, access: StorageAccess | str | None = None, type: VolumeStorageType | str | None = None, parameters: Mapping[str, Mapping[str, Any]] | None = None, attributes: Mapping[str, Any] | None = None) → StorageVolumeConfiguration

Update selected properties of a named storage volume.

None means leave a property unchanged; pass an empty mapping to clear backend parameters or extra attributes.

Parameters:

• name – Configured volume name.

• root – Replacement literal root expression, if supplied.

• access – Replacement access policy, if supplied.

• type – Replacement backend type, if supplied.

• parameters – Replacement backend parameter mapping, if supplied.

• attributes – Replacement extra volume values, if supplied.

Returns:

The updated mutable volume configuration.

Added in version 2.4.

validate(validation_level: ValidationLevel = ValidationLevel.SEMANTIC) → list[ValidationIssue]

Run steering validation at the requested level and report every issue.

write(path: Path | str, *, validation_level: ValidationLevel | None = None) → None

Dump the builder to disk.

property document: TOMLDocument | None

Return the parsed TOML document this builder originated from.

property extra_globals: dict[str, Any]

Return extra top-level globals preserved from the steering file.

class mafw.steering.builder.ValidationLevel(*values)

Bases: Enum

Validation tiers that can be requested from the steering builder.