lucidlog 0.1.0__py3-none-any.whl

lucidlog/__init__.py

@@ -0,0 +1,37 @@
+"""LucidLog public API."""
+
+from .api import (
+    clear_diagnostic_rules,
+    diagnose,
+    exception,
+    get_registered_rules,
+    install,
+    log_exception,
+    register_diagnostic_rule,
+    render_diagnostic,
+    render_exception,
+    uninstall,
+)
+from .config import Config, default_config
+from .rules import DiagnosticRule, clear_rules, list_rules, register_rule
+
+__all__ = [
+    "Config",
+    "DiagnosticRule",
+    "clear_diagnostic_rules",
+    "clear_rules",
+    "default_config",
+    "diagnose",
+    "exception",
+    "get_registered_rules",
+    "install",
+    "list_rules",
+    "log_exception",
+    "register_diagnostic_rule",
+    "register_rule",
+    "render_diagnostic",
+    "render_exception",
+    "uninstall",
+]
+
+__version__ = "0.1.0"

lucidlog/api.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+import logging
+import sys
+import traceback
+from typing import TextIO
+
+from .config import Config, default_config
+from .diagnosis import build_diagnostic
+from .models import Diagnostic
+from .redaction import sanitize_text
+from .render import render_diagnostic as _render_diagnostic
+from .rules import DiagnosticRule, clear_rules, list_rules, register_rule
+
+_previous_excepthook = None
+_installed = False
+_installed_config = default_config()
+
+
+def diagnose(exc: BaseException, *, config: Config | None = None) -> Diagnostic:
+    return build_diagnostic(exc, config=config)
+
+
+def register_diagnostic_rule(rule: DiagnosticRule) -> None:
+    register_rule(rule)
+
+
+def clear_diagnostic_rules() -> None:
+    clear_rules()
+
+
+def get_registered_rules() -> tuple[DiagnosticRule, ...]:
+    return list_rules()
+
+
+def _handle_uncaught(exc_type, exc_value, exc_traceback) -> None:
+    global _previous_excepthook
+    try:
+        diagnostic = build_diagnostic(exc_value, config=_installed_config)
+        _render_diagnostic(
+            diagnostic,
+            full=_installed_config.include_full_traceback,
+            stream=_installed_config.output_stream,
+            color=_installed_config.color,
+        )
+    except BaseException:
+        if _previous_excepthook is not None:
+            _previous_excepthook(exc_type, exc_value, exc_traceback)
+            return
+        traceback.print_exception(exc_type, exc_value, exc_traceback)
+
+
+def install(*, config: Config | None = None) -> None:
+    global _previous_excepthook, _installed, _installed_config
+    if _installed:
+        return
+    _installed_config = config or default_config()
+    _previous_excepthook = sys.excepthook
+    sys.excepthook = _handle_uncaught
+    _installed = True
+
+
+def uninstall() -> None:
+    global _previous_excepthook, _installed, _installed_config
+    if not _installed:
+        return
+    if sys.excepthook is _handle_uncaught:
+        sys.excepthook = _previous_excepthook
+    _previous_excepthook = None
+    _installed = False
+    _installed_config = default_config()
+
+
+def exception(
+    message: str | None = None,
+    *,
+    stream: TextIO | None = None,
+    full: bool = False,
+    config: Config | None = None,
+) -> Diagnostic:
+    exc = sys.exc_info()[1]
+    if exc is None:
+        raise RuntimeError("lucidlog.exception() must be called from within an active exception handler.")
+    selected_config = config or default_config()
+    diagnostic = build_diagnostic(exc, config=selected_config)
+    _render_diagnostic(
+        diagnostic,
+        full=full,
+        stream=stream if stream is not None else selected_config.output_stream,
+        color=selected_config.color,
+    )
+    if message:
+        target = stream if stream is not None else selected_config.output_stream
+        if target is None:
+            target = sys.stderr
+        target.write(sanitize_text(message, selected_config) + "\n")
+    return diagnostic
+
+
+def log_exception(
+    logger: logging.Logger,
+    message: str,
+    *,
+    full: bool = False,
+    config: Config | None = None,
+) -> Diagnostic:
+    exc = sys.exc_info()[1]
+    if exc is None:
+        raise RuntimeError("No active exception to log.")
+    selected_config = config or default_config()
+    diagnostic = build_diagnostic(exc, config=selected_config)
+    level = {
+        "critical": logging.CRITICAL,
+        "error": logging.ERROR,
+        "warning": logging.WARNING,
+        "info": logging.INFO,
+    }[diagnostic.severity]
+    logger.log(
+        level,
+        sanitize_text(message, selected_config),
+        extra={"lucidlog": diagnostic.to_dict(), "lucidlog_full": full},
+    )
+    return diagnostic
+
+
+def render_exception(
+    exc: BaseException,
+    *,
+    full: bool = False,
+    stream: TextIO | None = None,
+    color: bool | None = None,
+    config: Config | None = None,
+) -> str:
+    selected_config = config or default_config()
+    diagnostic = build_diagnostic(exc, config=selected_config)
+    return _render_diagnostic(
+        diagnostic,
+        full=full,
+        stream=stream if stream is not None else selected_config.output_stream,
+        color=selected_config.color if color is None else color,
+    )
+
+
+def render_diagnostic(
+    diag: Diagnostic,
+    *,
+    full: bool = False,
+    stream: TextIO | None = None,
+    color: bool | None = None,
+) -> str:
+    return _render_diagnostic(diag, full=full, stream=stream, color=color)

