pcntoolkit.util.migration#
The saved model JSON file can change structure across PCNtoolkit versions as new features are added. This module is one central place to register and apply migrations required to load these changed models files.
This module does two things: 1. It updates older saved models during loading.
2. It warns if a model was created with a newer PCNtoolkit version than the one currently installed by the user.
In simple: version_model < version_pcntoolkit → APPLY MIGRATIONS version_model = version_pcntoolkit → DO NOTHING version_model > version_pcntoolkit → WARN USER
Attributes#
Classes#
Registers and applies model migration functions. |
Functions#
|
Warn if a model was created with a newer PCNtoolkit version. |
Module Contents#
- class MigrationRegistry#
Registers and applies model migration functions.
Migration functions update older saved model dictionaries to the format expected by the current PCNtoolkit version.
Migrations are applied automatically in version order when a model is loaded.
- _migrations#
Maps component name -> sorted list of (introduced_in_version, migration_fn) tuples.
- Type:
dict[ComponentName,list[tuple[Version,Callable]]]
- migrate(component: ComponentName, d: dict, version: str | None = None) dict#
Apply all migrations specified in self._migrations when loading models saved with previous PCNtoolkit versions.
Called by from_dict() methods that exist in the components being migrated (e.g. BasisFunction.from_dict()).
- Parameters:
component (
ComponentName) – Name of the component (must match what was used in register()).d (
dict) – The raw dict read from a saved JSON file.version (
str | None, optional) – Explicit version override. If no version is exists in the JSON file, it defaults to 0.0.0
- Returns:
The dict, updated to the format expected by the current PCNtoolkit version.
- Return type:
- register(component: ComponentName, introduced_in: str) Callable[[Callable[[dict], dict]], Callable[[dict], dict]]#
Decorator used to register a migration function for a component.
When a function is decorated with @registry.register(…), it is automatically added to self._migrations.
- Parameters:
component (
ComponentName) – Name of the component being migrated (e.g. “BLR”, “BasisFunction”, “Scaler”).introduced_in (
str) – The PCNtoolkit version in which the new format was introduced.
- Returns:
The migration function.
- Return type:
Callable
- check_forward_compatibility(saved_version: str, current_version: str) None#
Warn if a model was created with a newer PCNtoolkit version.
Newer model files may contain features or formats that are not supported by the older installed version.
- ComponentName#
- registry: MigrationRegistry#