Merge branch 'feature-save-load' of github.com:IFCA-Advanced-Computing/frouros

Author: jaime-cespedes-sisniega

docs/source/api_reference/utils.md

@@ -8,5 +8,6 @@ The {mod}`frouros.utils` module contains auxiliary classes, functions or excepti
 utils/checks
 utils/data_structures
 utils/kernels
+utils/persistence
 utils/stats
 ```

docs/source/api_reference/utils/persistence.md

@@ -0,0 +1,9 @@
+# Persistence
+
+The {mod}`frouros.utils.persistence` module contains auxiliary functions to persistence objects.
+
+```{eval-rst}
+.. automodule:: frouros.utils.persistence
+    :members:
+    :no-inherited-members:
+```

docs/source/examples.md

@@ -5,4 +5,5 @@
 
 examples/concept_drift
 examples/data_drift
+examples/utils
 ```

docs/source/examples/utils.md

@@ -0,0 +1,7 @@
+# Utils
+
+```{toctree}
+:maxdepth: 1
+
+utils/save_load
+```

docs/source/faq.md

@@ -83,3 +83,10 @@ including guidelines for reporting issues, submitting feature requests, and cont
 
 Frouros does not currently provide built-in visualization tools for drift detection results, but it is planned to 
 include them in future releases.
+
+## How can I persist a detector or callback for later use?
+
+Frouros provides a [persistence module](./api_reference/utils/persistence.html) that allows you to persist a detector 
+or callback for later use. It offers [save](api_reference/utils/persistence.html#frouros.utils.persistence.save) and 
+[load](api_reference/utils/persistence.html#frouros.utils.persistence.load) methods to save and load the detector or 
+callback to and from disk, respectively.

frouros/tests/unit/utils/test_persistence.py

@@ -0,0 +1,120 @@
+"""Test persistence module."""
+
+import pickle
+
+import pytest  # type: ignore
+
+from frouros.callbacks import HistoryConceptDrift, PermutationTestDistanceBased
+from frouros.callbacks.base import BaseCallback
+from frouros.detectors.base import BaseDetector
+from frouros.detectors.concept_drift import DDM, DDMConfig
+from frouros.detectors.data_drift import MMD
+from frouros.utils import load, save
+
+
+@pytest.fixture(
+    scope="module",
+    params=[
+        DDM(
+            config=DDMConfig(),
+        ),
+        MMD(),
+    ],
+)
+def detector(
+    request: pytest.FixtureRequest,
+) -> BaseDetector:
+    """Fixture for detector.
+
+    :param request: Request
+    :type request: pytest.FixtureRequest
+    :return: Detector
+    :rtype: BaseDetector
+    """
+    return request.param
+
+
+@pytest.fixture(
+    scope="module",
+    params=[
+        HistoryConceptDrift(),
+        PermutationTestDistanceBased(
+            num_permutations=2,
+        ),
+    ],
+)
+def callback(
+    request: pytest.FixtureRequest,
+) -> BaseCallback:
+    """Fixture for callback.
+
+    :param request: Request
+    :type request: pytest.FixtureRequest
+    :return: Callback
+    :rtype: BaseCallback
+    """
+    return request.param
+
+
+def test_save_load_with_valid_detector(
+    detector: BaseDetector,
+) -> None:
+    """Test save and load with valid detector.
+
+    :param detector: Detector
+    :type detector: BaseDetector
+    """
+    filename = "/tmp/detector.pkl"
+    save(detector, filename)
+    loaded_detector = load(filename)
+    assert isinstance(loaded_detector, detector.__class__)
+
+
+def test_save_load_with_valid_callback(
+    callback: BaseCallback,
+) -> None:
+    """Test save and load with valid callback.
+
+    :param callback: Callback
+    :type callback: BaseCallback
+    """
+    filename = "/tmp/callback.pkl"
+    save(callback, filename)
+    loaded_callback = load(filename)
+    assert isinstance(loaded_callback, BaseCallback)
+
+
+def test_save_with_invalid_object() -> None:
+    """Test save with invalid object.
+
+    :raises TypeError: Type error exception
+    """
+    invalid_object = "invalid"
+    filename = "/tmp/invalid.pkl"
+    with pytest.raises(TypeError):
+        save(invalid_object, filename)
+
+
+def test_save_with_invalid_protocol(
+    detector: BaseDetector,
+) -> None:
+    """Test save with invalid protocol.
+
+    :param detector: Detector
+    :type detector: BaseDetector
+    :raises ValueError: Value error exception
+    """
+    filename = "/tmp/detector.pkl"
+    invalid_protocol = pickle.HIGHEST_PROTOCOL + 1
+    with pytest.raises(ValueError):
+        save(detector, filename, invalid_protocol)
+
+
+def test_load_with_non_existent_file() -> None:
+    """Test load with non-existent file.
+
+    :raises FileNotFoundError: File not found error exception
+    """
+    filename = "/tmp/non_existent.pkl"
+    with pytest.raises(FileNotFoundError):
+        load(filename)

frouros/utils/__init__.py

@@ -1 +1,8 @@
 """Utils init."""
+
+from .persistence import load, save
+
+__all__ = [
+    "load",
+    "save",
+]

frouros/utils/persistence.py

@@ -0,0 +1,66 @@
+"""Persistence module."""
+
+import pickle
+
+from frouros.callbacks.base import BaseCallback
+from frouros.detectors.base import BaseDetector
+from frouros.utils.logger import logger
+
+DEFAULT_PROTOCOL = pickle.DEFAULT_PROTOCOL
+
+
+def load(
+    filename: str,
+) -> object:
+    """Load object from file.
+
+    :param filename: Filename
+    :type filename: str
+    :return: Loaded object
+    :rtype: object
+    """
+    try:
+        with open(filename, "rb") as file:
+            obj = pickle.load(
+                file,
+            )
+        return obj
+    except (IOError, pickle.UnpicklingError) as e:
+        logger.error("Error occurred while loading object: %s", e)
+        raise e
+
+
+def save(
+    obj: object,
+    filename: str,
+    pickle_protocol: int = DEFAULT_PROTOCOL,
+) -> None:
+    """Save object to file.
+
+    :param obj: Object to save
+    :type obj: object
+    :param filename: Filename
+    :type filename: str
+    :param pickle_protocol: Pickle protocol, defaults to DEFAULT_PROTOCOL
+    :type pickle_protocol: int, optional
+    """
+    try:
+        if not isinstance(obj, (BaseDetector, BaseCallback)):
+            raise TypeError(
+                f"Object of type {type(obj)} is not serializable. "
+                f"Must be an instance that inherits from BaseDetector or BaseCallback."
+            )
+        if pickle_protocol not in range(pickle.HIGHEST_PROTOCOL + 1):
+            raise ValueError(
+                f"Invalid pickle_protocol value. "
+                f"Must be in range 0..{pickle.HIGHEST_PROTOCOL}."
+            )
+        with open(filename, "wb") as file:
+            pickle.dump(
+                obj,
+                file,
+                protocol=pickle_protocol,
+            )
+    except (IOError, pickle.PicklingError) as e:
+        logger.error("Error occurred while saving object: %s", e)
+        raise e