xakki-log-python 0.4.0__py3-none-any.whl

log_python/trace.py

@@ -0,0 +1,504 @@
+"""Stack-trace capture ported from `TraitFileTrace.php` (`src/TraitFileTrace.php`), wired
+the way `LogManager::appendContext()` (`src/LogManager.php`) actually calls it (spec
+`docs/LoggingRules.md` §3.7 / §6.1). Both reference files re-verified 2026-08-13.
+
+Two rendering modes, both feeding the SAME `#N file:line | qualname(args)` line format and
+the SAME consecutive-excluded-frame collapsing, but with different call-site semantics —
+this mirrors a real asymmetry in the PHP reference, not a simplification:
+
+- **Call-site trace** (`TraceCapture.capture()`) — what the reference builds from
+  `debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 40)` for an ordinary `warning`+ log call.
+  `DEBUG_BACKTRACE_IGNORE_ARGS` means the PHP trace carries NO call arguments at all, so
+  `renderTraceWithClass()`'s argument-redaction branch is simply never reached on this path.
+  Excluded frames (`excluded_partials`) are dropped and collapsed into a `.` run; only
+  non-excluded frames count against the per-level depth budget (5/10/20). No trace at all
+  below `WARNING` (`appendContext()`'s `$level->value >= Level::Warning->value` guard).
+- **Exception trace** (`TraceCapture.format_exception_chain()`) — what the reference builds
+  from `$e->getTrace()` (`traceToString($e->getTrace(), 30, false)`), which DOES carry call
+  arguments (no `IGNORE_ARGS` flag), so THIS is the path where `Redactor::redactValue()`
+  actually runs over trace arguments in the reference. Filtering is OFF
+  (`checkExcludePart=false`): excluded frames are still listed (file:line only, no
+  class/function/args) and DO count against the fixed 30-frame limit — nothing is collapsed
+  to dots here. Python has no "call arguments" concept distinct from a frame's locals; the
+  closest analogue (`inspect.getargvalues()`, no source read, no `inspect.stack()`) is used
+  to reconstruct the parameter values for exception frames only, which is exactly where the
+  reference needs them. Unlike PHP's positional-only backtrace arrays, `getargvalues()` also
+  hands back the PARAMETER NAME each value is bound to — this port uses that to apply
+  key-aware masking (`Redactor.should_redact_key()`) before the value-shape pass
+  (`_render_arg(value, name=...)`), a Python-only addition with no PHP analogue: PHP
+  structurally cannot know a positional arg's name, this port can and does, so a
+  `def login(password: str)` frame does not leak its argument here the way it would in the
+  reference.
+
+Ordering divergence (documented, not a bug): the reference's frame 0 is the THROW point
+(deepest frame first, PHP `getTrace()` order). This port keeps Python's own `tb_next`
+order (shallowest/catch-adjacent frame first, raise point last) — "most recent call last",
+matching every other Python traceback a reader will have seen.
+
+`LOGGER_SKIP_TRACE` ('skipTrace'): historically, this key was registered ONLY as a
+context-type-coercion skip entry in the PHP reference
+(`LogManager::$contextTypeRules['reserved'][LOGGER_SKIP_TRACE] = CONTEXT_TYPE_SKIP`,
+already ported in `context.py`) — nothing in `LogManager.php` ever READ
+`$context[LOGGER_SKIP_TRACE]` to actually suppress capture, despite what the name implied.
+`should_skip_trace()` below was originally this port's own completion of that evident
+intent. As of this phase, a matching fix has landed on the PHP side too (uncommitted at
+the time of writing — `LogManager::appendContext()` now reads the marker via
+`contextCastBool()`, pops it before coercion, and gates the call-site AND exception
+traces on it), so the two libraries now agree on both the wiring AND the truthiness
+convention: `should_skip_trace()` casts through the SAME `CONTEXT_FALSE_VALUES` bool
+convention `context.py`'s `_cast_bool()` uses, not raw Python truthiness (`bool("false")`
+is `True` in Python, which would silently invert a caller's intent). See `mapping.md`.
+`manager.py` (phase 5) is the orchestrator that calls this before `.capture()` /
+`.format_exception_chain()` / `.render_exception_trace()`, and pops the marker key so it
+never reaches the wire.
+
+Performance (this sits on the hot logging path): frames are walked via `sys._getframe()` /
+raw `TracebackType.tb_next`, never `inspect.stack()` (which reads source context per frame
+via `linecache` — pathologically slow). No source lines are read anywhere in this module.
+Both raw walks are capped (`_MAX_RAW_CALL_SITE_FRAMES` / `_EXCEPTION_TRACE_LIMIT`) so a
+pathologically deep recursion (e.g. a `RecursionError` traceback, ~1000 frames) costs the
+same handful of frame reads as a shallow one — the cap is applied to the WALK itself, not as
+a post-hoc slice of an already-fully-materialized frame list.
+"""
+
+from __future__ import annotations
+
+import inspect
+import logging
+import sys
+from collections.abc import Iterable, Mapping, Sequence
+from dataclasses import dataclass
+from types import FrameType, TracebackType
+from typing import TYPE_CHECKING, Final
+
+from log_python.const import LOGGER_SKIP_TRACE
+from log_python.context import CONTEXT_FALSE_VALUES
+from log_python.redactor import Redactor
+
+if TYPE_CHECKING:
+    from log_python.config import PylogConfig, TraceConfig
+
+# Same bool-truthiness convention as `context.py::_cast_bool()` — a string 'false'/'0'/
+# 'off'/'no' must NOT be treated as a truthy skip-trace marker. Bound to a module constant
+# here (rather than referenced only inline in `should_skip_trace()`) so the import is a
+# real, direct dependency of this module, not a re-export.
+_SKIP_TRACE_FALSE_VALUES: Final[frozenset[str]] = CONTEXT_FALSE_VALUES
+
+_UNRENDERABLE: Final[str] = "<unrenderable>"
+_UNREADABLE_FRAME: Final[str] = "<unreadable frame>"
+_TRUNCATION_MARKER: Final[str] = "***"
+
+# PHP call-site cap: `debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 40)`.
+_MAX_RAW_CALL_SITE_FRAMES: Final[int] = 40
+# PHP exception-trace fixed limit: `traceToString($e->getTrace(), 30, false)`.
+_EXCEPTION_TRACE_LIMIT: Final[int] = 30
+# Cause/context chain depth guard. The PHP reference only ever follows ONE
+# `getPrevious()` level (see the module-level report to the team-lead / SKILL.md for this
+# drift against its own spec text "full chain via getPrevious()") — there is no reference
+# cap to match. Bounded here purely as a defensive ceiling against a pathological chain.
+_MAX_CHAIN_DEPTH: Final[int] = 10
+
+_CAUSE_SEPARATOR: Final[str] = "\nThe above exception was the direct cause of the following exception:\n"
+_CONTEXT_SEPARATOR: Final[str] = "\nDuring handling of the above exception, another exception occurred:\n"
+
+
+@dataclass(frozen=True, slots=True)
+class _RawFrame:
+    """One normalized stack frame. `args` is populated only for exception frames — the
+    call-site path never has arguments to offer (see module docstring). Each entry is a
+    `(param_name, value)` pair, not a bare value: unlike PHP's `debug_backtrace()`/
+    `getTrace()` (a positional array with no parameter names attached), Python's
+    `inspect.getargvalues()` DOES give us the parameter name each value is bound to — see
+    `_render_arg()` for why that matters for redaction.
+    """
+
+    file: str | None
+    line: int | None
+    qualname: str | None
+    args: tuple[tuple[str, object], ...] | None
+
+
+@dataclass(frozen=True, slots=True)
+class CapturedTrace:
+    """Result of `TraceCapture.capture()` — mirrors the reference's `getFileLine()` (`file`)
+    and `traceToString()` (`trace`) over one `debug_backtrace()` call.
+    """
+
+    file: str
+    trace: str | None
+
+
+def _is_excluded(path: str, excluded_partials: tuple[str, ...]) -> bool:
+    return any(partial in path for partial in excluded_partials)
+
+
+def _frame_info(frame: FrameType) -> _RawFrame:
+    try:
+        code = frame.f_code
+        return _RawFrame(file=code.co_filename, line=frame.f_lineno, qualname=code.co_qualname, args=None)
+    except Exception:
+        # A logging library must never raise from the logging path over a merely
+        # unusual/broken frame — degrade to an unreadable placeholder instead.
+        return _RawFrame(file=None, line=None, qualname=None, args=None)
+
+
+def _walk_live_stack(*, skip: int, max_frames: int) -> list[_RawFrame]:
+    """Walk the CURRENTLY EXECUTING stack via `sys._getframe().f_back`, capped at
+    `max_frames` — never `inspect.stack()` (see module docstring).
+    """
+    frames: list[_RawFrame] = []
+    try:
+        frame: FrameType | None = sys._getframe(skip)
+    except ValueError:
+        # Fewer frames on the stack than `skip` (e.g. called near the top of the program).
+        frame = None
+    count = 0
+    while frame is not None and count < max_frames:
+        frames.append(_frame_info(frame))
+        frame = frame.f_back
+        count += 1
+    return frames
+
+
+def _exception_frame_info(tb: TracebackType) -> _RawFrame:
+    try:
+        frame = tb.tb_frame
+        code = frame.f_code
+        file = code.co_filename
+        line = tb.tb_lineno
+        qualname = code.co_qualname
+    except Exception:
+        return _RawFrame(file=None, line=None, qualname=None, args=None)
+
+    args: tuple[tuple[str, object], ...] | None
+    try:
+        # Closest Python analogue of PHP's per-call `args` array: the values bound to this
+        # frame's OWN parameters (not its full locals). No source read (unlike
+        # `inspect.stack()` / `inspect.getframeinfo()`) — `getargvalues()` only introspects
+        # `frame.f_code` and `frame.f_locals`. Kept as (name, value) pairs, not bare values —
+        # the name is what lets `_render_arg()` apply the SAME key-aware redaction the rest
+        # of the library uses for named context fields, which PHP structurally cannot do
+        # here (its backtrace arrays carry no parameter names at all).
+        arg_info = inspect.getargvalues(frame)
+        names = [*arg_info.args]
+        if arg_info.varargs:
+            names.append(arg_info.varargs)
+        if arg_info.keywords:
+            names.append(arg_info.keywords)
+        args = tuple((name, arg_info.locals.get(name)) for name in names)
+    except Exception:
+        args = None
+
+    return _RawFrame(file=file, line=line, qualname=qualname, args=args)
+
+
+def _walk_traceback(tb: TracebackType | None, *, max_frames: int) -> list[_RawFrame]:
+    frames: list[_RawFrame] = []
+    count = 0
+    while tb is not None and count < max_frames:
+        frames.append(_exception_frame_info(tb))
+        tb = tb.tb_next
+        count += 1
+    return frames
+
+
+def _first_file_line(frames: Iterable[_RawFrame], excluded_partials: tuple[str, ...]) -> str:
+    """Port of `TraitFileTrace::getFileLine()`: first frame whose file is not excluded,
+    rendered `file:line`; `''` if every frame is excluded or none carry a file.
+
+    No Laravel `app()->basePath()` equivalent exists in a framework-agnostic Python library,
+    so the file path is left as-is (absolute, as CPython reports it) rather than PHP's
+    `getRelativeFilePath()` — a documented Python-side simplification, not a gap.
+    """
+    for item in frames:
+        if not item.file:
+            continue
+        if _is_excluded(item.file, excluded_partials):
+            continue
+        return f"{item.file}:{item.line if item.line is not None else ''}"
+    return ""
+
+
+def exception_origin(exc: BaseException) -> str:
+    """The file:line where `exc` was ultimately raised (the deepest traceback frame) —
+    mirrors the reference's separate `context['file'] = getRelativeFilePath($e->getFile()) .
+    ':' . $e->getLine()` assignment for exception logging (`LogManager::appendContext()`,
+    distinct from the general call-site `getFileLine()` fallback).
+    """
+    tb = exc.__traceback__
+    if tb is None:
+        return ""
+    while tb.tb_next is not None:
+        tb = tb.tb_next
+    try:
+        return f"{tb.tb_frame.f_code.co_filename}:{tb.tb_lineno}"
+    except Exception:
+        return ""
+
+
+def exception_class_name(exc: BaseException) -> str:
+    """Fully-qualified exception class name, mirroring PHP's `get_class($e)` (always a
+    namespaced FQCN there). `builtins`/`__main__` are stripped as module qualifiers since
+    Python's own `traceback` module does the same — `ValueError`, not
+    `builtins.ValueError`. Used both for the `exception`/`exception_prev` context fields
+    (`manager.py`, phase 5) and the per-link header in `format_exception_chain()` below, so
+    the two never drift apart on how a class name is rendered.
+    """
+    try:
+        module = type(exc).__module__
+        qualname = type(exc).__qualname__
+    except Exception:
+        return _UNRENDERABLE
+    else:
+        return qualname if module in ("builtins", "__main__") else f"{module}.{qualname}"
+
+
+def should_skip_trace(context: Mapping[str, object]) -> bool:
+    """True if `context` carries a truthy `LOGGER_SKIP_TRACE` ('skipTrace') flag.
+
+    Truthiness is decided the same way every other bool-shaped context field in this
+    library is decided — `context.py`'s `_cast_bool()` / `CONTEXT_FALSE_VALUES` convention
+    — NOT raw Python truthiness. `bool("false")` is `True` in Python, which would silently
+    invert a caller's intent for a value arriving as a string (env var, HTTP header, JSON
+    payload): `{"skipTrace": "false"}` must NOT suppress the trace. This mirrors a matching
+    fix landed concurrently on the PHP side (`LogManager::appendContext()`, using its own
+    `contextCastBool()`) — the two libraries must agree on this, see mapping.md.
+
+    A non-scalar value (dict/list/object/...) has no bool-cast convention to apply — same
+    as PHP's `is_scalar()` guard — and is treated as not-set (does not suppress).
+
+    See the module docstring: the PHP reference historically never read this key at all to
+    suppress capture (it only registered it in the type-coercion skip table); this is this
+    port's completion of that evidently-intended opt-out, for a phase-5 orchestrator to
+    call before `.capture()` / `.format_exception_chain()` / `.render_exception_trace()`.
+    """
+    value = context.get(LOGGER_SKIP_TRACE)
+    if value is None:
+        return False
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, int | float):
+        return value != 0
+    if isinstance(value, str):
+        return value.strip().lower() not in _SKIP_TRACE_FALSE_VALUES
+    return False
+
+
+class TraceCapture:
+    """Precompiled, reusable trace-capture helper (mirrors `Redactor` / `ContextTypeCorrector`
+    — build once per process, reuse for its lifetime). Takes a `Redactor` for trace argument
+    redaction: value-shape matching (`Redactor.redact_value()`, the reference's own
+    mechanism — PHP's backtrace arrays are positional/key-less) PLUS, for exception frames
+    where a parameter name is available, key-aware masking (`Redactor.should_redact_key()`)
+    that the PHP reference structurally cannot do (see `_render_arg()`).
+    """
+
+    __slots__ = ("_arg_limit", "_config", "_redactor")
+
+    def __init__(self, config: TraceConfig, redactor: Redactor) -> None:
+        self._config = config
+        self._redactor = redactor
+        self._arg_limit = config.arg_limit
+
+    @classmethod
+    def from_config(cls, config: PylogConfig, redactor: Redactor) -> TraceCapture:
+        """Build a TraceCapture from `PylogConfig.trace`, reusing a shared `Redactor`."""
+        return cls(config.trace, redactor)
+
+    def depth_for_level(self, level: int) -> int:
+        """Frames to capture for a stdlib `logging` level. `0` = no trace at all — the
+        reference never builds a trace below `Warning` (`appendContext()`'s
+        `$level->value >= Level::Warning->value` guard); `logging.CRITICAL` and above also
+        covers any custom higher level a caller defines, matching the reference comment
+        "critical => 20 // also alert/emergency" (stdlib `logging` has no separate
+        alert/emergency levels).
+        """
+        if level < logging.WARNING:
+            return 0
+        if level >= logging.CRITICAL:
+            return self._config.depth.critical
+        if level >= logging.ERROR:
+            return self._config.depth.error
+        return self._config.depth.warning
+
+    def capture(self, level: int, *, skip: int = 2) -> CapturedTrace:
+        """Capture the current call site. `file` is always resolved (mirrors the reference
+        computing `context['file']` unconditionally); `trace` is `None` below the warning
+        depth cutoff.
+
+        `skip` is how many of THIS function's own frames to discard before starting the walk
+        (default 2: `_walk_live_stack`'s own frame + `capture()`'s own frame, landing on
+        `capture()`'s caller) — mirrors the reference's `array_slice(debug_backtrace(...), 1)`
+        dropping `appendContext()`'s own entry. A caller one layer further removed (e.g. a
+        thin logging wrapper) should pass a larger `skip`.
+        """
+        depth = self.depth_for_level(level)
+        raw = _walk_live_stack(skip=skip, max_frames=_MAX_RAW_CALL_SITE_FRAMES)
+        file_line = _first_file_line(raw, self._config.excluded_partials)
+        if depth <= 0:
+            return CapturedTrace(file=file_line, trace=None)
+        trace = self._render_frames(raw, limit=depth, filter_excluded=True)
+        return CapturedTrace(file=file_line, trace=trace)
+
+    def format_exception_chain(self, exc: BaseException) -> str:
+        """Render `exc` and its full `__cause__`/`__context__` chain into ONE coalesced
+        string (spec §3.7/§6.1 — never one record per traceback line, never one log call per
+        frame). Each link renders like the reference's own-exception trace
+        (`traceToString($e->getTrace(), 30, false)` — no filtering, fixed 30-frame limit,
+        arguments rendered+redacted); links are joined with the same separator text Python's
+        own `traceback` module uses for chained exceptions.
+
+        The reference (`LogManager::appendContext()`) only ever follows ONE `getPrevious()`
+        level into separate `exception_prev*` fields, despite its own spec text (§6.1) saying
+        "full chain via getPrevious()" — a drift between spec and implementation, reported
+        rather than silently resolved. This method follows the SPEC's stated intent (full
+        chain) using Python's native chain-walking idiom; field-name assembly (whether/how a
+        multi-level chain maps onto `exception_prev*`-shaped fields) is phase 5's job, not
+        this module's.
+        """
+        chain: list[tuple[BaseException, str | None]] = []
+        seen: set[int] = set()
+        current: BaseException | None = exc
+        depth = 0
+        while current is not None and depth < _MAX_CHAIN_DEPTH:
+            current_id = id(current)
+            if current_id in seen:
+                break
+            seen.add(current_id)
+            try:
+                cause = current.__cause__
+                context = current.__context__
+                suppressed = current.__suppress_context__
+            except Exception:
+                # A hostile exception subclass whose __cause__/__context__/
+                # __suppress_context__ access itself raises (e.g. overridden as a raising
+                # property) must not blow up the logging path — stop walking the chain
+                # here rather than propagate.
+                next_exception = None
+                separator = None
+            else:
+                if cause is not None:
+                    next_exception = cause
+                    separator = _CAUSE_SEPARATOR
+                elif context is not None and not suppressed:
+                    next_exception = context
+                    separator = _CONTEXT_SEPARATOR
+                else:
+                    next_exception = None
+                    separator = None
+            chain.append((current, separator))
+            current = next_exception
+            depth += 1
+
+        parts: list[str] = []
+        for index in range(len(chain) - 1, -1, -1):
+            parts.append(self._format_single_exception(chain[index][0]))
+            if index > 0:
+                separator = chain[index - 1][1]
+                if separator is not None:
+                    parts.append(separator)
+        return "\n".join(parts)
+
+    def render_exception_trace(self, exc: BaseException) -> str:
+        """Single-exception frame-list rendering, mirroring
+        `traceToString($e->getTrace(), 30, false)` exactly: no header (class name and
+        message are separate context fields already — `manager.py` phase 5), filtering
+        OFF, fixed 30-frame limit. This is the shared building block behind both
+        `_format_single_exception()`'s per-link body below and the flat `trace` /
+        `exception_prev_trace` fields `manager.py` assembles for a single exception (the
+        owner-decided ONE-level `exception_prev*` shape, distinct from the full coalesced
+        chain `format_exception_chain()` produces).
+        """
+        frames = _walk_traceback(exc.__traceback__, max_frames=_EXCEPTION_TRACE_LIMIT)
+        return self._render_frames(frames, limit=_EXCEPTION_TRACE_LIMIT, filter_excluded=False)
+
+    def _format_single_exception(self, exc: BaseException) -> str:
+        try:
+            message = self._redactor.redact_value(str(exc))
+        except Exception:
+            header = _UNRENDERABLE
+        else:
+            header = f"{exception_class_name(exc)}: {message}"
+        body = self.render_exception_trace(exc)
+        return f"{header}\n{body}" if body else header
+
+    def _render_frames(self, frames: Sequence[_RawFrame], *, limit: int, filter_excluded: bool) -> str:
+        """Port of `TraitFileTrace::traceToString()`. `filter_excluded=True` (call-site mode)
+        drops excluded frames and collapses consecutive runs into a single `'.' * N` marker,
+        counting only kept frames against `limit`; `filter_excluded=False` (exception mode)
+        keeps every frame (file:line only, no class/function/args for excluded ones) and
+        counts all of them against `limit`.
+        """
+        out: list[str] = []
+        skipped = 0
+        i = 0
+        for item in frames:
+            excluded = item.file is not None and _is_excluded(item.file, self._config.excluded_partials)
+            if excluded and filter_excluded:
+                skipped += 1
+                continue
+            if skipped:
+                out.append("." * skipped)
+                skipped = 0
+
+            line = f"#{i}"
+            if item.file:
+                line += f" {item.file}:{item.line if item.line is not None else ''}"
+            elif item.qualname is None:
+                line += f" {_UNREADABLE_FRAME}"
+            if not excluded and item.qualname:
+                line += self._render_call_suffix(item)
+            out.append(line)
+
+            i += 1
+            if i >= limit:
+                out.append(_TRUNCATION_MARKER)
+                break
+
+        if skipped:
+            out.append("." * skipped)
+        return "\n".join(out)
+
+    def _render_call_suffix(self, item: _RawFrame) -> str:
+        args_str = ""
+        if item.args:
+            args_str = ", ".join(self._render_arg(value, name=name) for name, value in item.args)
+        return f" | {item.qualname}({args_str})"
+
+    def _render_arg(self, value: object, *, name: str | None = None) -> str:
+        """Render+redact one trace argument.
+
+        `name` is the parameter name this value is bound to (exception frames only, via
+        `inspect.getargvalues()` — see `_RawFrame`). When it looks sensitive
+        (`Redactor.should_redact_key()`), the whole argument is masked outright, BEFORE any
+        type dispatch — this is a Python-only addition with no PHP analogue: PHP's
+        `debug_backtrace()`/`getTrace()` arrays carry no parameter names, so
+        `renderTraceWithClass()` can only ever apply VALUE-shape redaction
+        (`Redactor::redactValue()`). A `def login(password: str)` frame would leak `password`
+        verbatim in the PHP original; this port does not have that gap and does not
+        reproduce it. Unnamed data (call-site trace has no args at all; elements inside a
+        dict/list/tuple argument) still only gets value-shape redaction — those already
+        render as `[...N]` with no content exposed, so nothing there regresses.
+
+        Ported branch-for-branch from `renderTraceWithClass()` for the type dispatch: object
+        -> class name only (no redaction/truncation, same as the reference's bare
+        `get_class($arg)`); array/list-like -> `[...N]`; bool -> `T`/`F`; str -> quoted,
+        redacted THEN truncated to `arg_limit`; everything else (None/int/float) ->
+        stringified, redacted THEN truncated. Every branch is wrapped: a broken
+        `__class__`/`__repr__`/`__str__` degrades to a placeholder rather than propagating —
+        a logging library must never raise from the logging path.
+        """
+        try:
+            if name is not None and self._redactor.should_redact_key(name):
+                return self._redactor.MASK
+            if isinstance(value, bool):
+                return "T" if value else "F"
+            if isinstance(value, dict | list | tuple | set | frozenset):
+                return f"[...{len(value)}]"
+            if isinstance(value, str):
+                return '"' + self._redactor.redact_value(value)[: self._arg_limit] + '"'
+            if value is None or isinstance(value, int | float):
+                return self._redactor.redact_value(str(value))[: self._arg_limit]
+            return type(value).__name__
+        except Exception:
+            return _UNRENDERABLE