pcntoolkit.util.migration
=========================

.. py:module:: pcntoolkit.util.migration

.. autoapi-nested-parse::

   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
----------

.. autoapisummary::

   pcntoolkit.util.migration.ComponentName
   pcntoolkit.util.migration.registry


Classes
-------

.. autoapisummary::

   pcntoolkit.util.migration.MigrationRegistry


Functions
---------

.. autoapisummary::

   pcntoolkit.util.migration.check_forward_compatibility


Module Contents
---------------

.. py: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.

   .. attribute:: _migrations

      Maps component name -> sorted list of
      (introduced_in_version, migration_fn) tuples.

      :type: :py:class:`dict[ComponentName`, :py:class:`list[tuple[Version`, :py:class:`Callable]]]`


   .. py:method:: 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()).

      :param component: Name of the component (must match what was used in
                        register()).
      :type component: :py:class:`ComponentName`
      :param d: The raw dict read from a saved JSON file.
      :type d: :py:class:`dict`
      :param version: Explicit version override. If no version is exists in the JSON
                      file, it defaults to 0.0.0
      :type version: :py:class:`str | None`, *optional*

      :returns: The dict, updated to the format expected by the current
                PCNtoolkit version.
      :rtype: :py:class:`dict`



   .. py:method:: 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.

      :param component: Name of the component being migrated
                        (e.g. "BLR", "BasisFunction", "Scaler").
      :type component: :py:class:`ComponentName`
      :param introduced_in: The PCNtoolkit version in which the new format was
                            introduced.
      :type introduced_in: :py:class:`str`

      :returns: The migration function.
      :rtype: :py:class:`Callable`



.. py:function:: 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.

   :param saved_version: The ptk_version string stored in the model file.
   :type saved_version: :py:class:`str`
   :param current_version: The version of the currently installed pcntoolkit package.
   :type current_version: :py:class:`str`

   :rtype: :py:obj:`None`


.. py:data:: ComponentName

.. py:data:: registry
   :type:  MigrationRegistry