148 lines
4.6 KiB
Python
148 lines
4.6 KiB
Python
"""
|
|
Tracing utils
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
from collections.abc import Callable
|
|
from collections.abc import Sequence
|
|
import enum
|
|
import os
|
|
from typing import Any
|
|
|
|
|
|
_Writer = Callable[[str], object]
|
|
_Processor = Callable[[tuple[str, ...], tuple[Any, ...]], object]
|
|
|
|
|
|
def _describe_failure(exc: Exception, obj: object, func: str) -> str:
|
|
try:
|
|
exc_info = repr(exc)
|
|
except Exception:
|
|
exc_info = f"unpresentable {type(exc).__name__}"
|
|
name = type(obj).__name__
|
|
return f"<[{exc_info} raised in {func}()] {name} object at 0x{id(obj):x}>"
|
|
|
|
|
|
def _escape_surrogates(text: str) -> str:
|
|
"""Escape lone surrogates so the result survives any text writer.
|
|
|
|
A lone surrogate reaching the writer raises :exc:`UnicodeEncodeError`
|
|
inside the trace call for any utf-8 target, such as the file behind
|
|
pytest's ``--debug``.
|
|
"""
|
|
if text.isascii():
|
|
return text
|
|
return text.encode("utf-8", "backslashreplace").decode("utf-8")
|
|
|
|
|
|
def _safe_str(obj: object) -> str:
|
|
"""``str(obj)`` for tracing, with a failing ``__str__`` rendered, not raised.
|
|
|
|
The result has lone surrogates escaped, so any text writer accepts it.
|
|
"""
|
|
try:
|
|
text = str(obj)
|
|
except Exception as exc:
|
|
text = _describe_failure(exc, obj, "str")
|
|
return _escape_surrogates(text)
|
|
|
|
|
|
def _is_plain_token(text: str) -> bool:
|
|
"""Whether ``text`` can be shown bare, without quotes around it."""
|
|
return bool(text) and text.isprintable() and " " not in text
|
|
|
|
|
|
def _format_block(indent: str, lines: list[str]) -> list[str]:
|
|
"""Indent a multi line value under its key, so it reads as one value."""
|
|
return [f"{indent} {line}\n" for line in lines]
|
|
|
|
|
|
def _render_value(obj: object) -> str:
|
|
"""Render a traced value, adding detail only where ``str`` is ambiguous."""
|
|
# Before the str check: a StrEnum member is a str whose str() drops the name.
|
|
if isinstance(obj, (enum.Enum, os.PathLike)):
|
|
return _safe_repr(obj)
|
|
if isinstance(obj, str):
|
|
if len(obj.splitlines()) > 1:
|
|
return _safe_str(obj)
|
|
if _is_plain_token(obj):
|
|
return _safe_str(obj)
|
|
return _safe_repr(obj)
|
|
return _safe_str(obj)
|
|
|
|
|
|
def _safe_repr(obj: object) -> str:
|
|
"""``repr(obj)`` for tracing, with a failing ``__repr__`` rendered, not raised.
|
|
|
|
The result has lone surrogates escaped, so any text writer accepts it.
|
|
"""
|
|
try:
|
|
text = repr(obj)
|
|
except Exception as exc:
|
|
text = _describe_failure(exc, obj, "repr")
|
|
return _escape_surrogates(text)
|
|
|
|
|
|
class TagTracer:
|
|
def __init__(self) -> None:
|
|
self._tags2proc: dict[tuple[str, ...], _Processor] = {}
|
|
self._writer: _Writer | None = None
|
|
self.indent = 0
|
|
|
|
def get(self, name: str) -> TagTracerSub:
|
|
return TagTracerSub(self, (name,))
|
|
|
|
def _format_message(self, tags: Sequence[str], args: Sequence[object]) -> str:
|
|
if isinstance(args[-1], dict):
|
|
extra = args[-1]
|
|
args = args[:-1]
|
|
else:
|
|
extra = {}
|
|
|
|
content = " ".join(map(_safe_str, args))
|
|
indent = " " * self.indent
|
|
|
|
lines = [f"{indent}{content} [{':'.join(tags)}]\n"]
|
|
|
|
for name, value in extra.items():
|
|
rendered = _render_value(value)
|
|
# A bare \r is a line break too: inline, the terminal would
|
|
# return to column 0 and overwrite the key.
|
|
body = rendered.splitlines()
|
|
if body in ([], [rendered]):
|
|
lines.append(f"{indent} {name}: {rendered}\n")
|
|
else:
|
|
lines.append(f"{indent} {name}:\n")
|
|
lines.extend(_format_block(indent, body))
|
|
|
|
return "".join(lines)
|
|
|
|
def _processmessage(self, tags: tuple[str, ...], args: tuple[object, ...]) -> None:
|
|
if self._writer is not None and args:
|
|
self._writer(self._format_message(tags, args))
|
|
if processor := self._tags2proc.get(tags):
|
|
processor(tags, args)
|
|
|
|
def setwriter(self, writer: _Writer | None) -> None:
|
|
self._writer = writer
|
|
|
|
def setprocessor(self, tags: str | tuple[str, ...], processor: _Processor) -> None:
|
|
if isinstance(tags, str):
|
|
tags = tuple(tags.split(":"))
|
|
else:
|
|
assert isinstance(tags, tuple)
|
|
self._tags2proc[tags] = processor
|
|
|
|
|
|
class TagTracerSub:
|
|
def __init__(self, root: TagTracer, tags: tuple[str, ...]) -> None:
|
|
self.root = root
|
|
self.tags = tags
|
|
|
|
def __call__(self, *args: object) -> None:
|
|
self.root._processmessage(self.tags, args)
|
|
|
|
def get(self, name: str) -> TagTracerSub:
|
|
return self.__class__(self.root, self.tags + (name,))
|