lucidlog 0.1.0__tar.gz

lucidlog-0.1.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: lucidlog
+Version: 0.1.0
+Summary: Source-aware exception diagnostics with conservative explanations
+Author: LucidLog contributors
+License: MIT
+Keywords: debugging,exceptions,diagnostics,tracebacks
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+
+# LucidLog
+
+LucidLog is a lightweight, source-aware exception diagnostic library for Python.
+
+It keeps the original exception behavior intact, adds a clearer reading of the relevant traceback frame, and provides deterministic built-in explanations without requiring a remote service.
+
+## Quick start
+
+```python
+import lucidlog
+
+lucidlog.install()
+
+try:
+    value = {}["missing"]
+except Exception:
+    lucidlog.exception("Lookup failed")
+```
+
+## Complete example
+
+Run the bundled demo for a full tour of the library's features:
+
+```bash
+python examples/complete_demo.py
+```
+
+The demo covers chained exceptions, redaction, render output, custom rules, logging payloads, and the threading/asyncio integrations.
+
+## Public API
+
+- `lucidlog.install()`
+- `lucidlog.uninstall()`
+- `lucidlog.exception(message, *, stream=None, full=False, config=None)`
+- `lucidlog.diagnose(exc, *, config=None)`
+- `lucidlog.log_exception(logger, message, *, full=False, config=None)`
+- `lucidlog.render_diagnostic(diagnostic, *, full=False, stream=None, color=None)`
+
+## Configuration and output
+
+Pass a frozen `lucidlog.Config` to `install`, `diagnose`, `exception`, or `log_exception` to configure capture and output:
+
+```python
+import lucidlog
+from lucidlog import Config
+
+lucidlog.install(
+    config=Config(
+        color=True,
+        include_full_traceback=True,
+        max_chain_depth=6,
+        redact_patterns=(r"(?i)customer-id=[A-Z0-9]+",),
+    )
+)
+```
+
+Colors are disabled for non-interactive streams by default and honor `NO_COLOR` and `TERM=dumb`. `color=True` forces ANSI output; `color=False` disables it. Exception colors distinguish common diagnostic families, while the severity badge uses a separate palette (`critical`, `error`, `warning`, or `info`). The JSON representation contains the plain text values, never ANSI codes.
+
+Cause/context chains and exception groups are represented as bounded nested data and included in the compact output. Limits (`max_chain_depth`, `max_group_exceptions`, `max_frames`, `max_message_length`, `max_traceback_chars`, `max_source_file_bytes`, and `max_diagnosis_evidence`) constrain diagnostic capture. `Diagnostic.to_dict()` and `to_json()` include a schema version, severity, fingerprint-like ID, cause relationships, and truncation indicator. Setting `include_local_variables=True` or `allow_network=True` is rejected; those capabilities are deliberately not part of the core.
+
+The optional runtime integrations are explicit:
+
+```python
+from lucidlog.integrations.threading import install_threading_hook
+from lucidlog.integrations.asyncio import install_asyncio_exception_handler
+
+install_threading_hook()
+install_asyncio_exception_handler()
+```
+
+Each has a corresponding `uninstall_*` function. Asyncio leaves an already-installed handler in place unless `chain_previous=True`; thread and main hooks restore prior handlers when removed. Worker-thread and event-loop hooks do not cover child processes.
+
+## Privacy notes
+
+LucidLog never reads local variables or makes network requests. It redacts common credential-shaped strings and user-configured patterns from messages, source context, causes, and traceback text before those values enter the diagnostic model. Absolute paths under the home directory are shortened by default; `root_path` can shorten project paths. Redaction is best-effort: exception messages and source code are arbitrary application data, so review output before storing or forwarding it and supply additional patterns for your environment. `Config` validates regex syntax and output limits up front.
+
+Logging integration writes one structured log record with a `lucidlog` dictionary in `LogRecord` extra fields. It deliberately omits `exc_info` to avoid bypassing redaction with a raw traceback. The original exception is not modified, and `log_exception` requires an active exception handler.
+
+## Tests
+
+Run the unit and integration tests with:
+
+```bash
+python -m pytest
+```
+
+The suite covers chained and grouped exceptions, cycle/size limits, redaction, terminal colors, hook restoration, threading, asyncio, structured logging, and uncaught-process exit behavior.
+
+## Notes
+
+- The core package is standard-library only.
+- It does not capture local variables by default.
+- It keeps the original traceback available and does not replace the application's original exception flow.

lucidlog-0.1.0/README.md