lucidlog/capture.py

@@ -0,0 +1,197 @@
+from __future__ import annotations
+
+import traceback
+import builtins
+from typing import Any
+
+from .config import Config, default_config
+from .models import DiagnosticCause, ExceptionContext, FrameInfo, SourceLine
+from .redaction import redact_path, sanitize_text
+from .source import read_source_context
+
+
+def _safe_message(exc: BaseException, config: Config) -> str:
+    try:
+        message = str(exc)
+    except BaseException:
+        message = "<exception message could not be rendered>"
+    return sanitize_text(message, config)
+
+
+def _build_frame(frame: traceback.FrameSummary, config: Config) -> FrameInfo:
+    source_line, context = read_source_context(
+        frame.filename,
+        frame.lineno,
+        context_lines=config.max_source_context,
+        max_file_bytes=config.max_source_file_bytes,
+    )
+    safe_context = tuple(
+        SourceLine(
+            line_number=line.line_number,
+            text=sanitize_text(line.text, config, limit=config.max_context_line_length),
+            is_error_line=line.is_error_line,
+            start_column=line.start_column,
+            end_column=line.end_column,
+        )
+        for line in context
+    )
+    return FrameInfo(
+        filename=sanitize_text(
+            redact_path(frame.filename, config),
+            config,
+            limit=config.max_message_length,
+        ),
+        line_number=frame.lineno,
+        function=sanitize_text(frame.name, config, limit=256),
+        source_line=(
+            sanitize_text(source_line, config, limit=config.max_context_line_length)
+            if source_line is not None
+            else None
+        ),
+        context=safe_context,
+    )
+
+
+def _group_members(exc: BaseException) -> tuple[BaseException, ...]:
+    group_type: Any = getattr(builtins, "BaseExceptionGroup", None)
+    if group_type is None or not isinstance(exc, group_type):
+        return ()
+    return tuple(exc.exceptions)
+
+
+def _capture_relationships(
+    exc: BaseException,
+    *,
+    config: Config,
+    seen: set[int],
+    budget: list[int],
+    depth: int = 0,
+) -> tuple[tuple[DiagnosticCause, ...], bool]:
+    if not config.include_exception_chain:
+        return (), False
+    if depth >= config.max_chain_depth:
+        return (), bool(exc.__cause__ or (exc.__context__ and not exc.__suppress_context__) or _group_members(exc))
+
+    related: list[DiagnosticCause] = []
+    truncated = False
+    next_exc = exc.__cause__
+    relation = "cause"
+    if next_exc is None and not exc.__suppress_context__:
+        next_exc = exc.__context__
+        relation = "context"
+    def related_exceptions():
+        if next_exc is not None:
+            yield next_exc, relation
+        for member in _group_members(exc):
+            yield member, "group_member"
+
+    for candidate_count, (child, child_relation) in enumerate(related_exceptions()):
+        if candidate_count >= config.max_group_exceptions:
+            truncated = True
+            break
+        child_id = id(child)
+        if child_id in seen or budget[0] >= config.max_group_exceptions:
+            truncated = True
+            continue
+        seen.add(child_id)
+        budget[0] += 1
+        tb = child.__traceback__
+        child_frames: tuple[FrameInfo, ...] = ()
+        location = "<unknown>"
+        if tb is not None:
+            extracted = traceback.extract_tb(tb, limit=-config.max_frames)
+            child_frames = tuple(_build_frame(frame, config) for frame in extracted)
+            if child_frames:
+                location = child_frames[-1].location
+        children, child_truncated = _capture_relationships(
+            child,
+            config=config,
+            seen=seen,
+            budget=budget,
+            depth=depth + 1,
+        )
+        related.append(
+            DiagnosticCause(
+                exception_type=type(child).__name__,
+                message=_safe_message(child, config),
+                location=location,
+                summary="Nested exception" if child_relation != "group_member" else "Exception group member",
+                relation=child_relation,
+                children=children,
+                frames=child_frames,
+            )
+        )
+        truncated = truncated or child_truncated
+    return tuple(related), truncated
+
+
+def _format_frame(frame: FrameInfo) -> list[str]:
+    lines = [f'  File "{frame.filename}", line {frame.line_number}, in {frame.function}']
+    if frame.source_line:
+        lines.append(f"    {frame.source_line.strip()}")
+    return lines
+
+
+def _format_cause(cause: DiagnosticCause, depth: int = 0) -> list[str]:
+    lines: list[str] = []
+    relation = {
+        "cause": "Caused by",
+        "context": "During handling of",
+        "group_member": "Exception group member",
+    }.get(cause.relation, "Related exception")
+    lines.append(f"{'  ' * depth}{relation}:")
+    for frame in cause.frames:
+        lines.extend(f"{'  ' * depth}{line}" for line in _format_frame(frame))
+    lines.append(f"{'  ' * depth}{cause.exception_type}: {cause.message}")
+    for child in cause.children:
+        lines.extend(_format_cause(child, depth + 1))
+    return lines
+
+
+def _format_traceback(
+    exception_type: str,
+    message: str,
+    frames: tuple[FrameInfo, ...],
+    causes: tuple[DiagnosticCause, ...],
+    config: Config,
+) -> str:
+    lines = ["Traceback (most recent call last):"]
+    for frame in frames:
+        lines.extend(_format_frame(frame))
+    lines.append(f"{exception_type}: {message}")
+    for cause in causes:
+        lines.extend(_format_cause(cause))
+    return sanitize_text("\n".join(lines), config, limit=config.max_traceback_chars)
+
+
+def capture_exception(exc: BaseException, *, config: Config | None = None) -> ExceptionContext:
+    config = config or default_config()
+    frames: list[FrameInfo] = []
+    if exc.__traceback__ is not None:
+        extracted = traceback.extract_tb(exc.__traceback__, limit=-config.max_frames)
+        frames = [_build_frame(frame, config) for frame in extracted]
+    primary_frame = frames[-1] if frames else None
+    causes, causes_truncated = _capture_relationships(
+        exc,
+        config=config,
+        seen={id(exc)},
+        budget=[0],
+    )
+    message = _safe_message(exc, config)
+    formatted_traceback = _format_traceback(
+        type(exc).__name__,
+        message,
+        tuple(frames),
+        causes,
+        config,
+    )
+    return ExceptionContext(
+        exception_type=type(exc).__name__,
+        message=message,
+        exception_mro=tuple(base.__name__ for base in type(exc).__mro__[1:]),
+        frames=tuple(frames),
+        primary_frame=primary_frame,
+        formatted_traceback=formatted_traceback,
+        causes=causes,
+        causes_truncated=causes_truncated,
+    )

