feat(project): Add parameter to Project.clear to delete project (#1322)

`project.clear(delete_project=True)` now deletes the entire project,
while `project.clear(delete_project=False)` (the default) removes every
item from the project.

Closes #1294

Author: auguste-probabl

skore/src/skore/project/project.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+import functools
+import shutil
 from collections.abc import Iterator
 from logging import INFO, NullHandler, getLogger
 from pathlib import Path
@@ -16,6 +18,30 @@
 logger.setLevel(INFO)
 
 
+class ProjectDeletedError(Exception):
+    """A method of a Project was called but the Project is marked as deleted."""
+
+
+def _raise_if_deleted(method):
+    """Raise if the underlying Project has been deleted, otherwise execute `method`.
+
+    This wrapper makes it safe to "delete" a Project, even if the Project instance
+    still exists.
+    """
+
+    @functools.wraps(method)
+    def wrapper(self, *args, **kwargs):
+        if self._storage_initialized is not True:
+            raise ProjectDeletedError(
+                "This Project instance is marked as deleted. "
+                "Please re-create a Project and discard the current one."
+            )
+
+        return method(self, *args, **kwargs)
+
+    return wrapper
+
+
 class Project:
     """
     A collection of items persisted in a storage.
@@ -95,16 +121,38 @@ def __init__(
         # Initialize repositories with dedicated storages
         self._item_repository = ItemRepository(DiskCacheStorage(item_storage_dirpath))
 
+        self._storage_initialized = True
+
         # Check if the project should rejoin a server
         from skore.project._launch import ServerInfo  # avoid circular import
 
         self._server_info = ServerInfo.rejoin(self)
 
-    def clear(self):
-        """Clear the project."""
+    @_raise_if_deleted
+    def clear(self, delete_project=False):
+        """Remove all items from the project.
+
+        .. warning::
+           Clearing the project with `delete_project=True` will invalidate the whole
+           `Project` instance, making it unusable.
+           A new Project instance can be created using the :class:`skore.Project`
+           constructor or the :func:`skore.open` function.
+
+        Parameters
+        ----------
+        delete_project : bool
+            If set, the project will be deleted entirely.
+        """
+        if delete_project:
+            self._storage_initialized = False
+            del self._item_repository
+            shutil.rmtree(self.path)
+            return
+
         for item_key in self._item_repository:
             self._item_repository.delete_item(item_key)
 
+    @_raise_if_deleted
     def put(
         self,
         key: str,
@@ -150,6 +198,7 @@ def put(
             ),
         )
 
+    @_raise_if_deleted
     def get(
         self,
         key: str,
@@ -211,6 +260,7 @@ def dto(item):
 
         raise ValueError('`version` should be -1, "all", or an integer')
 
+    @_raise_if_deleted
     def keys(self) -> list[str]:
         """
         Get all keys of items stored in the project.
@@ -222,6 +272,7 @@ def keys(self) -> list[str]:
         """
         return self._item_repository.keys()
 
+    @_raise_if_deleted
     def __iter__(self) -> Iterator[str]:
         """
         Yield the keys of items stored in the project.
@@ -233,6 +284,7 @@ def __iter__(self) -> Iterator[str]:
         """
         yield from self._item_repository
 
+    @_raise_if_deleted
     def delete(self, key: str):
         """Delete the item corresponding to ``key`` from the Project.
 
@@ -248,6 +300,7 @@ def delete(self, key: str):
         """
         self._item_repository.delete_item(key)
 
+    @_raise_if_deleted
     def set_note(self, key: str, note: str, *, version=-1):
         """Attach a note to key ``key``.
 
@@ -277,6 +330,7 @@ def set_note(self, key: str, note: str, *, version=-1):
         """
         return self._item_repository.set_item_note(key=key, note=note, version=version)
 
+    @_raise_if_deleted
     def get_note(self, key: str, *, version=-1) -> Union[str, None]:
         """Retrieve a note previously attached to key ``key``.
 
@@ -306,6 +360,7 @@ def get_note(self, key: str, *, version=-1) -> Union[str, None]:
         """
         return self._item_repository.get_item_note(key=key, version=version)
 
+    @_raise_if_deleted
     def delete_note(self, key: str, *, version=-1):
         """Delete a note previously attached to key ``key``.
 
@@ -333,6 +388,7 @@ def delete_note(self, key: str, *, version=-1):
         """
         return self._item_repository.delete_item_note(key=key, version=version)
 
+    @_raise_if_deleted
     def shutdown_web_ui(self):
         """Shutdown the web UI server if it is running."""
         if self._server_info is None:

skore/tests/conftest.py

@@ -43,6 +43,7 @@ def in_memory_project(monkeypatch):
     project.path = None
     project.name = "test"
     project._item_repository = ItemRepository(storage=InMemoryStorage())
+    project._storage_initialized = True
 
     return project
 

skore/tests/unit/project/test_project.py

@@ -12,6 +12,7 @@
 from PIL import Image
 from sklearn.ensemble import RandomForestClassifier
 from skore import Project
+from skore.project.project import ProjectDeletedError
 
 
 @pytest.fixture(autouse=True)
@@ -49,6 +50,21 @@ def test_clear(tmp_path):
     assert project.keys() == []
     assert project._item_repository.keys() == []
 
+    assert dirpath.exists()
+
+
+def test_clear_delete_project(tmp_path):
+    dirpath = tmp_path / "my-project.skore"
+    project = Project(dirpath)
+
+    project.clear(delete_project=True)
+    assert not dirpath.exists()
+
+    with pytest.raises(
+        ProjectDeletedError, match="This Project instance is marked as deleted"
+    ):
+        project.keys()
+
 
 def test_put_string_item(in_memory_project):
     in_memory_project.put("string_item", "Hello, World!")