DataExcept 1.1.0__tar.gz → 1.2.0__tar.gz

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

@@ -7,6 +7,22 @@ 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
@@ -531,7 +547,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.1.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

{dataexcept-1.1.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.1.0"
+version: "1.2.0"
 authors:
   - family-names: "Ribeiro"
     given-names: "Diogo"

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

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

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

@@ -159,6 +159,7 @@ from .security_exceptions import (
     InvalidTokenError,
     SecurityError,
 )
+from .serialization import exception_to_dict, exception_to_json
 from .wrapping import wrap, wrapping
 
 __all__ = [
@@ -270,6 +271,9 @@ __all__ = [
     # 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.1.0 → dataexcept-1.2.0}/pyproject.toml

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