lucidlog/config.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import re
+from typing import TextIO
+
+
+DEFAULT_REDACTION_PATTERNS = (
+    r"(?im)(authorization|cookie)\s*[:=]\s*[^\r\n]+",
+    r"""(?i)(password|passwd|pwd|secret|token|api[_-]?key|access[_-]?key)["']?\s*[:=]\s*(?:"[^"]*"|'[^']*'|[^\s,;}\]]+)""",
+    r"(?i)\b(bearer|basic)\s+[A-Za-z0-9._~+/-]+=*",
+    r"\b(?:gh[pousr]_[A-Za-z0-9_]{20,}|sk[-_](?:live|test)?[A-Za-z0-9_-]{16,}|xox[baprs]-[A-Za-z0-9-]{16,}|AIza[0-9A-Za-z_-]{20,})\b",
+    r"-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----[\s\S]*?-----END (?:RSA |EC |OPENSSH )?PRIVATE KEY-----",
+    r"(?i)\bAKIA[0-9A-Z]{16}\b",
+)
+
+
+@dataclass(frozen=True)
+class Config:
+    max_chain_depth: int = 4
+    max_source_context: int = 3
+    max_frames: int = 20
+    shorten_paths: bool = True
+    output_stream: TextIO | None = None
+    redact_patterns: tuple[str, ...] = DEFAULT_REDACTION_PATTERNS
+    redact_paths: bool = True
+    include_full_traceback: bool = False
+    max_message_length: int = 4096
+    include_exception_chain: bool = True
+    include_local_variables: bool = False
+    allow_network: bool = False
+    root_path: str | None = None
+    max_traceback_chars: int = 20000
+    max_group_exceptions: int = 20
+    max_context_line_length: int = 1000
+    max_source_file_bytes: int = 5000000
+    max_diagnosis_evidence: int = 20
+    color: bool | None = None
+
+    def __post_init__(self) -> None:
+        for name in (
+            "max_chain_depth",
+            "max_frames",
+            "max_message_length",
+            "max_traceback_chars",
+            "max_group_exceptions",
+            "max_context_line_length",
+            "max_source_file_bytes",
+            "max_diagnosis_evidence",
+        ):
+            value = getattr(self, name)
+            if isinstance(value, bool) or not isinstance(value, int):
+                raise TypeError(f"{name} must be an integer")
+            if value < 1:
+                raise ValueError(f"{name} must be at least 1")
+        if isinstance(self.max_source_context, bool) or not isinstance(self.max_source_context, int):
+            raise TypeError("max_source_context must be an integer")
+        if self.max_source_context < 0:
+            raise ValueError("max_source_context cannot be negative")
+        if not isinstance(self.redact_patterns, tuple) or not all(
+            isinstance(pattern, str) for pattern in self.redact_patterns
+        ):
+            raise TypeError("redact_patterns must be a tuple of strings")
+        for pattern in self.redact_patterns:
+            re.compile(pattern)
+        if self.color is not None and not isinstance(self.color, bool):
+            raise TypeError("color must be True, False, or None")
+        for name in (
+            "shorten_paths",
+            "redact_paths",
+            "include_full_traceback",
+            "include_exception_chain",
+            "include_local_variables",
+            "allow_network",
+        ):
+            if not isinstance(getattr(self, name), bool):
+                raise TypeError(f"{name} must be a boolean")
+        if self.include_local_variables:
+            raise ValueError("LucidLog does not capture local variables.")
+        if self.allow_network:
+            raise ValueError("The LucidLog core does not make network requests.")
+        if self.root_path is not None and not isinstance(self.root_path, str):
+            raise TypeError("root_path must be a string or None")
+        if self.output_stream is not None and not callable(getattr(self.output_stream, "write", None)):
+            raise TypeError("output_stream must provide a write() method")
+
+
+def default_config() -> Config:
+    return Config()

