Add PersistentOnErrorTemporaryDirectory ctx manager (#49)

Is derived from `tempfile.TemporaryDirectory`, but it does
not delete the directory if an exception occurs. This is useful for
debugging or when you want to inspect the content of the directory
after an error.

Author: tomschr

changelog.d/49.feature.rst

@@ -0,0 +1,2 @@
+Add new context manager :class:`~docbuild.utils.contextmgr.PersistentOnErrorTemporaryDirectory`.
+It is derived from :class:`tempfile.TemporaryDirectory`and has a similar behavior, but it does not delete the temporary directory on exit if an exception occurs.

src/docbuild/utils/contextmgr.py

@@ -3,7 +3,21 @@
 from collections.abc import Callable, Iterator
 from contextlib import AbstractContextManager, contextmanager
 from dataclasses import dataclass
+import logging
+from pathlib import Path
+import shutil
+import tempfile
 import time
+from types import TracebackType
+import weakref as _weakref
+
+# Type aliases for exception handling
+type ExcType = type[BaseException] | None
+type ExcVal = BaseException | None
+type ExcTback = TracebackType | None
+
+# Logging
+log = logging.getLogger(__name__)
 
 
 @dataclass
@@ -53,3 +67,63 @@ def wrapper() -> Iterator[TimerData]:
             data.elapsed = data.end - data.start
 
     return wrapper
+
+
+class PersistentOnErrorTemporaryDirectory(tempfile.TemporaryDirectory):
+    """Delete temporary directory only if no exception occurs.
+
+    It is similar to :class:`tempfile.TemporaryDirectory`, but it does not
+    delete the directory if an exception occurs. This is useful for debugging
+    or when you want to inspect the contents of the directory after an error.
+
+    .. code-block:: python
+
+        with PersistentOnErrorTemporaryDirectory() as temp_dir:
+            # Do something with the temporary directory, it's a Path object
+
+    Optional arguments:
+    :param suffix: A str suffix for the directory name.  (see mkdtemp)
+    :param prefix: A str prefix for the directory name.  (see mkdtemp)
+    :param dir: A directory to create this temp dir in.  (see mkdtemp)
+    """
+
+    def __init__(
+        self,
+        suffix: str | None = None,
+        prefix: str | None = None,
+        dir: str | Path | None = None,  # noqa: A002
+    ) -> None:
+        # Call the parent constructor. We don't need the
+        # `ignore_cleanup_errors` flag as we implement our own cleanup.
+        super().__init__(suffix=suffix, prefix=prefix, dir=dir)
+
+    def __enter__(self) -> Path:
+        """Enter the runtime context and create the temporary directory.
+
+        :returns: Path to the created temporary directory.
+        """
+        # The parent __enter__ returns a string, so we override it
+        # to return a Path object for consistency with your original class.
+        return Path(self.name)
+
+    def __exit__(self, exc_type: ExcType, exc_val: ExcVal, exc_tb: ExcTback) -> None:
+        """Exit the runtime context and delete the directory if no exception occurred.
+
+        :param exc_type: Exception type, if any.
+        :param exc_val: Exception instance, if any.
+        :param exc_tb: Traceback, if any.
+        """
+        # CRITICAL: We must always detach the finalizer. If we don't,
+        # and an error occurred, the directory would still be deleted
+        # upon garbage collection, which is not what we want.
+        self._finalizer.detach()
+
+        if exc_type is None:
+            # No exception occurred in the `with` block, so we clean up.
+            try:
+                shutil.rmtree(self.name)
+
+            except OSError as e:
+                # Your custom logging is more informative than the parent's
+                # `ignore_errors=True`, so we replicate it here.
+                log.exception('Failed to delete temp dir %s: %s', self.name, e)

tests/utils/test_contextmgr.py

@@ -1,9 +1,12 @@
 import math
+from pathlib import Path
 import time
+from unittest.mock import patch
 
 import pytest
 
-from docbuild.utils.contextmgr import make_timer
+import docbuild.utils.contextmgr as contextmgr
+from docbuild.utils.contextmgr import PersistentOnErrorTemporaryDirectory, make_timer
 
 
 def test_timer_has_correct_attributes():
@@ -64,3 +67,60 @@ def test_timer_for_nan_as_default():
         assert timer_data.start > 0
         assert math.isnan(timer_data.end)
         assert math.isnan(timer_data.elapsed)
+
+
+# ----
+@pytest.fixture
+def fake_temp_path() -> str:
+    return '/mock/temp/dir'
+
+
+def test_temp_dir_deleted_on_success(fake_temp_path: str) -> None:
+    """Ensure the directory is deleted if no exception occurs."""
+    with (
+        patch.object(contextmgr.tempfile,
+            'mkdtemp',
+            return_value=fake_temp_path,
+        ),
+        patch.object(contextmgr.shutil, 'rmtree') as mock_rmtree,
+    ):
+        with PersistentOnErrorTemporaryDirectory() as temp_path:
+            assert temp_path == Path(fake_temp_path)
+
+        mock_rmtree.assert_called_once_with(fake_temp_path)
+
+
+def test_temp_dir_preserved_on_exception(fake_temp_path: str) -> None:
+    """Ensure the directory is preserved if an exception occurs."""
+    with (
+        patch.object(contextmgr.tempfile, 'mkdtemp', return_value=fake_temp_path),
+        patch.object(contextmgr.shutil, 'rmtree') as mock_rmtree,
+    ):
+        with pytest.raises(RuntimeError):
+            with PersistentOnErrorTemporaryDirectory() as temp_path:
+                assert temp_path == Path(fake_temp_path)
+                raise RuntimeError('Simulated failure')
+
+        mock_rmtree.assert_not_called()
+
+
+def test_temp_dir_deletion_failure_is_logged(fake_temp_path: str) -> None:
+    """Ensure that an OSError during directory deletion is logged."""
+    mock_error = OSError('Permission denied')
+
+    with (
+        patch.object(contextmgr.tempfile, 'mkdtemp', return_value=fake_temp_path),
+        patch.object(contextmgr.shutil, 'rmtree', side_effect=mock_error)
+        as mock_rmtree,
+        patch.object(contextmgr.log, 'exception') as mock_log_exception,
+    ):
+        # The __exit__ method should catch the OSError and not re-raise it.
+        with PersistentOnErrorTemporaryDirectory() as temp_path:
+            assert temp_path == Path(fake_temp_path)
+
+        # Verify that rmtree was called, which triggered the error
+        mock_rmtree.assert_called_once_with(fake_temp_path)
+        # Verify that the exception was logged with the correct message.
+        mock_log_exception.assert_called_once_with(
+            'Failed to delete temp dir %s: %s', fake_temp_path, mock_error
+        )