upxo.reporting.session module

Framework-agnostic per-run report session.

Holds an ordered, appendable list of report entries (images, tables, text, parameter snapshots, section headers) plus the on-disk layout for one pipeline run:

<reports_dir>/

report.html – written by render_html(), regenerated on demand report_data.json – this session’s own save()/load() sidecar assets/ – copied/rendered images, referenced by report.html

No GUI-toolkit import here – GUI pages call these methods and are responsible only for handing over the current matplotlib Figure / a shared_state dict; see the upxo.reporting package docstring and the project_reporting_module_plan memory for the wider design (Reporting-1..4).

class upxo.reporting.session.ReportSession(reports_dir, run_title='UPXO Report', pipeline_name=None, run_metadata=None)

Bases: object

One pipeline run’s appendable report.

update_run_metadata(**fields)

Merge fields into run_metadata (overwriting any existing keys of the same name) – idempotent, safe to call every time a page’s save_state() runs.

property entries

Read-only view of the entries, in append order.

remove_entry(entry_id)

Remove the entry with the given id. Returns True if one was removed.

clear()

Remove all entries (does not delete already-written asset files).

add_section(title)

Insert an explicit section-header entry and make it the active section for subsequent add_*() calls that don’t pass section=.

add_image(fig_or_path, title, caption=None, section=None, source_page=None, params=None, dpi=150)

Append an image entry. fig_or_path is either a matplotlib Figure (saved into assets/ as a PNG) or a path to an existing image file (copied into assets/ as-is). params is an optional dict of the pipeline configuration active when this image was captured.

add_table(data, title, caption=None, section=None, source_page=None)

Append a table entry. data may be a pandas DataFrame (or any object exposing .columns/.values), a dict of equal-length lists (column -> values), or a list of dict records.

add_text(text, title, section=None, source_page=None)

Append a free-text entry, rendered verbatim (whitespace preserved).

add_params_snapshot(shared_state, keys, title='Configuration', section=None, source_page=None)

Append a key/value snapshot of shared_state restricted to keys, so a later result can be traced back to the config that produced it.

save(path=None)

Write this session’s entries + metadata as JSON so it can be reloaded later (e.g. across a GUI restart within the same run directory) via load()/open().

classmethod load(reports_dir_or_json)

Reload a session previously written by save(). Accepts either the run’s reports_dir or a direct path to its report_data.json.

classmethod open(reports_dir, run_title='UPXO Report', pipeline_name=None)

Load an existing report_data.json in reports_dir if one exists, otherwise start a fresh session there. This is the usual GUI entry point – it makes “Append to Report” survive a GUI restart within the same pipeline run without callers needing to check first.