pelagos_py.utils.diagnostic_capture#

pelagos_py.utils.diagnostic_capture.force_headless_backend()[source]#

Force the headless Agg backend for the whole report run.

Report figures are saved to disk, never displayed, so no GUI backend is needed. Steps’ diagnostics commonly call matplotlib.use("tkagg") to force the interactive Tk backend; under report capture that is both pointless and dangerous - instantiating a Tk canvas off the main thread (e.g. when driven from an IDE/GUI) can hard-crash the process on Windows.

The backend is switched to Agg exactly once here and matplotlib.use() is neutralised for the duration, so every step’s backend switch becomes a harmless no-op and the backend is never toggled mid-run (repeated use(..., force=True) re-initialises matplotlib’s compiled backend, which can trigger a fatal delay-load crash on Windows). Both are restored on exit.

pelagos_py.utils.diagnostic_capture.capture_figures(outdir: str, step_name: str, images: list, suppress_text: bool = False, interactive: bool = False)[source]#

Redirect plt.show so diagnostic figures are saved for the report.

Within the context, every plt.show call (and any figures still open when the context exits) is written to outdir and its path recorded in images.

Parameters:

  • outdir (str) – Directory the figures are written into.

  • step_name (str) – Name of the step producing the figures (used to name the files).

  • images (list) – List that captured image paths are appended to, in the order produced.

  • suppress_text (bool, optional) – When True, stdout is silenced for the duration of the context. Used when diagnostics are force-enabled only to capture figures for the report: a step whose diagnostics are textual (print rather than a plot, e.g. the dataset summary from Load Data) would otherwise dump that text to the console even though the user never enabled diagnostics.

  • interactive (bool, optional) –

    When False (default) figures are saved and closed silently - no window is shown. This is used for steps whose diagnostics were force-enabled only to harvest figures for the report, and keeps the run headless (Agg) and Windows-safe.

    When True (the user explicitly set diagnostics: true on this step) the figure is saved to the report and shown in a blocking popup, so the pipeline pauses on that step exactly as it would outside a report run. This temporarily switches to the interactive Tk backend for the duration of the step and switches back to headless Agg afterwards; the GUI backend is the reason this path is opt-in only.

pelagos_py.utils.diagnostic_capture.make_diagnostics_safe(step) → None[source]#

Wrap a step’s diagnostic methods so a failure never aborts the step.

Used when diagnostics are force-enabled to capture plots for the report: a user who did not opt into diagnostics should never have the pipeline fail because of a diagnostic-only error. The error is logged as a warning and the step’s core processing continues.