Debugging

The debugging helpers are meant for external scripts and small home-brewed workflow code. Diagnostics provides an opt-in pattern for writing artifacts such as plots, reports, or intermediate snapshots without adding global debug flags or commented-out debugging blocks.

When diagnostics are disabled, hooks return immediately and do not create output directories:

from snippets.debugging import Diagnostics, NO_DIAGNOSTICS


def write_report(value, path):
    path.write_text(f"value={value}\n", encoding="utf-8")


def process_value(value, diagnostics=NO_DIAGNOSTICS):
    diagnostics.emit(
        "input",
        lambda path: write_report(value, path / "input.txt"),
    )

    result = value * 2

    diagnostics.emit(
        "output",
        lambda path: write_report(result, path / "output.txt"),
    )
    return result


diagnostics = Diagnostics(enabled=True, outdir="debug", only={"output"})
process_value(3, diagnostics=diagnostics)

Use child() to keep event names explicit in nested workflows:

diagnostics = Diagnostics(
    enabled=True,
    outdir="debug",
    only={"preprocess.input"},
)
preprocess_diagnostics = diagnostics.child("preprocess")
preprocess_diagnostics.emit("input", lambda path: write_report(3, path / "input.txt"))

This writes to debug/preprocess/input/input.txt. Because child diagnostics use qualified event names, the only filter must use preprocess.input, not input.

Optional dependency fallback

If a workflow can run without snippets, define a small fallback and skip optional setup when Diagnostics is unavailable:

try:
    from snippets.debugging import NO_DIAGNOSTICS, Diagnostics
except ImportError:
    class NoDiagnostics:
        enabled = False

        def active(self, name):
            return False

        def emit(self, name, fn):
            return None

        def child(self, prefix):
            return self

    NO_DIAGNOSTICS = NoDiagnostics()
    Diagnostics = None


diagnostics = NO_DIAGNOSTICS
if Diagnostics is not None:
    diagnostics = Diagnostics(enabled=True, outdir="debug")

Functions can still default to NO_DIAGNOSTICS, so callers that do not need artifacts do not need any setup.

Performance

Diagnostic hooks belong at stage boundaries. Do not put emit() calls inside tight numerical loops, per-cell loops, Dask block kernels, numba or JAX compiled sections, or xarray apply_ufunc inner functions.

In hot paths, check diagnostics.active(name) before doing any setup for a diagnostic artifact.