hyrax.config_migrations

hyrax.config_migrations#

Versioned migrations for Hyrax user configuration files.

Hyrax tags its config schema with a top-level config_version scalar in hyrax_default_config.toml. When a user loads an older config, the migrations registered here run before the merge step in hyrax.config_utils.ConfigManager, bringing the user’s document forward one version at a time until it matches CURRENT_CONFIG_VERSION.

Each migration step lives in its own descriptively-named module (e.g. 001_rename_model_inputs_to_data_request.py) and self-registers via the migration_step() decorator, which populates the MIGRATIONS dict. CURRENT_CONFIG_VERSION is auto-derived from the highest registered migration — developers do not bump it manually.

Adding a new migration:

  1. Create src/hyrax/config_migrations/migrations/00N_description.py (e.g. 002_move_learning_rate.py). Decorate the migration function with @migration_step(from_version=N, key_renames={...}). Import the decorator and helpers from hyrax.config_migrations.migration_utils. The module is auto-discovered — no import line needed elsewhere. CURRENT_CONFIG_VERSION and config_version in the default TOML are both stamped automatically at runtime.

  2. Add a unit test in tests/hyrax/test_config_migrations.py.

Submodules#

Attributes#

MIGRATIONS

CURRENT_CONFIG_VERSION

DEPRECATED_KEY_NAMES

Classes#

MigrationStep

A single schema migration with optional key-rename metadata.

Functions#

migrate_config(→ tomlkit.toml_document.TOMLDocument)

Upgrade a user config document to the current schema version.

migration_step(from_version[, key_renames])

Decorator that registers a migration function into MIGRATIONS.

move_key(→ bool)

Move a nested key from old_path to new_path.

rename_table(→ bool)

Rename a top-level table from old to new.

Package Contents#

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]#
key_renames: dict[str, str]#
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.

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.

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

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

CURRENT_CONFIG_VERSION: int = 1[source]#
DEPRECATED_KEY_NAMES: dict[str, str][source]#