DataExcept 1.0.0__tar.gz → 1.2.0__tar.gz

{dataexcept-1.0.0 → dataexcept-1.2.0}/CHANGELOG.md

@@ -7,6 +7,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.2.0] - 2026-09-02
+
+### Added
+
+- **`exception_to_dict` and `exception_to_json`** provide a stable, strict
+  JSON-safe envelope for exceptions crossing API, queue, telemetry and
+  structured-log boundaries. The envelope preserves type, module, rendered
+  message, public attributes and bounded cause/context chains.
+- Structured export degrades hostile or unserialisable values safely, converts
+  non-finite floats and byte payloads to text, marks cycles and depth
+  truncation, and excludes traceback frames and private attributes.
+- Export uses a stricter redaction boundary than ordinary exception rendering:
+  credential-bearing URL paths are removed as well as sensitive query and
+  fragment values, including in third-party causes, mapping keys and arbitrary
+  attribute representations.
+
+## [1.1.0] - 2026-09-02
+
+### Added
+
+- **`wrap` and `wrapping`**, for turning a third-party exception into a
+  DataExcept one:
+
+  ```python
+  with wrapping(OSError, DataLoadingError, source=path):
+      frame = pd.read_csv(path)
+  ```
+
+  The hand-written form is easy to get subtly wrong: a missing `from exc` loses
+  the traceback, the original passed to the wrong parameter is not recorded,
+  and a broad `except` relabels a `KeyboardInterrupt` as a data error. These
+  settle the wiring — the original goes to whichever constructor parameter
+  takes a cause (`original`, `original_exception` or `cause`) and is set as
+  `__cause__` either way, which matters because only 17 of the 100 classes
+  record one on an attribute.
+- Guidance in the advanced usage guide on building a project-specific
+  hierarchy on these bases, and what deriving from a domain root gets you.
+
 ## [1.0.0] - 2026-08-25
 
 First stable release. The public API is frozen; see the
