python-corekit 0.4.0__tar.gz → 0.4.1__tar.gz

{python_corekit-0.4.0 → python_corekit-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-corekit
-Version: 0.4.0
+Version: 0.4.1
 Summary: Shared foundations for Python projects: logging, benchmarking, registries, FastAPI application and routers, SQL statements and migrations, background tasks, ETL, and LLM chat/tool primitives
 Author: Steven Jacobsen
 License-Expression: MIT
@@ -90,6 +90,29 @@ class Report(Benchmarkable):
         self.timing("queried")   # logs the time since the previous split
 ```
 
+## Exceptionator
+
+Catch an exception, run one action, then rethrow so the existing failure path
+still happens. Built-in actions are no-op and log-traceback; apps supply their
+own (persist, notify, …).
+
+```python
+from corekit.exceptionator import (
+    Exceptionator,
+    ExceptionatorMiddleware,
+    LogTracebackAction,
+    install_run_task_hook,
+    set_process_exceptionator,
+)
+
+exceptionator = Exceptionator(LogTracebackAction(), service="api")
+set_process_exceptionator(exceptionator)
+install_run_task_hook(exceptionator)  # optional; run_task captures with task name
+```
+
+`ExceptionatorMiddleware` is raw ASGI (not `BaseHTTPMiddleware`). With no
+`run_task` hook installed, jobs behave as in 0.4.0.
+
 ## Assembling an application
 
 `Application` is a plain `FastAPI` subclass — every constructor argument,

{python_corekit-0.4.0 → python_corekit-0.4.1}/README.md

@@ -54,6 +54,29 @@ class Report(Benchmarkable):
         self.timing("queried")   # logs the time since the previous split
 ```
 
+## Exceptionator
+
+Catch an exception, run one action, then rethrow so the existing failure path
+still happens. Built-in actions are no-op and log-traceback; apps supply their
+own (persist, notify, …).
+
+```python
+from corekit.exceptionator import (
+    Exceptionator,
+    ExceptionatorMiddleware,
+    LogTracebackAction,
+    install_run_task_hook,
+    set_process_exceptionator,
+)
+
+exceptionator = Exceptionator(LogTracebackAction(), service="api")
+set_process_exceptionator(exceptionator)
+install_run_task_hook(exceptionator)  # optional; run_task captures with task name
+```
+
+`ExceptionatorMiddleware` is raw ASGI (not `BaseHTTPMiddleware`). With no
+`run_task` hook installed, jobs behave as in 0.4.0.
+
 ## Assembling an application
 
 `Application` is a plain `FastAPI` subclass — every constructor argument,

python_corekit-0.4.1/corekit/exceptionator/__init__.py

@@ -0,0 +1,68 @@
+"""
+Process-wide exception capture: catch, run one action, rethrow.
+
+Product concerns (Postgres, ntfy, prompts) stay in the installing application.
+This package owns the wrapper, built-in actions, fingerprinting, ASGI middleware,
+and the ``run_task`` hook point.
+"""
+
+from corekit.exceptionator.actions import (
+    ExceptionatorAction,
+    LogTracebackAction,
+    NoOpAction,
+)
+from corekit.exceptionator.asgi import (
+    ExceptionatorMiddleware,
+    get_process_exceptionator,
+    record_http_exception,
+    set_process_exceptionator,
+    should_record_http_exception,
+)
+from corekit.exceptionator.exceptionator import Exceptionator
+from corekit.exceptionator.fingerprint import ExceptionFingerprint, ExceptionText
+from corekit.exceptionator.guard import (
+    begin_handling,
+    end_handling,
+    handling_active,
+    is_captured,
+    mark_captured,
+)
+from corekit.exceptionator.jobs import (
+    clear_run_task_hook,
+    get_run_task_hook,
+    install_run_task_hook,
+)
+from corekit.exceptionator.models import (
+    CapturedException,
+    ExceptionatorActionName,
+    ExceptionContext,
+    ExceptionSource,
+    build_captured,
+)
+
+__all__ = [
+    "CapturedException",
+    "ExceptionContext",
+    "ExceptionFingerprint",
+    "ExceptionSource",
+    "ExceptionText",
+    "Exceptionator",
+    "ExceptionatorAction",
+    "ExceptionatorActionName",
+    "ExceptionatorMiddleware",
+    "LogTracebackAction",
+    "NoOpAction",
+    "begin_handling",
+    "build_captured",
+    "clear_run_task_hook",
+    "end_handling",
+    "get_process_exceptionator",
+    "get_run_task_hook",
+    "handling_active",
+    "install_run_task_hook",
+    "is_captured",
+    "mark_captured",
+    "record_http_exception",
+    "set_process_exceptionator",
+    "should_record_http_exception",
+]

python_corekit-0.4.1/corekit/exceptionator/actions.py

@@ -0,0 +1,46 @@
+"""
+Built-in Exceptionator actions.
+"""
+
+from __future__ import annotations
+
+from corekit.exceptionator.models import CapturedException
+from corekit.observability.loggable import Loggable
+
+__all__ = ["ExceptionatorAction", "LogTracebackAction", "NoOpAction"]
+
+
+class ExceptionatorAction(Loggable):
+    """
+    Work performed after an exception is captured and before it continues.
+    """
+
+    def run(self, captured: CapturedException) -> None:
+        """
+        Perform the action. Must not raise.
+        """
+        raise NotImplementedError
+
+
+class NoOpAction(ExceptionatorAction):
+    """
+    Catch and continue. Records nothing and publishes nothing.
+    """
+
+    def run(self, captured: CapturedException) -> None:
+        """
+        Do nothing with the captured exception.
+        """
+        return None
+
+
+class LogTracebackAction(ExceptionatorAction):
+    """
+    Write the message and traceback. Does not store or notify.
+    """
+
+    def run(self, captured: CapturedException) -> None:
+        """
+        Log the incident text.
+        """
+        self.error(f"{captured.service} {captured.exception_type}: {captured.message}\n{captured.traceback_text}")

python_corekit-0.4.1/corekit/exceptionator/asgi.py

@@ -0,0 +1,115 @@
+"""
+ASGI middleware and HTTP helpers for Exceptionator.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from fastapi import Request
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+from starlette.exceptions import HTTPException
+from starlette.websockets import WebSocketDisconnect
+
+from corekit.exceptionator.exceptionator import Exceptionator
+from corekit.exceptionator.models import ExceptionContext, ExceptionSource
+
+__all__ = [
+    "ExceptionatorMiddleware",
+    "get_process_exceptionator",
+    "record_http_exception",
+    "set_process_exceptionator",
+    "should_record_http_exception",
+]
+
+ASGIApp = Callable[..., Awaitable[None]]
+
+_process_exceptionator: Exceptionator | None = None
+
+
+def set_process_exceptionator(exceptionator: Exceptionator) -> None:
+    """
+    Remember the process Exceptionator for middleware and HTTP handlers.
+    """
+    global _process_exceptionator
+    _process_exceptionator = exceptionator
+
+
+def get_process_exceptionator() -> Exceptionator:
+    """
+    The Exceptionator installed for this process.
+    """
+    if _process_exceptionator is None:
+        raise RuntimeError("No Exceptionator installed; call set_process_exceptionator first")
+    return _process_exceptionator
+
+
+def should_record_http_exception(exc: BaseException) -> bool:
+    """
+    Client errors and validation failures are not incidents. HTTP 500s are.
+    """
+    if isinstance(exc, RequestValidationError):
+        return False
+    if isinstance(exc, WebSocketDisconnect):
+        return False
+    status = getattr(exc, "status_code", None)
+    if isinstance(exc, HTTPException) and isinstance(status, int) and status < 500:
+        return False
+    return True
+
+
+class ExceptionatorMiddleware:
+    """
+    ASGI middleware that records unhandled HTTP failures and rethrows them.
+
+    Not ``BaseHTTPMiddleware``: that wrapper breaks streaming and exception groups.
+    """
+
+    def __init__(self, app: ASGIApp, exceptionator: Exceptionator | None = None) -> None:
+        self.app = app
+        self._exceptionator = exceptionator
+
+    async def __call__(self, scope: dict[str, Any], receive: Any, send: Any) -> None:
+        if scope.get("type") != "http":
+            await self.app(scope, receive, send)
+            return
+        try:
+            await self.app(scope, receive, send)
+        except Exception as exc:
+            if should_record_http_exception(exc):
+                self._resolve().capture(
+                    exc,
+                    context=ExceptionContext(
+                        source=ExceptionSource.HTTP,
+                        http_method=scope.get("method"),
+                        http_path=scope.get("path"),
+                    ),
+                )
+            raise
+
+    def _resolve(self) -> Exceptionator:
+        if self._exceptionator is not None:
+            return self._exceptionator
+        return get_process_exceptionator()
+
+
+def record_http_exception(request: Request, exc: HTTPException) -> JSONResponse:
+    """
+    Store HTTP 500s, then return the same JSON body FastAPI would have sent.
+
+    Starlette answers ``HTTPException`` inside the router, so the ASGI middleware
+    never sees it. 4xx responses are returned unchanged and are not incidents.
+    """
+    if should_record_http_exception(exc):
+        get_process_exceptionator().capture(
+            exc,
+            context=ExceptionContext(
+                source=ExceptionSource.HTTP,
+                http_method=request.method,
+                http_path=request.url.path,
+            ),
+        )
+    headers = getattr(exc, "headers", None)
+    return JSONResponse(status_code=exc.status_code, content={"detail": exc.detail}, headers=headers)

python_corekit-0.4.1/corekit/exceptionator/constants.py

@@ -0,0 +1,7 @@
+"""
+Limits shared by every Exceptionator install.
+"""
+
+MESSAGE_MAX_CHARS = 2_000
+TRACEBACK_MAX_CHARS = 32_000
+FINGERPRINT_FRAMES = 8

python_corekit-0.4.1/corekit/exceptionator/exceptionator.py

@@ -0,0 +1,62 @@
+"""
+Catch an exception, run one action, and let the caller rethrow.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+
+from corekit.exceptionator.actions import ExceptionatorAction
+from corekit.exceptionator.guard import (
+    begin_handling,
+    end_handling,
+    handling_active,
+    is_captured,
+    mark_captured,
+)
+from corekit.exceptionator.models import CapturedException, ExceptionContext, build_captured
+from corekit.observability.loggable import Loggable
+
+__all__ = ["Exceptionator"]
+
+
+class Exceptionator(Loggable):
+    """
+    Catch an exception, run the configured action, and let the caller rethrow.
+
+    ``guard`` rethrows. ``capture`` runs the same action and returns, for a
+    caller that has already decided to swallow the error.
+    """
+
+    def __init__(self, action: ExceptionatorAction, *, service: str) -> None:
+        super().__init__()
+        self._action = action
+        self.service = service
+
+    @contextmanager
+    def guard(self, context: ExceptionContext | None = None) -> Iterator[None]:
+        """
+        Run the action when the block raises, then rethrow the original exception.
+        """
+        try:
+            yield
+        except Exception as exc:
+            self.capture(exc, context=context)
+            raise
+
+    def capture(self, exc: BaseException, *, context: ExceptionContext | None = None) -> None:
+        """
+        Run the action once for this exception. Later calls on the same object no-op.
+        """
+        if handling_active() or is_captured(exc):
+            return
+        token = begin_handling()
+        try:
+            captured: CapturedException = build_captured(exc, service=self.service, context=context)
+            mark_captured(exc)
+            self._action.run(captured)
+        except Exception:
+            self.exception("Exceptionator failed while recording an exception")
+        finally:
+            end_handling(token)

python_corekit-0.4.1/corekit/exceptionator/fingerprint.py

@@ -0,0 +1,86 @@
+"""
+Identity for an exception based on its type and innermost frames.
+
+The message is left out so ids embedded in the text do not split one bug into
+many fingerprints.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import traceback
+from types import TracebackType
+from typing import ClassVar
+
+from corekit.exceptionator.constants import FINGERPRINT_FRAMES
+from corekit.utils.text import truncate
+
+__all__ = ["ExceptionFingerprint", "ExceptionText"]
+
+
+class ExceptionText:
+    """
+    Backend text extracted from an exception.
+    """
+
+    @staticmethod
+    def message(exc: BaseException) -> str:
+        """
+        Backend message. Public exceptions stringify to user copy, so prefer ``for_log``.
+        """
+        for_log = getattr(exc, "for_log", None)
+        if callable(for_log):
+            try:
+                return str(for_log())
+            except Exception:
+                return str(exc)
+        return str(exc)
+
+    @staticmethod
+    def first_line(text: str, limit: int) -> str:
+        """
+        The first line of ``text``, truncated to ``limit`` characters.
+        """
+        line = text.splitlines()[0] if text else ""
+        return truncate(line, limit)
+
+
+class ExceptionFingerprint:
+    """
+    Stable identity for an exception based on its type and innermost frames.
+    """
+
+    path_markers: ClassVar[tuple[str, ...]] = ()
+
+    def of(self, exc: BaseException) -> str:
+        """
+        Hash the exception type plus the innermost stack frames.
+        """
+        frames = traceback.extract_tb(exc.__traceback__)[-FINGERPRINT_FRAMES:]
+        parts = [type(exc).__qualname__]
+        for frame in frames:
+            parts.append(f"{self.normalize_path(frame.filename)}|{frame.name}|{frame.lineno}")
+        return hashlib.sha256("\n".join(parts).encode()).hexdigest()
+
+    @classmethod
+    def normalize_path(cls, filename: str) -> str:
+        """
+        Drop machine-specific prefixes so a container path and a checkout match.
+        """
+        normalized = filename.replace("\\", "/")
+        for marker in cls.path_markers:
+            index = normalized.find(marker)
+            if index >= 0:
+                return normalized[index:]
+        parts = [part for part in normalized.split("/") if part]
+        if not parts:
+            return normalized
+        return "/".join(parts[-2:])
+
+    @staticmethod
+    def format_traceback(exc: BaseException) -> str:
+        """
+        Render the traceback text for storage.
+        """
+        tb: TracebackType | None = exc.__traceback__
+        return "".join(traceback.format_exception(type(exc), exc, tb))

python_corekit-0.4.1/corekit/exceptionator/guard.py

@@ -0,0 +1,53 @@
+"""
+ContextVar and per-exception marker so one failure is recorded once.
+"""
+
+from __future__ import annotations
+
+from contextvars import ContextVar, Token
+
+__all__ = [
+    "begin_handling",
+    "end_handling",
+    "handling_active",
+    "is_captured",
+    "mark_captured",
+]
+
+CAPTURED_MARKER = "_exceptionator_captured"
+_handling: ContextVar[bool] = ContextVar("exceptionator_handling", default=False)
+
+
+def is_captured(exc: BaseException) -> bool:
+    """
+    Whether this exception object was already handed to an Exceptionator.
+    """
+    return bool(getattr(exc, CAPTURED_MARKER, False))
+
+
+def mark_captured(exc: BaseException) -> None:
+    """
+    Remember that this exception object has been handled.
+    """
+    setattr(exc, CAPTURED_MARKER, True)
+
+
+def handling_active() -> bool:
+    """
+    Whether this task is already inside the Exceptionator.
+    """
+    return _handling.get()
+
+
+def begin_handling() -> Token[bool]:
+    """
+    Mark this task as inside the Exceptionator. Pair with ``end_handling``.
+    """
+    return _handling.set(True)
+
+
+def end_handling(token: Token[bool]) -> None:
+    """
+    Leave the Exceptionator guard.
+    """
+    _handling.reset(token)

python_corekit-0.4.1/corekit/exceptionator/jobs.py

@@ -0,0 +1,52 @@
+"""
+Hook ``run_task`` calls after a task fails and before ``failure()``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING
+
+from corekit.exceptionator.models import ExceptionContext, ExceptionSource
+
+if TYPE_CHECKING:
+    from corekit.exceptionator.exceptionator import Exceptionator
+
+__all__ = ["clear_run_task_hook", "get_run_task_hook", "install_run_task_hook"]
+
+RunTaskHook = Callable[[str, BaseException], None]
+
+_hook: RunTaskHook | None = None
+
+
+def install_run_task_hook(exceptionator: Exceptionator) -> None:
+    """
+    Register ``exceptionator`` so ``run_task`` captures failures with the task name.
+
+    Passing the same instance again is a no-op. Call ``clear_run_task_hook`` to
+    remove it. With no hook registered, ``run_task`` behaves as it did before.
+    """
+    global _hook
+
+    def hook(task_name: str, exc: BaseException) -> None:
+        exceptionator.capture(
+            exc,
+            context=ExceptionContext(source=ExceptionSource.RQ, job_name=task_name),
+        )
+
+    _hook = hook
+
+
+def clear_run_task_hook() -> None:
+    """
+    Remove any ``run_task`` capture hook.
+    """
+    global _hook
+    _hook = None
+
+
+def get_run_task_hook() -> RunTaskHook | None:
+    """
+    The hook ``run_task`` should call, or ``None``.
+    """
+    return _hook

python_corekit-0.4.1/corekit/exceptionator/models.py

@@ -0,0 +1,98 @@
+"""
+Values every Exceptionator action receives.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from corekit.exceptionator.constants import MESSAGE_MAX_CHARS, TRACEBACK_MAX_CHARS
+from corekit.exceptionator.fingerprint import ExceptionFingerprint, ExceptionText
+from corekit.schemas import StringEnum
+from corekit.utils.text import truncate
+
+__all__ = [
+    "CapturedException",
+    "ExceptionContext",
+    "ExceptionSource",
+    "ExceptionatorActionName",
+    "build_captured",
+]
+
+_fingerprint = ExceptionFingerprint()
+
+
+class ExceptionatorActionName(StringEnum):
+    """
+    Built-in action names. Apps may define additional string names for custom actions.
+    """
+
+    NOOP = "noop"
+    LOG = "log"
+    PERSIST_AND_NOTIFY = "persist_and_notify"
+
+
+class ExceptionSource(StringEnum):
+    """
+    Which process boundary captured the exception.
+    """
+
+    HTTP = "http"
+    RQ = "rq"
+    DISCORD = "discord"
+    TASK = "task"
+
+
+class ExceptionContext(BaseModel):
+    """
+    Where an exception was caught, plus whatever the boundary already knows.
+    """
+
+    source: ExceptionSource = ExceptionSource.TASK
+    http_method: str | None = None
+    http_path: str | None = None
+    job_name: str | None = None
+    extra: dict[str, Any] = Field(default_factory=dict)
+
+
+@dataclass
+class CapturedException:
+    """
+    One incident, ready for an action. Not a database row.
+    """
+
+    service: str
+    exception_type: str
+    message: str
+    traceback_text: str
+    fingerprint: str
+    context: ExceptionContext
+    exc: BaseException = field(repr=False)
+
+
+def build_captured(
+    exc: BaseException,
+    *,
+    service: str,
+    context: ExceptionContext | None = None,
+) -> CapturedException:
+    """
+    Truncate an exception into the object actions receive.
+
+    Product code that stores the text should redact secrets before writing.
+    """
+    resolved = context or ExceptionContext()
+    message = ExceptionText.message(exc)
+    traceback_text = ExceptionFingerprint.format_traceback(exc)
+    return CapturedException(
+        service=service,
+        exception_type=type(exc).__qualname__,
+        message=truncate(message, MESSAGE_MAX_CHARS),
+        traceback_text=truncate(traceback_text, TRACEBACK_MAX_CHARS, suffix="\n… truncated"),
+        fingerprint=_fingerprint.of(exc),
+        context=resolved,
+        exc=exc,
+    )