Source code for snippets.debugging

"""Debugging helpers for interactive analysis and small workflow scripts."""

__all__ = ["Diagnostics", "NO_DIAGNOSTICS", "NoDiagnostics", "warn_with_traceback"]

from collections.abc import Callable, Iterable
from pathlib import Path
import sys
import traceback
from typing import Any
import warnings


[docs] class NoDiagnostics: """Disabled diagnostic artifact hooks for default/off state.""" enabled = False outdir = Path("debug") only = None def active(self, name: str) -> bool: return False def emit(self, name: str, fn: Callable[[Path], Any]) -> Any: return None def child(self, prefix: str) -> "NoDiagnostics": return self
NO_DIAGNOSTICS = NoDiagnostics()
[docs] class Diagnostics: """Small opt-in writer for diagnostic artifacts. Use this in external scripts or home-brewed workflow code when plots, reports, or snapshots are useful for debugging an operation. """ def __init__( self, enabled: bool = False, outdir: Path | str = "debug", only: Iterable[str] | None = None, *, _prefix: str | None = None, ): self.enabled = enabled self.outdir = Path(outdir) self.only = set(only) if only is not None else None self._prefix = _prefix def _qualify(self, name: str) -> str: if self._prefix is None or self._prefix == "": return name return f"{self._prefix}.{name}" def active(self, name: str) -> bool: qualified = self._qualify(name) return self.enabled and (self.only is None or qualified in self.only) def emit(self, name: str, fn: Callable[[Path], Any]) -> Any: if not self.active(name): return None path = self.outdir.joinpath(*self._qualify(name).split(".")) path.mkdir(parents=True, exist_ok=True) return fn(path) def child(self, prefix: str) -> "Diagnostics": return Diagnostics( enabled=self.enabled, outdir=self.outdir, only=self.only, _prefix=self._qualify(prefix), )
# CREDIT: mgab https://stackoverflow.com/a/22376126 def warn_with_traceback(message, category, filename, lineno, file=None, line=None): log = file if hasattr(file, "write") else sys.stderr traceback.print_stack(file=log) log.write(warnings.formatwarning(message, category, filename, lineno, line))