FastMapy 0.1.1__tar.gz → 0.2.0__tar.gz

{fastmapy-0.1.1 → fastmapy-0.2.0}/FastMapy.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: FastMapy
-Version: 0.1.1
+Version: 0.2.0
 Summary: Python implementation of the FastMap multidimensional-scaling technique.
 Author-email: Shawn Davis <shawndavis.lomod@gmail.com>
 License-Expression: Apache-2.0
@@ -154,5 +154,18 @@ objects.
 
 FastMapy is licensed under the [Apache License, Version 2.0](LICENSE).
 
+## Model persistence
+
+Save a fitted model and restore it later with the versioned persistence API:
+
+```python
+model.save("jaccard.fastmap")
+restored = fastmap.FastMap.load("jaccard.fastmap")
+embedding = restored.transform(new_strings)
+```
+
+Model files use Python pickle and must only be loaded from trusted sources. Custom distance classes and object
+transformers must be importable module-level objects in the environment that loads the model.
+
 ## References
 <b id="f1">1</b> Proceedings of the 1995 ACM SIGMOD international conference on Management of data  - SIGMOD  ’95. (1995). doi:10.1145/223784 [↩](#a1)

{fastmapy-0.1.1 → fastmapy-0.2.0}/FastMapy.egg-info/SOURCES.txt

@@ -23,5 +23,6 @@ fastmap/distances/_lev.py
 tests/test_distances.py
 tests/test_fastmap.py
 tests/test_metrics.py
+tests/test_persistence.py
 utils/__init__.py
 utils/_tools.py

{fastmapy-0.1.1 → fastmapy-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: FastMapy
-Version: 0.1.1
+Version: 0.2.0
 Summary: Python implementation of the FastMap multidimensional-scaling technique.
 Author-email: Shawn Davis <shawndavis.lomod@gmail.com>
 License-Expression: Apache-2.0
@@ -154,5 +154,18 @@ objects.
 
 FastMapy is licensed under the [Apache License, Version 2.0](LICENSE).
 
+## Model persistence
+
+Save a fitted model and restore it later with the versioned persistence API:
+
+```python
+model.save("jaccard.fastmap")
+restored = fastmap.FastMap.load("jaccard.fastmap")
+embedding = restored.transform(new_strings)
+```
+
+Model files use Python pickle and must only be loaded from trusted sources. Custom distance classes and object
+transformers must be importable module-level objects in the environment that loads the model.
+
 ## References
 <b id="f1">1</b> Proceedings of the 1995 ACM SIGMOD international conference on Management of data  - SIGMOD  ’95. (1995). doi:10.1145/223784 [↩](#a1)

{fastmapy-0.1.1 → fastmapy-0.2.0}/README.md

@@ -117,5 +117,18 @@ objects.
 
 FastMapy is licensed under the [Apache License, Version 2.0](LICENSE).
 
+## Model persistence
+
+Save a fitted model and restore it later with the versioned persistence API:
+
+```python
+model.save("jaccard.fastmap")
+restored = fastmap.FastMap.load("jaccard.fastmap")
+embedding = restored.transform(new_strings)
+```
+
+Model files use Python pickle and must only be loaded from trusted sources. Custom distance classes and object
+transformers must be importable module-level objects in the environment that loads the model.
+
 ## References
 <b id="f1">1</b> Proceedings of the 1995 ACM SIGMOD international conference on Management of data  - SIGMOD  ’95. (1995). doi:10.1145/223784 [↩](#a1)

{fastmapy-0.1.1 → fastmapy-0.2.0}/fastmap/__init__.py

@@ -1,3 +1,3 @@
-__version__ = "0.1.1"
+__version__ = "0.2.0"
 from ._distances import Distance, InputError
 from ._fastmap import FastMap

{fastmapy-0.1.1 → fastmapy-0.2.0}/fastmap/_fastmap.py

@@ -1,8 +1,13 @@
 import multiprocessing
+import os
+import pickle
 import random
 from concurrent.futures import ThreadPoolExecutor as Executor
 from dataclasses import dataclass
 from math import sqrt
+from numbers import Real
+from pathlib import Path
+from tempfile import NamedTemporaryFile
 
 import numpy as np
 
@@ -13,6 +18,10 @@ class ModelError(Exception):
     """Raised when a FastMap model cannot be fitted or used."""
 
 
+_MODEL_FORMAT = "fastmapy.model"
+_MODEL_FORMAT_VERSION = 1
+
+
 @dataclass
 class Pivots:
     left: object
@@ -115,6 +124,113 @@ class FastMap:
         """Dimensions where batch fitting exhausted its distinct-pair retries."""
         return tuple(self._pivot_pair_collisions)
 
+    def save(self, path):
+        """Persist a fitted model to ``path``.
+
+        The model is stored with Python pickle in a versioned FastMapy envelope. Only
+        load files from trusted sources. Custom distance classes and object transformers
+        must be importable module-level objects when the model is loaded.
+        """
+        if len(self._pivots) != self._dim:
+            raise ModelError("Only a fully fitted model can be saved")
+
+        destination = Path(path)
+        if destination.exists() and destination.is_dir():
+            raise IsADirectoryError(f"Model path is a directory: {destination}")
+
+        temporary_path = None
+        try:
+            with NamedTemporaryFile("wb", dir=destination.parent, delete=False) as temporary:
+                temporary_path = Path(temporary.name)
+                pickle.dump(
+                    {
+                        "format": _MODEL_FORMAT,
+                        "format_version": _MODEL_FORMAT_VERSION,
+                        "model": self,
+                    },
+                    temporary,
+                    protocol=pickle.HIGHEST_PROTOCOL,
+                )
+                temporary.flush()
+                os.fsync(temporary.fileno())
+            os.replace(temporary_path, destination)
+        except (OSError, pickle.PickleError, TypeError, AttributeError) as error:
+            raise ModelError(f"Unable to save model to {destination}") from error
+        finally:
+            if temporary_path is not None and temporary_path.exists():
+                temporary_path.unlink()
+        return self
+
+    @classmethod
+    def load(cls, path):
+        """Load a model saved with :meth:`save`.
+
+        Pickle loading can execute code, so ``path`` must refer to a model file from a
+        trusted source. The persisted format version is checked before returning it.
+        """
+        source = Path(path)
+        try:
+            with source.open("rb") as model_file:
+                payload = pickle.load(model_file)
+        except (OSError, EOFError, pickle.UnpicklingError, AttributeError, ImportError) as error:
+            raise ModelError(f"Unable to load model from {source}") from error
+
+        if not isinstance(payload, dict) or payload.get("format") != _MODEL_FORMAT:
+            raise ModelError("File is not a FastMapy model")
+        if payload.get("format_version") != _MODEL_FORMAT_VERSION:
+            raise ModelError("Unsupported FastMapy model format version")
+
+        model = payload.get("model")
+        if not isinstance(model, cls):
+            raise ModelError("Persisted model has an invalid type")
+        cls._validate_loaded_model(model)
+        return model
+
+    @staticmethod
+    def _validate_loaded_model(model):
+        """Reject persisted state that cannot safely support transformation."""
+        if not isinstance(getattr(model, "_dim", None), int) or isinstance(model._dim, bool):
+            raise ModelError("Persisted model has an invalid dimension")
+        if model._dim < 1:
+            raise ModelError("Persisted model has an invalid dimension")
+        if not isinstance(getattr(model, "_iters", None), int) or model._iters < 1:
+            raise ModelError("Persisted model has invalid iteration settings")
+        if not isinstance(getattr(model, "_cores", None), int) or model._cores < 1:
+            raise ModelError("Persisted model has invalid core settings")
+        if not callable(getattr(getattr(model, "_distance", None), "calculate", None)):
+            raise ModelError("Persisted model has an invalid distance metric")
+        transformer = getattr(model, "_obj_transformer", None)
+        if transformer is not None and not callable(transformer):
+            raise ModelError("Persisted model has an invalid object transformer")
+        if not isinstance(getattr(model, "_pivots", None), list):
+            raise ModelError("Persisted model is not fully fitted")
+        if len(model._pivots) != model._dim:
+            raise ModelError("Persisted model is not fully fitted")
+        if not isinstance(getattr(model, "_pivot_pair_collisions", None), list):
+            raise ModelError("Persisted model has invalid collision data")
+
+        for pivot in model._pivots:
+            if not isinstance(pivot, Pivots):
+                raise ModelError("Persisted model has an invalid pivot")
+            if not all(
+                isinstance(index, int) and not isinstance(index, bool) and index >= 0
+                for index in (pivot.left_index, pivot.right_index)
+            ):
+                raise ModelError("Persisted model has invalid pivot indexes")
+            if not isinstance(pivot.distance, Real):
+                raise ModelError("Persisted model has an invalid pivot distance")
+            if not all(
+                isinstance(projection, np.ndarray) and projection.shape == (model._dim,)
+                for projection in (pivot.left_proj, pivot.right_proj)
+            ):
+                raise ModelError("Persisted model has invalid pivot projections")
+
+        if not all(
+            isinstance(index, int) and not isinstance(index, bool) and 0 <= index < model._dim
+            for index in model._pivot_pair_collisions
+        ):
+            raise ModelError("Persisted model has invalid collision data")
+
     def _compute_proj_i(self, index, pivots, obj, obj_proj):
         if pivots.distance == 0:
             return 0.0

{fastmapy-0.1.1 → fastmapy-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "FastMapy"
-version = "0.1.1"
+version = "0.2.0"
 description = "Python implementation of the FastMap multidimensional-scaling technique."
 readme = "README.md"
 requires-python = ">=3.9"

fastmapy-0.2.0/tests/test_persistence.py

@@ -0,0 +1,68 @@
+import pickle
+
+import numpy as np
+import pytest
+
+from fastmap import FastMap
+from fastmap._fastmap import _MODEL_FORMAT, _MODEL_FORMAT_VERSION, ModelError
+from fastmap.distances import L2, Jaccard
+
+
+def test_save_and_load_preserves_a_fitted_model(monkeypatch, tmp_path):
+    vectors = [[0.0, 0.0], [3.0, 4.0], [6.0, 8.0]]
+    monkeypatch.setattr("fastmap._fastmap.random.randrange", lambda count: 0)
+    model = FastMap(dim=1, distance=L2, iters=2).fit(vectors)
+    path = tmp_path / "model.fastmap"
+
+    assert model.save(path) is model
+    loaded = FastMap.load(path)
+
+    assert loaded.dim == model.dim
+    assert loaded.distance == model.distance
+    assert np.allclose(loaded.transform(vectors), model.transform(vectors))
+
+
+def test_save_and_load_preserves_distance_configuration(monkeypatch, tmp_path):
+    strings = ["abcd", "abce", "xyz"]
+    monkeypatch.setattr("fastmap._fastmap.random.randrange", lambda count: 0)
+    model = FastMap(dim=1, distance=Jaccard, dist_args={"shingle_size": 2}).fit(strings)
+    path = tmp_path / "jaccard.fastmap"
+
+    loaded = model.save(path).load(path)
+
+    assert loaded._distance.shingle_size == 2
+    assert np.allclose(loaded.transform(strings), model.transform(strings))
+
+
+def test_save_rejects_an_unfitted_model(tmp_path):
+    with pytest.raises(ModelError, match="fully fitted"):
+        FastMap(dim=1, distance=L2).save(tmp_path / "model.fastmap")
+
+
+def test_load_rejects_non_fastmapy_data(tmp_path):
+    path = tmp_path / "not-a-model.fastmap"
+    with path.open("wb") as model_file:
+        pickle.dump({"format": "something-else"}, model_file)
+
+    with pytest.raises(ModelError, match="not a FastMapy model"):
+        FastMap.load(path)
+
+
+def test_load_rejects_malformed_fitted_model(monkeypatch, tmp_path):
+    vectors = [[0.0, 0.0], [3.0, 4.0], [6.0, 8.0]]
+    monkeypatch.setattr("fastmap._fastmap.random.randrange", lambda count: 0)
+    model = FastMap(dim=1, distance=L2, iters=2).fit(vectors)
+    model._pivots[0] = object()
+    path = tmp_path / "malformed.fastmap"
+    with path.open("wb") as model_file:
+        pickle.dump(
+            {
+                "format": _MODEL_FORMAT,
+                "format_version": _MODEL_FORMAT_VERSION,
+                "model": model,
+            },
+            model_file,
+        )
+
+    with pytest.raises(ModelError, match="invalid pivot"):
+        FastMap.load(path)