hyrax.config_migrations.migration_utils

hyrax.config_migrations.migration_utils#

Migration engine, helpers, and registry for versioned config migrations.

Attributes#

logger

MIGRATIONS

Classes#

MigrationStep

A single schema migration with optional key-rename metadata.

Functions#

migration_step(from_version[, key_renames])

Decorator that registers a migration function into MIGRATIONS.

rename_table(→ bool)

Rename a top-level table from old to new.

move_key(→ bool)

Move a nested key from old_path to new_path.

_build_deprecated_key_map(→ dict[str, str])

migrate_config(→ tomlkit.toml_document.TOMLDocument)

Upgrade a user config document to the current schema version.

Module Contents#

logger[source]#
MIGRATIONS: dict[int, MigrationStep][source]#
class MigrationStep[source]#

A single schema migration with optional key-rename metadata.

Parameters:

  • func (Callable[[TOMLDocument], TOMLDocument]) – The function that upgrades a config document by one version.

  • key_renames (dict[str, str]) – Old dotted path -> new dotted path for every key renamed by this migration. Used by ConfigManager.set_config to warn callers who still reference the old names at runtime.

func: collections.abc.Callable[[tomlkit.toml_document.TOMLDocument], tomlkit.toml_document.TOMLDocument][source]#
key_renames: dict[str, str][source]#
migration_step(from_version: int, key_renames: dict[str, str] | None = None)[source]#

Decorator that registers a migration function into MIGRATIONS.

Parameters:

  • from_version (int) – The config schema version this function upgrades FROM. The target version is implicitly from_version + 1.

  • key_renames (dict[str, str], optional) – Old dotted path -> new dotted path for every key renamed by this migration.

rename_table(cfg: tomlkit.toml_document.TOMLDocument | dict, old: str, new: str) → bool[source]#

Rename a top-level table from old to new.

If only old exists it is moved. If both exist, cfg[new] wins on leaf collisions; the two are deep-merged via ConfigManager.merge_configs and old is removed. If neither exists this is a no-op.

Parameters:

  • cfg (TOMLDocument or dict) – The user config document to mutate in place.

  • old (str) – The table name that is being retired.

  • new (str) – The new table name to adopt.

Returns:

True iff old was present and something was renamed (so the caller can emit a deprecation warning conditionally).

Return type:

bool

move_key(cfg: tomlkit.toml_document.TOMLDocument | dict, old_path: str, new_path: str) → bool[source]#

Move a nested key from old_path to new_path.

Paths are dotted strings parsed by hyrax.config_utils.parse_dotted_key(), so quoted segments like "'torch.optim.Adam'.lr" are supported.

Parameters:

  • cfg (TOMLDocument or dict) – The user config document to mutate in place.

  • old_path (str) – The dotted path to the existing key.

  • new_path (str) – The dotted path to write the value to. Intermediate tables are created as needed.

Returns:

True iff old_path was present and the value was moved.

Return type:

bool

_build_deprecated_key_map() → dict[str, str][source]#
migrate_config(user_config: tomlkit.toml_document.TOMLDocument, *, _migrations: dict[int, MigrationStep] | None = None, _target_version: int | None = None) → tomlkit.toml_document.TOMLDocument[source]#

Upgrade a user config document to the current schema version.

The document is mutated in place (and also returned for convenience). If config_version is absent it is assumed to be 1 — older configs predate the versioning field. If it is greater than the current schema version, a RuntimeError is raised because the installed Hyrax does not know how to read the schema.

Parameters:

  • user_config (TOMLDocument) – The parsed user config. An empty document (the “no user config” case) is returned unchanged.

  • _migrations (dict[int, MigrationStep], optional) – Override the global MIGRATIONS registry (testing only).

  • _target_version (int, optional) – Override the auto-derived target version (testing only).

Returns:

The upgraded document with config_version stamped to the current value.

Return type:

TOMLDocument

Raises:

RuntimeError – If user_config declares a version newer than this Hyrax can understand, or if a migration step is missing from MIGRATIONS.