DataExcept 1.3.0__tar.gz → 1.5.0__tar.gz

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

@@ -7,6 +7,102 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.5.0] - 2026-09-06
+
+### Added
+
+- **Redaction-safe source context for parsing failures.** `ParsingError` and
+  `DeserializationError` accept keyword-only `source`, `format`, `preview` and
+  `cause`, so a failure on untrusted content can be described without keeping
+  the content. `source` is redacted when it is a URL and left alone when it is
+  a file path; `preview` is bounded to 200 characters including its truncation
+  marker, decodes bytes as UTF-8
+  with any undecodable byte shown as `\xNN`, and is redacted like any other
+  public attribute.
+- `cause=` on both classes, following the canonical 1.4.0 contract: recorded as
+  `.cause` and set as `__cause__`.
+- **A published JSON Schema for the structured envelope.** The payload
+  `exception_to_dict()` and `exception_to_json()` produce is now a versioned,
+  language-neutral contract rather than prose. `envelope_schema()`,
+  `ENVELOPE_SCHEMA_VERSION` and `ENVELOPE_SCHEMA_ID` expose it from the top
+  level; the document ships inside the package and is published at its `$id`,
+  so a consumer in another language can fetch it without installing anything
+  Python.
+- Reference envelope fixtures covering ordinary exceptions, explicit causes,
+  failure metadata, implicit contexts, nested exception groups, redaction,
+  truncation and cycles. Each is produced by running the real serializer over a
+  real exception, and CI fails if a committed fixture stops matching what the
+  serializer emits.
+- Compatibility tests that validate an emitted envelope against the schema for
+  every exception class the package defines, and that reject malformed
+  envelopes so the schema cannot quietly become vacuous.
+
+The envelope shape itself is unchanged here: this release writes down and tests
+the payload as it already stands. That payload has been emitted since 1.2.0 and
+reached its current shape in 1.4.0, having gained `exceptions` in 1.3.0 and
+`failure` in 1.4.0; schema 1.0.0 describes that shape. The schema is versioned
+separately from the package, and DataExcept still takes no runtime dependency on
+a validator — it publishes the contract rather than checking its own output.
+
+### Changed
+
+- `ParsingError.text` and `DeserializationError.data` are now optional, so
+  neither class requires the payload that caused the failure. Existing
+  positional calls are unaffected, and a payload that is passed is still kept
+  verbatim.
+- `ParsingError`'s generated message bounds the payload it quotes, so a large
+  malformed input no longer becomes a log line of the same size. The payload
+  itself remains in full on `.text`.
+
+### Fixed
+
+- A URL that ends a sentence no longer swallows the punctuation that ended it.
+  A full stop, colon, exclamation mark or question mark is legal inside a URL,
+  so the matcher ran through it and gave the character to the redacted URL:
+  `"fetch <url>: connection refused"` came back without its separator. The
+  match now runs through such characters but cannot end on one. Commas,
+  semicolons, brackets and quotes already terminated a match and are unchanged.
+
+## [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 +284,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 +666,9 @@ 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.5.0...HEAD
+[1.5.0]: https://github.com/DiogoRibeiro7/DataExcept/compare/v1.4.0...v1.5.0
+[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.5.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.5.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-06"

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: DataExcept
-Version: 1.3.0
+Version: 1.5.0
 Summary: A Python package providing structured, easily-extendable custom exception types.
 License-Expression: MIT
 License-File: LICENSE
@@ -45,6 +45,7 @@ Description-Content-Type: text/markdown
 - **🏗️ Hierarchical Structure**: Catch one specific error, a whole domain, or every operational error via `DataExceptError`
 - **📦 One Import**: Every exception is available from `dataexcept` directly, or from its domain module — same objects either way
 - **📊 Data Science Focused**: 100 exception classes covering ML pipelines, feature engineering, model training
+- **🧭 Language-neutral envelopes**: exceptions export to strict JSON against a published, versioned schema — so a non-Python consumer can validate what it receives
 - **🔧 Production Ready**: Logging helpers, error context, and exceptions that pickle — so they cross a process boundary with their message, attributes and cause intact
 - **📚 Academic Quality**: Proper documentation, type hints, and citation support
 - **🐍 Python 3.10 – 3.14**: Every supported version tested in CI, with full type safety
@@ -211,6 +212,24 @@ except Exception as exc:
     raise
 ```
 
+### Structured Error Envelopes
+
+```python
+from dataexcept import ValidationError, exception_to_json
+
+try:
+    validate_row(row)
+except ValidationError as exc:
+    # Strict JSON: identity, message, public attributes, failure metadata and
+    # the cause chain, with credential-bearing URLs already redacted.
+    logger.error(exception_to_json(exc, sort_keys=True))
+```
+
+The payload shape is a versioned, language-neutral contract, published as a
+[JSON Schema](https://diogoribeiro7.github.io/DataExcept/envelope_schema/) with
+reference fixtures, so a Node.js or Go consumer can be tested against the same
+document Python emits.
+
 ### Command Line Interface
 
 ```bash
@@ -364,6 +383,7 @@ through [SECURITY.md](SECURITY.md), not the public issue tracker.
 - **API Stability**: [What is public and what may change](https://diogoribeiro7.github.io/DataExcept/stability/)
 - **Upgrading from 0.x**: [Migration guide](https://diogoribeiro7.github.io/DataExcept/migration/)
 - **Advanced Usage**: [Advanced Guide](https://diogoribeiro7.github.io/DataExcept/advanced_usage/)
+- **Envelope Schema**: [The published envelope contract](https://diogoribeiro7.github.io/DataExcept/envelope_schema/)
 - **CLI Reference**: [CLI Guide](https://diogoribeiro7.github.io/DataExcept/cli/)
 - **Changelog**: [CHANGELOG.md](CHANGELOG.md)
 

{dataexcept-1.3.0 → dataexcept-1.5.0}/README.md

@@ -18,6 +18,7 @@
 - **🏗️ Hierarchical Structure**: Catch one specific error, a whole domain, or every operational error via `DataExceptError`
 - **📦 One Import**: Every exception is available from `dataexcept` directly, or from its domain module — same objects either way
 - **📊 Data Science Focused**: 100 exception classes covering ML pipelines, feature engineering, model training
+- **🧭 Language-neutral envelopes**: exceptions export to strict JSON against a published, versioned schema — so a non-Python consumer can validate what it receives
 - **🔧 Production Ready**: Logging helpers, error context, and exceptions that pickle — so they cross a process boundary with their message, attributes and cause intact
 - **📚 Academic Quality**: Proper documentation, type hints, and citation support
 - **🐍 Python 3.10 – 3.14**: Every supported version tested in CI, with full type safety
@@ -184,6 +185,24 @@ except Exception as exc:
     raise
 ```
 
+### Structured Error Envelopes
+
+```python
+from dataexcept import ValidationError, exception_to_json
+
+try:
+    validate_row(row)
+except ValidationError as exc:
+    # Strict JSON: identity, message, public attributes, failure metadata and
+    # the cause chain, with credential-bearing URLs already redacted.
+    logger.error(exception_to_json(exc, sort_keys=True))
+```
+
+The payload shape is a versioned, language-neutral contract, published as a
+[JSON Schema](https://diogoribeiro7.github.io/DataExcept/envelope_schema/) with
+reference fixtures, so a Node.js or Go consumer can be tested against the same
+document Python emits.
+
 ### Command Line Interface
 
 ```bash
@@ -337,6 +356,7 @@ through [SECURITY.md](SECURITY.md), not the public issue tracker.
 - **API Stability**: [What is public and what may change](https://diogoribeiro7.github.io/DataExcept/stability/)
 - **Upgrading from 0.x**: [Migration guide](https://diogoribeiro7.github.io/DataExcept/migration/)
 - **Advanced Usage**: [Advanced Guide](https://diogoribeiro7.github.io/DataExcept/advanced_usage/)
+- **Envelope Schema**: [The published envelope contract](https://diogoribeiro7.github.io/DataExcept/envelope_schema/)
 - **CLI Reference**: [CLI Guide](https://diogoribeiro7.github.io/DataExcept/cli/)
 - **Changelog**: [CHANGELOG.md](CHANGELOG.md)
 

{dataexcept-1.3.0 → dataexcept-1.5.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,
@@ -153,6 +154,11 @@ from .pipeline_exceptions import (
     TimeDeltaTooLargeError,
     TypeCheckError,
 )
+from .schema import (
+    ENVELOPE_SCHEMA_ID,
+    ENVELOPE_SCHEMA_VERSION,
+    envelope_schema,
+)
 from .security_exceptions import (
     DecryptionError,
     EncryptionError,
@@ -163,13 +169,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 +272,17 @@ __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.
+    "ENVELOPE_SCHEMA_ID",
+    "ENVELOPE_SCHEMA_VERSION",
+    "envelope_schema",
     "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.5.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.5.0/dataexcept/_previews.py

@@ -0,0 +1,74 @@
+"""Bounded excerpts of a payload that failed to parse.
+
+A parsing failure happens on content the caller did not write and often did not
+choose: an API response, a queue message, a file from somewhere else. Storing
+the whole offending payload on the exception drags it into every log line,
+envelope and telemetry event that touches the failure -- including whatever
+credentials or personal data the payload happened to contain.
+
+The excerpt is the compromise. It is short enough to read in a log and long
+enough to show what the parser choked on, and because it is an ordinary string
+attribute it goes through the same URL redaction as every other public
+attribute on a DataExcept exception.
+"""
+
+from __future__ import annotations
+
+__all__ = ["MAX_PREVIEW_LENGTH", "TRUNCATION_MARKER", "bounded_preview"]
+
+#: Longest excerpt kept, in characters, counting the truncation marker. A
+#: caller who wants less can pass less; there is deliberately no way to ask for
+#: more, because the point of the field is that an untrusted payload cannot
+#: reach a log at its own length.
+MAX_PREVIEW_LENGTH = 200
+
+#: Appended when anything was cut, and only then.
+TRUNCATION_MARKER = "..."
+
+#: Bytes decoded before the excerpt is measured. Four is the longest a UTF-8
+#: character gets, so this always yields at least MAX_PREVIEW_LENGTH characters
+#: when the payload has them, without decoding a payload of any size.
+_BYTE_WINDOW = MAX_PREVIEW_LENGTH * 4
+
+
+def _as_text(value: str | bytes | bytearray) -> tuple[str, bool]:
+    """Return *value* as text, and whether reading it already cut something."""
+    if isinstance(value, str):
+        return value, False
+    head = bytes(value[:_BYTE_WINDOW])
+    # backslashreplace, not replace: an excerpt of a malformed payload is a
+    # best effort by definition and must not fail where the parser did, but it
+    # should stay printable. U+FFFD is neither readable nor writable on a
+    # console that is not UTF-8, while `\xff` says which byte was wrong.
+    return head.decode("utf-8", errors="backslashreplace"), len(value) > len(head)
+
+
+def bounded_preview(value: str | bytes | bytearray | None) -> str | None:
+    r"""Return at most :data:`MAX_PREVIEW_LENGTH` characters of *value*.
+
+    ``None`` gives ``None``: no excerpt was asked for. Bytes are decoded as
+    UTF-8, with any undecodable byte shown as ``\xNN``.
+    :data:`TRUNCATION_MARKER` is appended when, and only when, something was
+    left out, and the result stays within the bound either way.
+
+    The bound is on the payload. Redaction runs afterwards, over this value as
+    over every other public attribute, and a credential shorter than its
+    replacement makes the stored string a few characters longer. Chasing an
+    exact count through a pass whose job is to remove secrets rather than
+    preserve lengths would buy nothing: the excerpt is bounded so that an
+    untrusted payload cannot reach a log at its own size, and it does that.
+    """
+    if value is None:
+        return None
+    if not isinstance(value, (str, bytes, bytearray)):
+        raise TypeError(
+            f"preview must be str, bytes, or None, got {type(value).__name__}"
+        )
+
+    text, truncated = _as_text(value)
+    if not truncated and len(text) <= MAX_PREVIEW_LENGTH:
+        return text
+    # Something was left out, whether by the decode window or by length. Cut
+    # short enough for the marker to fit inside the bound rather than on top of
+    # it: a documented maximum the value can exceed is not a maximum.
+    return text[: MAX_PREVIEW_LENGTH - len(TRUNCATION_MARKER)] + TRUNCATION_MARKER

{dataexcept-1.3.0 → dataexcept-1.5.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.5.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.5.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.5.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)