DataExcept 1.3.0__tar.gz → 1.4.0__tar.gz

{dataexcept-1.3.0 → dataexcept-1.4.0}/CHANGELOG.md

@@ -7,6 +7,46 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.4.0] - 2026-09-04
+
+### Added
+
+- **A canonical cause contract for operational exceptions.** New code can use
+  keyword-only `cause=` and the public `.cause` attribute, while existing
+  `original=` and `original_exception=` APIs remain supported where they were
+  already public. Accepted causes populate `__cause__`, survive pickling and
+  structured serialization, and invalid or ambiguous aliases fail fast.
+- **Machine-readable failure metadata.** Every `DataExceptError` exposes
+  `failure_kind`, `retryable`, `retry_after_seconds` and the immutable
+  `FailureMetadata` value object. Validation and authentication/authorization
+  failures have conservative permanent/non-retryable defaults; generic
+  infrastructure failures remain unknown unless backend evidence says more.
+- `wrap()` and `wrapping()` accept `failure_metadata=` so integrations can
+  attach backend-informed retryability without parsing messages or changing
+  exception constructors.
+- Structured envelopes now include a stable `failure` object carrying failure
+  kind, retryability and optional retry delay.
+
+### Changed
+
+- `wrap()` now prefers the canonical `cause` keyword when a target supports it,
+  while preserving explicit legacy cause overrides and always chaining the
+  actual wrapped exception through `__cause__`.
+- Release automation now uses one permanent privileged Release workflow. Normal
+  release preparation happens through ordinary branches and pull requests;
+  publication is requested only after the reviewed release commit reaches
+  protected `main`.
+
+### Fixed
+
+- Failure-metadata serialization now preserves the serializer's never-throw
+  contract even for hostile or malformed custom accessors. Invalid kinds,
+  retryability values, string or boolean delays, negative delays and non-finite
+  delays all fall back to the canonical unknown failure record; valid numeric
+  delays are normalised to `float`.
+- Cause-aware wrapping no longer injects a second canonical cause when a caller
+  already supplied a legacy `original` or `original_exception` override.
+
 ## [1.3.0] - 2026-09-03
 
 ### Added