lucidlog/diagnosis.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+import hashlib
+from dataclasses import replace
+from itertools import islice
+
+from .capture import capture_exception
+from .config import Config, default_config
+from .models import Diagnostic, Diagnosis
+from .redaction import sanitize_text
+from .rules import diagnose_with_rules
+
+
+def severity_for_exception(exc: BaseException) -> str:
+    if isinstance(exc, Warning):
+        return "warning"
+    if isinstance(exc, (KeyboardInterrupt, SystemExit)) or type(exc).__name__ == "CancelledError":
+        return "info"
+    if isinstance(exc, (MemoryError, SystemError)):
+        return "critical"
+    members = getattr(exc, "exceptions", ())
+    if members:
+        if any(severity_for_exception(member) == "critical" for member in islice(members, 20)):
+            return "critical"
+        return "error"
+    return "error"
+
+
+def build_diagnostic(exc: BaseException, *, config: Config | None = None) -> Diagnostic:
+    config = config or default_config()
+    context = capture_exception(exc, config=config)
+    diagnosis = diagnose_with_rules(context)
+    if not isinstance(diagnosis, Diagnosis):
+        raise TypeError("A diagnostic rule must return a Diagnosis instance.")
+    if not all(
+        isinstance(value, str)
+        for value in (diagnosis.summary, diagnosis.explanation, diagnosis.confidence, diagnosis.origin)
+    ):
+        raise TypeError("A Diagnosis must use strings for its text fields.")
+    if diagnosis.suggestion is not None and not isinstance(diagnosis.suggestion, str):
+        raise TypeError("A Diagnosis suggestion must be a string or None.")
+    if not isinstance(diagnosis.evidence, tuple) or not all(
+        isinstance(item, str) for item in diagnosis.evidence
+    ):
+        raise TypeError("A Diagnosis evidence field must be a tuple of strings.")
+    if diagnosis.confidence not in {"low", "medium", "high"}:
+        raise ValueError("A Diagnosis confidence must be low, medium, or high.")
+    evidence = list(diagnosis.evidence[: config.max_diagnosis_evidence])
+    if len(diagnosis.evidence) > config.max_diagnosis_evidence:
+        evidence[-1] = "Additional rule evidence omitted due to configured limits."
+    diagnosis = replace(
+        diagnosis,
+        summary=sanitize_text(diagnosis.summary, config),
+        explanation=sanitize_text(diagnosis.explanation, config),
+        suggestion=(
+            sanitize_text(diagnosis.suggestion, config)
+            if diagnosis.suggestion is not None
+            else None
+        ),
+        confidence=sanitize_text(diagnosis.confidence, config, limit=64),
+        origin=sanitize_text(diagnosis.origin, config, limit=128),
+        evidence=tuple(sanitize_text(item, config) for item in evidence),
+    )
+    digest = hashlib.sha256()
+    location = context.primary_frame
+    fingerprint_parts = (
+        type(exc).__name__,
+        location.filename if location else "",
+        str(location.line_number) if location else "",
+        location.function if location else "",
+    )
+    digest.update(":".join(fingerprint_parts).encode("utf-8", errors="replace"))
+    diagnostic_id = digest.hexdigest()[:16]
+    return Diagnostic(
+        schema_version=1,
+        diagnostic_id=diagnostic_id,
+        exception_type=context.exception_type,
+        message=context.message,
+        frames=context.frames,
+        primary_frame=context.primary_frame,
+        causes=context.causes,
+        diagnosis=diagnosis,
+        formatted_traceback=context.formatted_traceback,
+        severity=severity_for_exception(exc),
+        causes_truncated=context.causes_truncated,
+    )

