spectrochempy.migrate_legacy_file

migrate_legacy_file(source, destination=None, *, allow_unsafe_legacy=False, overwrite=False, verbose=False)[source]

Migrate a legacy SCP/PSCP file to the safe raw-base64 format.

Legacy SCP/PSCP files produced before SpectroChemPy 0.8 may contain pickle-based array payloads. Loading such files with the default allow_unsafe_legacy=False raises an error. This function converts the file to the current safe format (raw-base64).

Warning

Migration does execute pickle.loads on the legacy payload to reconstruct the in-memory object. Only migrate files whose provenance you fully trust. Set allow_unsafe_legacy=True to acknowledge this risk explicitly.

The migrated file is a proper SCP/ZIP archive and can be loaded with the default allow_unsafe_legacy=False. The source file is never modified or deleted.

Writes are atomic: the destination is only replaced after the migrated file has been written, verified as loadable with safe defaults, and then moved into place via os.replace().

Parameters:

  • source (str or pathlib.Path) – Path to the .scp or .pscp file to migrate.

  • destination (str or pathlib.Path, optional) – Path for the migrated output file. When None, a _migrated suffix is inserted before the extension in the source path.

  • allow_unsafe_legacy (bool, default False) – Required to be ``True``. Acknowledges that the source file will be deserialised via pickle.loads during migration. Set this to True only when the source file comes from a known and trusted origin.

  • overwrite (bool, default False) – Allow overwriting an existing destination file. When False and the destination already exists, a FileExistsError is raised.

  • verbose (bool, default False) – Print a summary of the migration to stdout.

Returns:

pathlib.Path – Path of the migrated file.

Raises:

  • FileNotFoundError – If source does not exist.

  • ValueError – If source does not have a .scp or .pscp extension, if source and destination resolve to the same path, or if the destination suffix does not match the source suffix.

  • FileExistsError – If the destination already exists and overwrite is False.

  • spectrochempy.utils.exceptions.SpectroChemPyError – If allow_unsafe_legacy is False, if the source is already in safe format, or if the migration fails for any other reason.

See also

spectrochempy.load

Load an SCP/PSCP file.

spectrochempy.NDDataset.save

Save an NDDataset to SCP format.

spectrochempy.Project.save

Save a Project to PSCP format.

Examples

>>> from spectrochempy import migrate_legacy_file
>>> # migrate a single file (requires trust acknowledgement)
>>> migrated = migrate_legacy_file("old_data.scp",
...                                allow_unsafe_legacy=True)
>>> # migrate to a specific path
>>> migrated = migrate_legacy_file("old_data.scp", "new_data.scp",
...                                allow_unsafe_legacy=True,
...                                overwrite=True)