@@ -188,7 +228,7 @@ and the [migration guide](https://diogoribeiro7.github.io/DataExcept/migration/)
 - Two classes assigned their attributes *after* calling `super().__init__`, so
   the sweep never saw them. Both now assign first, and a test fails if any
   constructor does it again.
-- The URL pattern carried a `` anchor, so a URL directly following a word
+- The URL pattern carried a `\b` anchor, so a URL directly following a word
   character was never matched — including `feature_https://...`, the step name
   `FeaturePreprocessingError` builds from its own argument.
 
@@ -570,7 +610,8 @@ First public release.
 - Published to PyPI via OIDC trusted publishing; no long-lived API token is
   involved in a release.
 
-[Unreleased]: https://github.com/DiogoRibeiro7/DataExcept/compare/v1.3.0...HEAD
+[Unreleased]: https://github.com/DiogoRibeiro7/DataExcept/compare/v1.4.0...HEAD
+[1.4.0]: https://github.com/DiogoRibeiro7/DataExcept/compare/v1.3.0...v1.4.0
 [1.3.0]: https://github.com/DiogoRibeiro7/DataExcept/compare/v1.2.0...v1.3.0
 [1.2.0]: https://github.com/DiogoRibeiro7/DataExcept/compare/v1.1.0...v1.2.0
 [1.1.0]: https://github.com/DiogoRibeiro7/DataExcept/compare/v1.0.0...v1.1.0

{dataexcept-1.3.0 → dataexcept-1.4.0}/CITATION.cff

@@ -1,7 +1,7 @@
 cff-version: 1.2.0
 message: "If you use this software, please cite it using the following metadata."
 title: "DataExcept"
-version: "1.3.0"
+version: "1.4.0"
 authors:
   - family-names: "Ribeiro"
     given-names: "Diogo"
@@ -11,4 +11,4 @@ authors:
 type: software
 url: "https://github.com/DiogoRibeiro7/DataExcept"
 repository-code: "https://github.com/DiogoRibeiro7/DataExcept"
-date-released: "2026-09-03"
+date-released: "2026-09-04"

{dataexcept-1.3.0 → dataexcept-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: DataExcept
-Version: 1.3.0
+Version: 1.4.0
 Summary: A Python package providing structured, easily-extendable custom exception types.
 License-Expression: MIT
 License-File: LICENSE

{dataexcept-1.3.0 → dataexcept-1.4.0}/dataexcept/__init__.py

@@ -111,6 +111,7 @@ from .exceptions import (
     ValidationError,
     WebhookError,
 )
+from .failure_metadata import FailureKind, FailureMetadata
 from .io_exceptions import (
     CustomIOError,
     FileLockError,
@@ -163,13 +164,11 @@ from .serialization import exception_to_dict, exception_to_json
 from .wrapping import wrap, wrapping
 
 __all__ = [
-    # The root of the hierarchy: catches every operational exception the
-    # package raises.
     "DataExceptError",
-    # Placeholders for state that could not survive serialization.
     "UnpicklableCause",
     "UnpicklableValue",
-    # Every exception class the package defines.
+    "FailureKind",
+    "FailureMetadata",
     "ApiError",
     "AuthenticationError",
     "AuthorizationError",
@@ -268,18 +267,14 @@ __all__ = [
     "UnderfittingError",
     "ValidationError",
     "WebhookError",
-    # Turning a third-party exception into one of these.
     "wrap",
     "wrapping",
-    # Structured serialization for APIs, queues and telemetry.
     "exception_to_dict",
     "exception_to_json",
-    # Logging helpers.
     "Context",
     "log_and_raise",
     "log_exception",
     "log_then_raise",
-    # Domain modules, for callers who prefer a qualified import.
     "database_exceptions",
     "dataengineering_exceptions",
     "datascience_exceptions",

dataexcept-1.4.0/dataexcept/_causes.py

@@ -0,0 +1,31 @@
+"""Internal helpers for the canonical wrapped-exception contract."""
+
+from __future__ import annotations
+
+__all__ = ["resolve_cause"]
+
+
+def resolve_cause(
+    *,
+    cause: Exception | None = None,
+    original: Exception | None = None,
+    original_exception: Exception | None = None,
+) -> Exception | None:
+    """Return the one supplied cause, rejecting invalid or ambiguous aliases.
+
+    ``cause`` is the canonical public keyword. ``original`` and
+    ``original_exception`` remain supported only for backward compatibility.
+    """
+    values = (
+        ("cause", cause),
+        ("original", original),
+        ("original_exception", original_exception),
+    )
+    for name, value in values:
+        if value is not None and not isinstance(value, Exception):
+            raise TypeError(f"{name} must be Exception or None")
+
+    supplied = [value for _, value in values if value is not None]
+    if len(supplied) > 1:
+        raise TypeError("provide only one of cause, original, or original_exception")
+    return supplied[0] if supplied else None

{dataexcept-1.3.0 → dataexcept-1.4.0}/dataexcept/base.py

@@ -34,22 +34,16 @@ from __future__ import annotations
 import pickle
 from typing import Any, Dict, Optional, Tuple, Type
 
+from .failure_metadata import FailureKind, FailureMetadata
 from .redaction import redact_urls_in_text
 
 __all__ = ["DataExceptError", "UnpicklableCause", "UnpicklableValue"]
 
-#: Attribute names used across the package to hold the exception that caused
-#: this one. Checked in order; the first that holds an exception wins.
 _CAUSE_ATTRIBUTES = ("original", "original_exception", "cause")
 
 
 class UnpicklableValue:
-    """Stands in for state that could not survive serialization.
-
-    An exception carrying a lambda, an open file or a lock would otherwise be
-    unraisable across a process boundary. Keeping a description preserves what
-    the value was for debugging, which is the reason it was attached.
-    """
+    """Stands in for state that could not survive serialization."""
 
     __slots__ = ("description",)
 
@@ -79,7 +73,7 @@ def _safe(value: Any) -> Any:
     except Exception:
         try:
             description = f"{type(value).__name__}: {value!r}"
-        except Exception:  # pragma: no cover - a repr that itself raises
+        except Exception:  # pragma: no cover
             description = type(value).__name__
         return UnpicklableValue(description[:200])
     return value
@@ -104,22 +98,7 @@ def _rebuild(
     context: Optional[BaseException] = None,
     suppress_context: bool = False,
 ) -> "DataExceptError":
-    """Recreate *cls* without replaying its ``__init__``.
-
-    Constructors validate and render a message from their arguments; replaying
-    them would need those arguments, which ``args`` does not carry. Restoring
-    ``args`` and ``__dict__`` directly reproduces the exception exactly.
-
-    The three chain arguments carry defaults so that a payload pickled by an
-    earlier version -- which passed only ``cls``, ``args`` and ``state`` --
-    still loads. An exception can outlive an upgrade: it may sit in a task
-    queue, or be sent by a worker running the previous release.
-
-    ``__cause__``, ``__context__`` and ``__suppress_context__`` live outside
-    ``__dict__`` -- they are special exception state -- so they are restored
-    explicitly. Without this the chain is silently lost, and a traceback
-    rebuilt in another process no longer shows what actually failed.
-    """
+    """Recreate *cls* without replaying its ``__init__``."""
     exc = cls.__new__(cls)
     Exception.__init__(exc, *args)
     exc.__dict__.update(state)
@@ -132,44 +111,51 @@ def _rebuild(
 class DataExceptError(Exception):
     """Base class for every operational exception DataExcept raises."""
 
-    #: Passed to redact_urls_in_text when scrubbing this class's message.
-    #: WebhookError sets it False, because a webhook URL's path *is* the
-    #: credential.
     _keep_url_path = True
+    _default_failure_metadata = FailureMetadata()
 
     def __init__(self, *args: Any) -> None:
-        # One boundary for the whole hierarchy. Whatever built the message -- a
-        # constructor, a caller-supplied `message`, or the text of a wrapped
-        # exception quoting the original URL -- it is scrubbed here, because
-        # redacting only the structured argument leaves all three routes open.
         keep_path = type(self)._keep_url_path
         if args and isinstance(args[0], str):
             args = (redact_urls_in_text(args[0], keep_path=keep_path),) + args[1:]
 
-        # Many classes store the message on self.message and render *that* in
-        # __str__, and 18 interpolate some other attribute -- a field, a
-        # column, a resource -- any of which a caller can fill with a URL. So
-        # every stored string is swept, not just the message.
-        #
-        # redact_urls_in_text rather than redact_if_url: a message has the URL
-        # embedded in prose, and redact_if_url only handles a value that is
-        # wholly a URL. It is a no-op on anything without "://" in it, so
-        # ordinary names and file paths are untouched.
         for name, value in list(self.__dict__.items()):
             if isinstance(value, str) and "://" in value:
                 self.__dict__[name] = redact_urls_in_text(value, keep_path=keep_path)
 
         super().__init__(*args)
-        # Constructors that wrap another exception record it on an attribute.
-        # Mirroring it into __cause__ is what makes a traceback print the
-        # underlying failure, exactly as `raise ... from exc` would; assigning
-        # __cause__ also sets __suppress_context__, as `raise from` does.
         for attribute in _CAUSE_ATTRIBUTES:
             candidate = getattr(self, attribute, None)
             if isinstance(candidate, BaseException):
                 self.__cause__ = candidate
                 break
 
+    @property
+    def failure_metadata(self) -> FailureMetadata:
+        override = self.__dict__.get("_failure_metadata_override")
+        if isinstance(override, FailureMetadata):
+            return override
+        return type(self)._default_failure_metadata
+
+    @property
+    def failure_kind(self) -> FailureKind:
+        return self.failure_metadata.failure_kind
+
+    @property
+    def retryable(self) -> bool | None:
+        return self.failure_metadata.retryable
+
+    @property
+    def retry_after_seconds(self) -> float | None:
+        return self.failure_metadata.retry_after_seconds
+
+    def with_failure_metadata(self, metadata: FailureMetadata) -> "DataExceptError":
+        """Attach backend-informed metadata and return ``self`` for chaining."""
+        if not isinstance(metadata, FailureMetadata):
+            raise TypeError("metadata must be a FailureMetadata instance")
+        self._failure_metadata_override = metadata
+        return self
+
     def __reduce__(self) -> Tuple[Any, Tuple[Any, ...]]:
         args = tuple(_safe(arg) for arg in self.args)
         state = {key: _safe(value) for key, value in self.__dict__.items()}

{dataexcept-1.3.0 → dataexcept-1.4.0}/dataexcept/database_exceptions.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from ._causes import resolve_cause
 from .base import DataExceptError
 from .redaction import redact_url
 
@@ -31,18 +32,27 @@ class DatabaseConnectionError(DatabaseError):
 class QueryExecutionError(DatabaseError):
     """Raised when a database query execution fails."""
 
-    def __init__(self, query: str, original: Exception | None = None) -> None:
+    def __init__(
+        self,
+        query: str,
+        original: Exception | None = None,
+        *,
+        cause: Exception | None = None,
+    ) -> None:
         """Initialize QueryExecutionError.
 
         Args:
             query: SQL query string.
-            original: Optional underlying exception.
+            original: Legacy alias for ``cause``.
+            cause: Optional underlying exception.
         """
+        resolved = resolve_cause(cause=cause, original=original)
         self.query = query
-        self.original = original
+        self.original = resolved
+        self.cause = resolved
         msg = f"Query failed: {query}"
-        if original:
-            msg += f" ({original})"
+        if resolved:
+            msg += f" ({resolved})"
         super().__init__(msg)
 
 
@@ -53,14 +63,18 @@ class TransactionError(DatabaseError):
         self,
         transaction_id: str | None = None,
         message: str | None = None,
+        *,
+        cause: Exception | None = None,
     ) -> None:
         """Initialize TransactionError.
 
         Args:
             transaction_id: Identifier for the transaction.
             message: Optional custom error message.
+            cause: Optional underlying exception.
         """
         self.transaction_id = transaction_id
+        self.cause = cause
         default = "Database transaction failed"
         if transaction_id:
             default += f" (id={transaction_id})"

{dataexcept-1.3.0 → dataexcept-1.4.0}/dataexcept/exceptions/authentication.py

@@ -1,10 +1,16 @@
 # authentication.py
+from ..failure_metadata import FailureMetadata
 from .base import JobError
 
 
 class AuthenticationError(JobError):
     """Raised when user authentication fails."""
 
+    _default_failure_metadata = FailureMetadata(
+        failure_kind="permanent",
+        retryable=False,
+    )
+
     def __init__(self, user: str, message: str | None = None):
         self.user = user
         self.message = message or f"Authentication failed for user '{user}'"
@@ -14,6 +20,11 @@ class AuthenticationError(JobError):
 class AuthorizationError(JobError):
     """Raised when user lacks permission for an action."""
 
+    _default_failure_metadata = FailureMetadata(
+        failure_kind="permanent",
+        retryable=False,
+    )
+
     def __init__(self, user: str, permission: str):
         self.user = user
         self.permission = permission

{dataexcept-1.3.0 → dataexcept-1.4.0}/dataexcept/exceptions/external.py

@@ -1,24 +1,43 @@
+from .._causes import resolve_cause
 from .base import JobError
 
 
 class ServiceConnectionError(JobError):
     """Raised when a connection to an external service fails."""
 
-    def __init__(self, service_name: str, original_exception: Exception | None = None):
+    def __init__(
+        self,
+        service_name: str,
+        original_exception: Exception | None = None,
+        *,
+        cause: Exception | None = None,
+    ):
+        resolved = resolve_cause(
+            cause=cause,
+            original_exception=original_exception,
+        )
         self.service_name = service_name
-        self.original_exception = original_exception
+        self.original_exception = resolved
+        self.cause = resolved
         msg = f"Failed to connect to service '{service_name}'"
-        if original_exception:
-            msg += f": {original_exception}"
+        if resolved:
+            msg += f": {resolved}"
         super().__init__(msg)
 
 
 class OperationTimeoutError(JobError):
     """Raised when an operation exceeds its time limit."""
 
-    def __init__(self, operation: str, timeout: float):
+    def __init__(
+        self,
+        operation: str,
+        timeout: float,
+        *,
+        cause: Exception | None = None,
+    ):
         self.operation = operation
         self.timeout = timeout
+        self.cause = cause
         msg = f"Operation '{operation}' timed out after {timeout} seconds"
         super().__init__(msg)
 

{dataexcept-1.3.0 → dataexcept-1.4.0}/dataexcept/exceptions/validation.py

@@ -1,10 +1,16 @@
 # validation.py
+from ..failure_metadata import FailureMetadata
 from .base import JobError
 
 
 class ValidationError(JobError):
     """Raised when input data fails validation."""
 
+    _default_failure_metadata = FailureMetadata(
+        failure_kind="permanent",
+        retryable=False,
+    )
+
     def __init__(self, field: str, value, message: str | None = None):
         self.field = field
         self.value = value

dataexcept-1.4.0/dataexcept/failure_metadata.py

@@ -0,0 +1,45 @@
+"""Machine-readable failure classification for DataExcept exceptions."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from typing import Literal, TypeAlias
+
+__all__ = ["FailureKind", "FailureMetadata"]
+
+FailureKind: TypeAlias = Literal["transient", "permanent", "unknown"]
+_VALID_FAILURE_KINDS = {"transient", "permanent", "unknown"}
+
+
+@dataclass(frozen=True)
+class FailureMetadata:
+    """Describe recovery-relevant properties of an operational failure.
+
+    ``failure_kind`` describes whether the underlying condition is known to be
+    transient, permanent for the same operation/payload, or unknown.
+    ``retryable`` is deliberately independent: DataExcept describes the
+    failure, while the calling application still owns retry policy.
+    """
+
+    failure_kind: FailureKind = "unknown"
+    retryable: bool | None = None
+    retry_after_seconds: float | None = None
+
+    def __post_init__(self) -> None:
+        if self.failure_kind not in _VALID_FAILURE_KINDS:
+            raise ValueError(
+                "failure_kind must be 'transient', 'permanent', or 'unknown'"
+            )
+        if self.retryable is not None and not isinstance(self.retryable, bool):
+            raise TypeError("retryable must be bool or None")
+        if self.retry_after_seconds is None:
+            return
+        if isinstance(self.retry_after_seconds, bool) or not isinstance(
+            self.retry_after_seconds, (int, float)
+        ):
+            raise TypeError("retry_after_seconds must be a number or None")
+        seconds = float(self.retry_after_seconds)
+        if not math.isfinite(seconds) or seconds < 0:
+            raise ValueError("retry_after_seconds must be finite and non-negative")
+        object.__setattr__(self, "retry_after_seconds", seconds)

{dataexcept-1.3.0 → dataexcept-1.4.0}/dataexcept/pipeline_exceptions.py

@@ -4,7 +4,9 @@ from __future__ import annotations
 
 from typing import Any, Optional
 
+from ._causes import resolve_cause
 from .base import DataExceptError
+from .failure_metadata import FailureMetadata
 from .redaction import redact_if_url, redact_url
 
 
@@ -29,8 +31,6 @@ class FeaturePreprocessingError(PreprocessingError):
     """Raised when feature engineering fails."""
 
     def __init__(self, feature: str, reason: Optional[str] = None) -> None:
-        # Assigned before super(): DataExceptError.__init__ sweeps the stored
-        # strings for URLs, and anything set afterwards escapes that.
         self.feature = feature
         self.reason = reason
         super().__init__(step_name=f"feature_{feature}", details=reason)
@@ -44,10 +44,13 @@ class StorageError(PipelineError):
         location: str,
         operation: str,
         message: Optional[str] = None,
+        *,
+        cause: Exception | None = None,
     ) -> None:
         default = f"Storage {operation} failed at location: '{location}'."
         self.location = redact_if_url(location)
         self.operation = operation
+        self.cause = resolve_cause(cause=cause)
         super().__init__(message or default)
 
 
@@ -104,6 +107,11 @@ class ExternalServiceError(PipelineError):
 class ServiceAuthenticationError(ExternalServiceError):
     """Authentication to an external service failed."""
 
+    _default_failure_metadata = FailureMetadata(
+        failure_kind="permanent",
+        retryable=False,
+    )
+
     def __init__(
         self,
         service_name: str,
@@ -116,6 +124,11 @@ class ServiceAuthenticationError(ExternalServiceError):
 class ServiceAuthorizationError(ExternalServiceError):
     """Authorization was denied by an external service."""
 
+    _default_failure_metadata = FailureMetadata(
+        failure_kind="permanent",
+        retryable=False,
+    )
+
     def __init__(
         self,
         service_name: str,
@@ -150,7 +163,6 @@ class ApiError(PipelineError):
         status_code: Optional[int] = None,
         message: Optional[str] = None,
     ) -> None:
-        # An endpoint URL may authenticate through a query parameter.
         self.endpoint = redact_url(endpoint)
         default = f"API call failed: {self.endpoint}"
         if status_code is not None:

{dataexcept-1.3.0 → dataexcept-1.4.0}/dataexcept/serialization.py

@@ -8,6 +8,7 @@ import math
 from collections.abc import Mapping, Sequence, Set
 from typing import Any
 
+from .base import DataExceptError
 from .redaction import redact_urls_in_text
 
 __all__ = ["exception_to_dict", "exception_to_json"]
@@ -15,16 +16,15 @@ __all__ = ["exception_to_dict", "exception_to_json"]
 _MAX_VALUE_DEPTH = 8
 _NOT_SCALAR = object()
 _EXCEPTION_GROUP_TYPE = getattr(builtins, "BaseExceptionGroup", None)
+_UNKNOWN_FAILURE = {
+    "kind": "unknown",
+    "retryable": None,
+    "retry_after_seconds": None,
+}
 
 
 def _redact_export_text(text: str) -> str:
-    """Scrub URLs for export, including their paths.
-
-    Normal DataExcept messages preserve URL paths because paths are commonly
-    useful debugging context. Structured envelopes have a stricter boundary:
-    third-party errors and arbitrary caller state may put credentials in the
-    path itself, so exported text never preserves URL paths.
-    """
+    """Scrub URLs for export, including their paths."""
     return redact_urls_in_text(text, keep_path=False)
 
 
@@ -132,6 +132,46 @@ def _group_members(exc: BaseException) -> Sequence[BaseException] | None:
         return None
 
 
+def _failure_record(exc: DataExceptError) -> dict[str, Any]:
+    """Return failure metadata without letting hostile overrides escape."""
+    try:
+        metadata = exc.failure_metadata
+        failure = {
+            "kind": metadata.failure_kind,
+            "retryable": metadata.retryable,
+            "retry_after_seconds": metadata.retry_after_seconds,
+        }
+        if failure["kind"] not in {"transient", "permanent", "unknown"}:
+            raise ValueError("invalid failure kind")
+        if failure["retryable"] is not None and not isinstance(
+            failure["retryable"], bool
+        ):
+            raise TypeError("invalid retryable value")
+
+        retry_after = failure["retry_after_seconds"]
+        if retry_after is not None:
+            if isinstance(retry_after, bool) or not isinstance(
+                retry_after, (int, float)
+            ):
+                raise TypeError("invalid retry_after_seconds value")
+            retry_after = float(retry_after)
+            if not math.isfinite(retry_after) or retry_after < 0:
+                raise ValueError("invalid retry_after_seconds value")
+            failure["retry_after_seconds"] = retry_after
+
+        json.dumps(failure, allow_nan=False)
+        return failure
+    except Exception:
+        return dict(_UNKNOWN_FAILURE)
+
+
+def _failure_fields(exc: BaseException) -> dict[str, Any]:
+    """Return the optional structured failure field for *exc*."""
+    if not isinstance(exc, DataExceptError):
+        return {}
+    return {"failure": _failure_record(exc)}
+
+
 def _exception_record(
     exc: BaseException,
     *,
@@ -158,6 +198,7 @@ def _exception_record(
         "module": type(exc).__module__,
         "message": _safe_text(exc),
     }
+    record.update(_failure_fields(exc))
     if include_attributes:
         attributes = _attributes(exc)
         if attributes:
@@ -203,13 +244,7 @@ def exception_to_dict(
     include_attributes: bool = True,
     max_depth: int = 8,
 ) -> dict[str, Any]:
-    """Return a strict JSON-safe structured representation of *exc*.
-
-    The representation contains the exception type, module and rendered
-    message, optionally public instance attributes, bounded cause/context
-    chains, and on Python 3.11+ the member tree of exception groups. Traceback
-    frames and private attributes are deliberately excluded.
-    """
+    """Return a strict JSON-safe structured representation of *exc*."""
     if not isinstance(exc, BaseException):
         raise TypeError("exc must be an exception instance")
     if not isinstance(max_depth, int) or isinstance(max_depth, bool):

dataexcept-1.4.0/dataexcept/wrapping.py

@@ -0,0 +1,111 @@
+"""Turning a third-party exception into a DataExcept one.
+
+The pattern this replaces is everywhere in pipeline code::
+
+    try:
+        frame = pd.read_csv(path)
+    except OSError as exc:
+        raise DataLoadingError(path, exc) from exc
+
+It is easy to write and easy to get subtly wrong: forget the ``from exc`` and
+the traceback stops showing what actually failed; pass the original to the
+wrong parameter and it is not recorded at all; catch too broadly and a
+``KeyboardInterrupt`` becomes a data-loading error.
+
+:func:`wrap` and :func:`wrapping` do the same thing with the wiring settled.
+New cause-aware constructors use the canonical keyword ``cause``. Legacy
+``original`` and ``original_exception`` parameters remain supported, and
+``__cause__`` is set either way so a traceback always shows both failures.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import inspect
+from typing import Any, Iterator, Tuple, Type, Union
+
+from .base import DataExceptError
+from .failure_metadata import FailureMetadata
+
+__all__ = ["wrap", "wrapping"]
+
+_CAUSE_PARAMETERS = ("cause", "original", "original_exception")
+
+Catchable = Union[Type[BaseException], Tuple[Type[BaseException], ...]]
+
+
+def _cause_parameter(target: Type[DataExceptError]) -> str | None:
+    """Return the parameter of *target* that takes a wrapped exception."""
+    try:
+        parameters = inspect.signature(target.__init__).parameters
+    except (TypeError, ValueError):  # pragma: no cover - builtins and C types
+        return None
+    for name in _CAUSE_PARAMETERS:
+        if name in parameters:
+            return name
+    return None
+
+
+def _explicit_cause_parameter(kwargs: dict[str, Any]) -> str | None:
+    """Return an explicitly supplied canonical or legacy cause keyword."""
+    for name in _CAUSE_PARAMETERS:
+        if name in kwargs:
+            return name
+    return None
+
+
+def wrap(
+    original: BaseException,
+    target: Type[DataExceptError],
+    /,
+    *,
+    failure_metadata: FailureMetadata | None = None,
+    **kwargs: Any,
+) -> DataExceptError:
+    """Build *target* from *original*, recording it as the cause.
+
+    Extra keyword arguments are passed through to the target constructor. If
+    the target accepts a cause parameter, *original* is injected unless the
+    caller already supplied ``cause``, ``original`` or ``original_exception``.
+    The resulting exception is always chained to *original* via ``__cause__``.
+
+    ``failure_metadata`` optionally overrides the target class's conservative
+    default when the integration has backend-specific evidence about whether
+    the failure is transient or retryable.
+    """
+    if failure_metadata is not None and not isinstance(
+        failure_metadata, FailureMetadata
+    ):
+        raise TypeError("failure_metadata must be FailureMetadata or None")
+
+    if _explicit_cause_parameter(kwargs) is None:
+        parameter = _cause_parameter(target)
+        if parameter is not None:
+            kwargs[parameter] = original
+
+    exception = target(**kwargs)
+    exception.__cause__ = original
+    if failure_metadata is not None:
+        exception.with_failure_metadata(failure_metadata)
+    return exception
+
+
+@contextlib.contextmanager
+def wrapping(
+    catch: Catchable,
+    target: Type[DataExceptError],
+    /,
+    *,
+    failure_metadata: FailureMetadata | None = None,
+    **kwargs: Any,
+) -> Iterator[None]:
+    """Translate *catch* raised inside the block into *target*."""
+    try:
+        yield
+    except catch as exc:
+        raise wrap(
+            exc,
+            target,
+            failure_metadata=failure_metadata,
+            **kwargs,
+        ) from exc

{dataexcept-1.3.0 → dataexcept-1.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "DataExcept"
-version = "1.3.0"
+version = "1.4.0"
 description = "A Python package providing structured, easily-extendable custom exception types."
 readme = "README.md"
 license = "MIT"

dataexcept-1.3.0/dataexcept/wrapping.py

@@ -1,103 +0,0 @@
-"""Turning a third-party exception into a DataExcept one.
-
-The pattern this replaces is everywhere in pipeline code::
-
-    try:
-        frame = pd.read_csv(path)
-    except OSError as exc:
-        raise DataLoadingError(path, exc) from exc
-
-It is easy to write and easy to get subtly wrong: forget the ``from exc`` and
-the traceback stops showing what actually failed; pass the original to the
-wrong parameter and it is not recorded at all; catch too broadly and a
-``KeyboardInterrupt`` becomes a data-loading error.
-
-:func:`wrap` and :func:`wrapping` do the same thing with the wiring settled.
-The original is passed to whichever constructor parameter takes a cause --
-``original``, ``original_exception`` or ``cause``, whichever that class uses --
-and set as ``__cause__`` either way, so a traceback always shows both.
-"""
-
-from __future__ import annotations
-
-import contextlib
-import inspect
-from typing import Any, Iterator, Tuple, Type, Union
-
-from .base import DataExceptError
-
-__all__ = ["wrap", "wrapping"]
-
-#: Constructor parameter names used across the package for a wrapped
-#: exception. Checked in this order; the first the target accepts wins.
-_CAUSE_PARAMETERS = ("original", "original_exception", "cause")
-
-Catchable = Union[Type[BaseException], Tuple[Type[BaseException], ...]]
-
-
-def _cause_parameter(target: Type[DataExceptError]) -> str | None:
-    """Return the parameter of *target* that takes a wrapped exception."""
-    try:
-        parameters = inspect.signature(target.__init__).parameters
-    except (TypeError, ValueError):  # pragma: no cover - builtins and C types
-        return None
-    for name in _CAUSE_PARAMETERS:
-        if name in parameters:
-            return name
-    return None
-
-
-def wrap(
-    original: BaseException,
-    target: Type[DataExceptError],
-    /,
-    **kwargs: Any,
-) -> DataExceptError:
-    """Build *target* from *original*, recording it as the cause.
-
-    Extra keyword arguments go to the constructor::
-
-        raise wrap(exc, DataLoadingError, source=path) from exc
-
-    If *target* accepts a cause parameter, *original* is passed to it. Either
-    way ``__cause__`` is set, so a traceback shows the underlying failure even
-    for a class that records nothing.
-
-    An explicit ``original``/``cause`` keyword wins, so a caller can still say
-    exactly what they mean.
-    """
-    parameter = _cause_parameter(target)
-    if parameter is not None and parameter not in kwargs:
-        kwargs[parameter] = original
-
-    exception = target(**kwargs)
-    # Set unconditionally: the target may record nothing, and the point is that
-    # the traceback shows what actually failed.
-    exception.__cause__ = original
-    return exception
-
-
-@contextlib.contextmanager
-def wrapping(
-    catch: Catchable,
-    target: Type[DataExceptError],
-    /,
-    **kwargs: Any,
-) -> Iterator[None]:
-    """Translate *catch* raised inside the block into *target*.
-
-    ::
-
-        with wrapping(OSError, DataLoadingError, source=path):
-            frame = pd.read_csv(path)
-
-    Only exceptions matching *catch* are translated; everything else propagates
-    untouched, including anything already raised by this package. Because
-    *catch* is given explicitly there is no default broad ``except``, so a
-    ``KeyboardInterrupt`` or a bug in the block is never relabelled as a data
-    error.
-    """
-    try:
-        yield
-    except catch as exc:
-        raise wrap(exc, target, **kwargs) from exc