lucidlog/integrations/__init__.py

@@ -0,0 +1 @@
+"""Runtime integrations for LucidLog."""

lucidlog/integrations/asyncio.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable
+from typing import Any
+from weakref import WeakKeyDictionary
+
+from ..api import render_exception
+from ..config import Config, default_config
+
+_Handler = Callable[[asyncio.AbstractEventLoop, dict[str, Any]], None]
+_installed_handlers: WeakKeyDictionary[asyncio.AbstractEventLoop, tuple[_Handler | None, _Handler]] = (
+    WeakKeyDictionary()
+)
+
+
+def install_asyncio_exception_handler(
+    loop: asyncio.AbstractEventLoop | None = None,
+    *,
+    config: Config | None = None,
+    chain_previous: bool = False,
+) -> None:
+    loop = loop or asyncio.get_running_loop()
+    if loop in _installed_handlers:
+        return
+    previous = loop.get_exception_handler()
+    selected_config = config or default_config()
+
+    def handler(current_loop: asyncio.AbstractEventLoop, context: dict[str, Any]) -> None:
+        exception = context.get("exception")
+        if not isinstance(exception, BaseException):
+            _delegate(current_loop, context, previous)
+            return
+        if previous is not None and not chain_previous:
+            previous(current_loop, context)
+            return
+        try:
+            render_exception(
+                exception,
+                full=selected_config.include_full_traceback,
+                stream=selected_config.output_stream,
+                config=selected_config,
+            )
+        except BaseException:
+            _delegate(current_loop, context, previous)
+            return
+        if previous is not None:
+            previous(current_loop, context)
+
+    _installed_handlers[loop] = (previous, handler)
+    loop.set_exception_handler(handler)
+
+
+def _delegate(
+    loop: asyncio.AbstractEventLoop,
+    context: dict[str, Any],
+    previous: _Handler | None,
+) -> None:
+    if previous is not None:
+        previous(loop, context)
+    else:
+        loop.default_exception_handler(context)
+
+
+def uninstall_asyncio_exception_handler(loop: asyncio.AbstractEventLoop | None = None) -> None:
+    loop = loop or asyncio.get_running_loop()
+    installed = _installed_handlers.pop(loop, None)
+    if installed is None:
+        return
+    previous, handler = installed
+    if loop.get_exception_handler() is handler:
+        loop.set_exception_handler(previous)

lucidlog/integrations/logging.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import logging
+
+from ..api import log_exception as _log_exception
+from ..config import Config
+from ..models import Diagnostic
+
+
+def log_exception_with_diagnostic(
+    logger: logging.Logger,
+    message: str,
+    *,
+    full: bool = False,
+    config: Config | None = None,
+) -> Diagnostic:
+    return _log_exception(logger, message, full=full, config=config)
+
+
+def log_exception(
+    logger: logging.Logger,
+    message: str,
+    *,
+    full: bool = False,
+    config: Config | None = None,
+) -> Diagnostic:
+    return log_exception_with_diagnostic(logger, message, full=full, config=config)