hyrax.config_migrations.migration_utils ======================================= .. py:module:: hyrax.config_migrations.migration_utils .. autoapi-nested-parse:: Migration engine, helpers, and registry for versioned config migrations. Attributes ---------- .. autoapisummary:: hyrax.config_migrations.migration_utils.logger hyrax.config_migrations.migration_utils.MIGRATIONS Classes ------- .. autoapisummary:: hyrax.config_migrations.migration_utils.MigrationStep Functions --------- .. autoapisummary:: hyrax.config_migrations.migration_utils.migration_step hyrax.config_migrations.migration_utils.rename_table hyrax.config_migrations.migration_utils.move_key hyrax.config_migrations.migration_utils._build_deprecated_key_map hyrax.config_migrations.migration_utils.migrate_config Module Contents --------------- .. py:data:: logger .. py:data:: MIGRATIONS :type: dict[int, MigrationStep] .. py:class:: MigrationStep A single schema migration with optional key-rename metadata. :param func: The function that upgrades a config document by one version. :type func: Callable[[TOMLDocument], TOMLDocument] :param key_renames: 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. :type key_renames: dict[str, str] .. py:attribute:: func :type: collections.abc.Callable[[tomlkit.toml_document.TOMLDocument], tomlkit.toml_document.TOMLDocument] .. py:attribute:: key_renames :type: dict[str, str] .. py:function:: migration_step(from_version: int, key_renames: dict[str, str] | None = None) Decorator that registers a migration function into :data:`MIGRATIONS`. :param from_version: The config schema version this function upgrades FROM. The target version is implicitly ``from_version + 1``. :type from_version: int :param key_renames: Old dotted path -> new dotted path for every key renamed by this migration. :type key_renames: dict[str, str], optional .. py:function:: rename_table(cfg: tomlkit.toml_document.TOMLDocument | dict, old: str, new: str) -> bool 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. :param cfg: The user config document to mutate in place. :type cfg: TOMLDocument or dict :param old: The table name that is being retired. :type old: str :param new: The new table name to adopt. :type new: str :returns: ``True`` iff ``old`` was present and something was renamed (so the caller can emit a deprecation warning conditionally). :rtype: bool .. py:function:: move_key(cfg: tomlkit.toml_document.TOMLDocument | dict, old_path: str, new_path: str) -> bool Move a nested key from ``old_path`` to ``new_path``. Paths are dotted strings parsed by :func:`hyrax.config_utils.parse_dotted_key`, so quoted segments like ``"'torch.optim.Adam'.lr"`` are supported. :param cfg: The user config document to mutate in place. :type cfg: TOMLDocument or dict :param old_path: The dotted path to the existing key. :type old_path: str :param new_path: The dotted path to write the value to. Intermediate tables are created as needed. :type new_path: str :returns: ``True`` iff ``old_path`` was present and the value was moved. :rtype: bool .. py:function:: _build_deprecated_key_map() -> dict[str, str] .. py:function:: migrate_config(user_config: tomlkit.toml_document.TOMLDocument, *, _migrations: dict[int, MigrationStep] | None = None, _target_version: int | None = None) -> tomlkit.toml_document.TOMLDocument 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 :class:`RuntimeError` is raised because the installed Hyrax does not know how to read the schema. :param user_config: The parsed user config. An empty document (the "no user config" case) is returned unchanged. :type user_config: TOMLDocument :param _migrations: Override the global :data:`MIGRATIONS` registry (testing only). :type _migrations: dict[int, MigrationStep], optional :param _target_version: Override the auto-derived target version (testing only). :type _target_version: int, optional :returns: The upgraded document with ``config_version`` stamped to the current value. :rtype: TOMLDocument :raises RuntimeError: If ``user_config`` declares a version newer than this Hyrax can understand, or if a migration step is missing from :data:`MIGRATIONS`.