@@ -0,0 +1,93 @@
+# LucidLog
+
+LucidLog is a lightweight, source-aware exception diagnostic library for Python.
+
+It keeps the original exception behavior intact, adds a clearer reading of the relevant traceback frame, and provides deterministic built-in explanations without requiring a remote service.
+
+## Quick start
+
+```python
+import lucidlog
+
+lucidlog.install()
+
+try:
+    value = {}["missing"]
+except Exception:
+    lucidlog.exception("Lookup failed")
+```
+
+## Complete example
+
+Run the bundled demo for a full tour of the library's features:
+
+```bash
+python examples/complete_demo.py
+```
+
+The demo covers chained exceptions, redaction, render output, custom rules, logging payloads, and the threading/asyncio integrations.
+
+## Public API
+
+- `lucidlog.install()`
+- `lucidlog.uninstall()`
+- `lucidlog.exception(message, *, stream=None, full=False, config=None)`
+- `lucidlog.diagnose(exc, *, config=None)`
+- `lucidlog.log_exception(logger, message, *, full=False, config=None)`
+- `lucidlog.render_diagnostic(diagnostic, *, full=False, stream=None, color=None)`
+
+## Configuration and output
+
+Pass a frozen `lucidlog.Config` to `install`, `diagnose`, `exception`, or `log_exception` to configure capture and output:
+
+```python
+import lucidlog
+from lucidlog import Config
+
+lucidlog.install(
+    config=Config(
+        color=True,
+        include_full_traceback=True,
+        max_chain_depth=6,
+        redact_patterns=(r"(?i)customer-id=[A-Z0-9]+",),
+    )
+)
+```
+
+Colors are disabled for non-interactive streams by default and honor `NO_COLOR` and `TERM=dumb`. `color=True` forces ANSI output; `color=False` disables it. Exception colors distinguish common diagnostic families, while the severity badge uses a separate palette (`critical`, `error`, `warning`, or `info`). The JSON representation contains the plain text values, never ANSI codes.
+
+Cause/context chains and exception groups are represented as bounded nested data and included in the compact output. Limits (`max_chain_depth`, `max_group_exceptions`, `max_frames`, `max_message_length`, `max_traceback_chars`, `max_source_file_bytes`, and `max_diagnosis_evidence`) constrain diagnostic capture. `Diagnostic.to_dict()` and `to_json()` include a schema version, severity, fingerprint-like ID, cause relationships, and truncation indicator. Setting `include_local_variables=True` or `allow_network=True` is rejected; those capabilities are deliberately not part of the core.
+
+The optional runtime integrations are explicit:
+
+```python
+from lucidlog.integrations.threading import install_threading_hook
+from lucidlog.integrations.asyncio import install_asyncio_exception_handler
+
+install_threading_hook()
+install_asyncio_exception_handler()
+```
+
+Each has a corresponding `uninstall_*` function. Asyncio leaves an already-installed handler in place unless `chain_previous=True`; thread and main hooks restore prior handlers when removed. Worker-thread and event-loop hooks do not cover child processes.
+
+## Privacy notes
+
+LucidLog never reads local variables or makes network requests. It redacts common credential-shaped strings and user-configured patterns from messages, source context, causes, and traceback text before those values enter the diagnostic model. Absolute paths under the home directory are shortened by default; `root_path` can shorten project paths. Redaction is best-effort: exception messages and source code are arbitrary application data, so review output before storing or forwarding it and supply additional patterns for your environment. `Config` validates regex syntax and output limits up front.
+
+Logging integration writes one structured log record with a `lucidlog` dictionary in `LogRecord` extra fields. It deliberately omits `exc_info` to avoid bypassing redaction with a raw traceback. The original exception is not modified, and `log_exception` requires an active exception handler.
+
+## Tests
+
+Run the unit and integration tests with:
+
+```bash
+python -m pytest
+```
+
+The suite covers chained and grouped exceptions, cycle/size limits, redaction, terminal colors, hook restoration, threading, asyncio, structured logging, and uncaught-process exit behavior.
+
+## Notes
+
+- The core package is standard-library only.
+- It does not capture local variables by default.
+- It keeps the original traceback available and does not replace the application's original exception flow.

lucidlog-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "lucidlog"
+version = "0.1.0"
+description = "Source-aware exception diagnostics with conservative explanations"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "LucidLog contributors" }]
+keywords = ["debugging", "exceptions", "diagnostics", "tracebacks"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=7.0",
+  "pytest-cov>=4.0",
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

lucidlog-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

lucidlog-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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,
+    )