@@ -509,7 +547,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.0.0...HEAD
+[Unreleased]: https://github.com/DiogoRibeiro7/DataExcept/compare/v1.2.0...HEAD
+[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
 [1.0.0]: https://github.com/DiogoRibeiro7/DataExcept/compare/v0.4.3...v1.0.0
 [0.4.3]: https://github.com/DiogoRibeiro7/DataExcept/compare/v0.4.2...v0.4.3
 [0.4.2]: https://github.com/DiogoRibeiro7/DataExcept/compare/v0.4.1...v0.4.2

{dataexcept-1.0.0 → dataexcept-1.2.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.0.0"
+version: "1.2.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-08-25"
+date-released: "2026-09-02"

{dataexcept-1.0.0 → dataexcept-1.2.0}/PKG-INFO

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

{dataexcept-1.0.0 → dataexcept-1.2.0}/dataexcept/__init__.py

@@ -159,6 +159,8 @@ from .security_exceptions import (
     InvalidTokenError,
     SecurityError,
 )
+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
@@ -266,6 +268,12 @@ __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",

dataexcept-1.2.0/dataexcept/serialization.py

@@ -0,0 +1,216 @@
+"""Strict JSON-safe structured representations of exceptions."""
+
+from __future__ import annotations
+
+import json
+import math
+from collections.abc import Mapping, Sequence, Set
+from typing import Any
+
+from .redaction import redact_urls_in_text
+
+__all__ = ["exception_to_dict", "exception_to_json"]
+
+_MAX_VALUE_DEPTH = 8
+_NOT_SCALAR = object()
+
+
+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.
+    """
+    return redact_urls_in_text(text, keep_path=False)
+
+
+def _safe_text(value: Any) -> str:
+    """Render *value* without raising and scrub credential-bearing URLs."""
+    try:
+        text = str(value)
+    except Exception:
+        try:
+            text = f"<unrepresentable {type(value).__name__}>"
+        except Exception:  # pragma: no cover - hostile type metadata
+            text = "<unrepresentable>"
+    return _redact_export_text(text)
+
+
+def _safe_key(value: Any) -> str:
+    if isinstance(value, str):
+        return _redact_export_text(value)
+    return _safe_text(value)
+
+
+def _safe_scalar(value: Any) -> Any:
+    if value is None or isinstance(value, (bool, int)):
+        return value
+    if isinstance(value, float):
+        return value if math.isfinite(value) else str(value)
+    if isinstance(value, str):
+        return _redact_export_text(value)
+    if isinstance(value, (bytes, bytearray)):
+        return _safe_text(value)
+    return _NOT_SCALAR
+
+
+def _safe_mapping(value: Mapping[Any, Any], *, depth: int, seen: set[int]) -> Any:
+    identity = id(value)
+    seen.add(identity)
+    try:
+        return {
+            _safe_key(key): _json_safe(item, depth=depth + 1, seen=seen)
+            for key, item in value.items()
+        }
+    except Exception:
+        return _safe_text(value)
+    finally:
+        seen.discard(identity)
+
+
+def _safe_collection(
+    value: Sequence[Any] | Set[Any], *, depth: int, seen: set[int]
+) -> Any:
+    identity = id(value)
+    seen.add(identity)
+    try:
+        return [_json_safe(item, depth=depth + 1, seen=seen) for item in value]
+    except Exception:
+        return _safe_text(value)
+    finally:
+        seen.discard(identity)
+
+
+def _json_safe(value: Any, *, depth: int = 0, seen: set[int] | None = None) -> Any:
+    """Return *value* in a strict JSON-safe form without raising."""
+    if seen is None:
+        seen = set()
+    scalar = _safe_scalar(value)
+    if scalar is not _NOT_SCALAR:
+        return scalar
+    if depth >= _MAX_VALUE_DEPTH:
+        return "<truncated>"
+    if id(value) in seen:
+        return "<cycle>"
+    if isinstance(value, Mapping):
+        return _safe_mapping(value, depth=depth, seen=seen)
+    if isinstance(value, (Sequence, Set)):
+        return _safe_collection(value, depth=depth, seen=seen)
+    return _safe_text(value)
+
+
+def _attributes(exc: BaseException) -> dict[str, Any]:
+    """Return public instance attributes in a JSON-safe representation."""
+    try:
+        state = vars(exc)
+        result: dict[str, Any] = {}
+        for name, value in state.items():
+            if not isinstance(name, str) or name.startswith("_"):
+                continue
+            result[name] = _json_safe(value)
+        return result
+    except Exception:
+        # This code runs at an error-transport boundary. A hostile __dict__,
+        # custom mapping, iterator or key must not replace the original failure
+        # with a serialization failure.
+        return {}
+
+
+def _exception_record(
+    exc: BaseException,
+    *,
+    include_attributes: bool,
+    max_depth: int,
+    depth: int,
+    seen: set[int],
+) -> dict[str, Any]:
+    if depth > max_depth:
+        return {"truncated": True}
+
+    identity = id(exc)
+    if identity in seen:
+        return {
+            "type": type(exc).__name__,
+            "module": type(exc).__module__,
+            "message": _safe_text(exc),
+            "cycle": True,
+        }
+
+    seen.add(identity)
+    record: dict[str, Any] = {
+        "type": type(exc).__name__,
+        "module": type(exc).__module__,
+        "message": _safe_text(exc),
+    }
+    if include_attributes:
+        attributes = _attributes(exc)
+        if attributes:
+            record["attributes"] = attributes
+
+    if exc.__cause__ is not None:
+        record["cause"] = _exception_record(
+            exc.__cause__,
+            include_attributes=include_attributes,
+            max_depth=max_depth,
+            depth=depth + 1,
+            seen=seen,
+        )
+    if exc.__context__ is not None and not exc.__suppress_context__:
+        record["context"] = _exception_record(
+            exc.__context__,
+            include_attributes=include_attributes,
+            max_depth=max_depth,
+            depth=depth + 1,
+            seen=seen,
+        )
+
+    seen.discard(identity)
+    return record
+
+
+def exception_to_dict(
+    exc: BaseException,
+    *,
+    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, and bounded cause/context
+    chains. Traceback frames and private attributes are deliberately excluded.
+    """
+    if not isinstance(exc, BaseException):
+        raise TypeError("exc must be an exception instance")
+    if not isinstance(max_depth, int) or isinstance(max_depth, bool):
+        raise TypeError("max_depth must be an integer")
+    if max_depth < 0:
+        raise ValueError("max_depth must be non-negative")
+    return _exception_record(
+        exc,
+        include_attributes=include_attributes,
+        max_depth=max_depth,
+        depth=0,
+        seen=set(),
+    )
+
+
+def exception_to_json(
+    exc: BaseException,
+    *,
+    include_attributes: bool = True,
+    max_depth: int = 8,
+    **json_kwargs: Any,
+) -> str:
+    """Return :func:`exception_to_dict` encoded as strict JSON."""
+    json_kwargs["allow_nan"] = False
+    return json.dumps(
+        exception_to_dict(
+            exc,
+            include_attributes=include_attributes,
+            max_depth=max_depth,
+        ),
+        **json_kwargs,
+    )

dataexcept-1.2.0/dataexcept/wrapping.py

@@ -0,0 +1,103 @@
+"""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

{dataexcept-1.0.0 → dataexcept-1.2.0}/pyproject.toml

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