delete: Raise exceptions for failures

- Raises PdfRestDeleteError when a file can be deleted.

- Since there can be more than one file deleted at a time, raises the
  error inside a PdfRestErrorGroup.

Assisted-by: Codex

Author: datalogics-kam

src/pdfrest/__init__.py

@@ -7,7 +7,9 @@
     PdfRestApiError,
     PdfRestAuthenticationError,
     PdfRestConfigurationError,
+    PdfRestDeleteError,
     PdfRestError,
+    PdfRestErrorGroup,
     PdfRestRequestError,
     PdfRestTimeoutError,
     PdfRestTransportError,
@@ -21,7 +23,9 @@
     "PdfRestAuthenticationError",
     "PdfRestClient",
     "PdfRestConfigurationError",
+    "PdfRestDeleteError",
     "PdfRestError",
+    "PdfRestErrorGroup",
     "PdfRestRequestError",
     "PdfRestTimeoutError",
     "PdfRestTransportError",

src/pdfrest/client.py

@@ -50,7 +50,9 @@
     PdfRestAuthenticationError,
     PdfRestConfigurationError,
     PdfRestConnectTimeoutError,
+    PdfRestDeleteError,
     PdfRestError,
+    PdfRestErrorGroup,
     PdfRestPoolTimeoutError,
     PdfRestRequestError,
     PdfRestTimeoutError,
@@ -111,6 +113,7 @@
 MAX_BACKOFF_SECONDS = 8.0
 BACKOFF_JITTER_SECONDS = 0.1
 RETRYABLE_STATUS_CODES = {408, 425, 429, 499}
+_SUCCESSFUL_DELETION_MESSAGE = "successfully deleted"
 
 
 HttpMethod = Literal["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"]
@@ -227,6 +230,20 @@ def _extract_uploaded_file_ids(payload: Any) -> list[str]:
     return file_ids
 
 
+def _handle_deletion_failures(response: PdfRestDeletionResponse) -> None:
+    failures: list[PdfRestDeleteError] = []
+    for file_id, result in response.deletion_responses.items():
+        normalized_result = result.strip().lower()
+        if normalized_result != _SUCCESSFUL_DELETION_MESSAGE:
+            failures.append(PdfRestDeleteError(file_id, result))
+    if failures:
+        msg = "Failed to delete one or more files."
+        raise PdfRestErrorGroup(
+            msg,
+            failures,
+        )
+
+
 def _normalize_headers(headers: Mapping[str, str]) -> Mapping[str, str]:
     return {str(key): str(value) for key, value in headers.items()}
 
@@ -1553,7 +1570,7 @@ def delete(
         extra_headers: AnyMapping | None = None,
         extra_body: Body | None = None,
         timeout: TimeoutTypes | None = None,
-    ) -> PdfRestDeletionResponse:
+    ) -> None:
         """Delete one or more uploaded files by reference."""
 
         payload = DeletePayload.model_validate({"files": files})
@@ -1569,7 +1586,9 @@ def delete(
             timeout=timeout,
         )
         raw_payload = self._client.send_request(request)
-        return PdfRestDeletionResponse.model_validate(raw_payload)
+        deletion_response = PdfRestDeletionResponse.model_validate(raw_payload)
+        _handle_deletion_failures(deletion_response)
+        return
 
     def read_bytes(
         self,
@@ -1853,7 +1872,7 @@ async def delete(
         extra_headers: AnyMapping | None = None,
         extra_body: Body | None = None,
         timeout: TimeoutTypes | None = None,
-    ) -> PdfRestDeletionResponse:
+    ) -> None:
         """Delete one or more uploaded files by reference."""
 
         payload = DeletePayload.model_validate({"files": files})
@@ -1869,7 +1888,9 @@ async def delete(
             timeout=timeout,
         )
         raw_payload = await self._client.send_request(request)
-        return PdfRestDeletionResponse.model_validate(raw_payload)
+        deletion_response = PdfRestDeletionResponse.model_validate(raw_payload)
+        _handle_deletion_failures(deletion_response)
+        return
 
     async def read_bytes(
         self,

src/pdfrest/exceptions.py

@@ -2,24 +2,32 @@
 
 from __future__ import annotations
 
-from typing import Any
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Any
 
 import httpx
 from typing_extensions import override
 
+if TYPE_CHECKING:  # pragma: no cover
+    from .models import PdfRestFileID
+
 __all__ = (
     "PdfRestApiError",
     "PdfRestAuthenticationError",
     "PdfRestConfigurationError",
     "PdfRestConnectTimeoutError",
+    "PdfRestDeleteError",
     "PdfRestError",
+    "PdfRestErrorGroup",
     "PdfRestPoolTimeoutError",
     "PdfRestRequestError",
     "PdfRestTimeoutError",
     "PdfRestTransportError",
     "translate_httpx_error",
 )
 
+from exceptiongroup import ExceptionGroup
+
 
 class PdfRestError(Exception):
     """Base exception for all pdfrest client errors."""
@@ -78,6 +86,27 @@ class PdfRestAuthenticationError(PdfRestApiError):
     """Raised when authentication with the pdfRest API fails."""
 
 
+class PdfRestDeleteError(PdfRestError):
+    """Raised when an individual file cannot be deleted."""
+
+    def __init__(self, file_id: PdfRestFileID | str, message: str) -> None:
+        self.file_id = str(file_id)
+        self.detail = message
+        super().__init__(f"Failed to delete file {self.file_id}: {message}")
+
+
+class PdfRestErrorGroup(ExceptionGroup):
+    """Group of PdfRestError exceptions produced by the PDF REST library."""
+
+    def __init__(self, message: str, exceptions: Sequence[Exception], /) -> None:
+        # enforce that everything inside is from your library
+        for e in exceptions:
+            if not isinstance(e, PdfRestError):
+                msg = f"PdfRestErrorGroup may only contain PdfRestError instances, got {type(e)}"
+                raise TypeError(msg)
+        super().__init__(message, list(exceptions))
+
+
 def translate_httpx_error(exc: httpx.HTTPError) -> PdfRestError:
     """Convert an httpx exception into a library-specific exception."""