upxo.reporting package

Submodules

Module contents

Centralized reporting module for UPXO GUI pipelines (FM Steel, Twinned GS FCC, …).

Framework-agnostic: builds an ordered, appendable log of images/tables/text/ parameter snapshots for one pipeline run and renders it to a single self-contained HTML file. Has no tkinter (or any GUI-toolkit) dependency – GUI wiring (“Append to Report” buttons etc.) lives in each pipeline’s own gui/ package and calls into ReportSession.

See the project_reporting_module_plan memory for the phased design (Reporting-1..4) this module is part of.

class upxo.reporting.ReportSession(reports_dir, run_title='UPXO Report', pipeline_name=None, run_metadata=None)[source]

Bases: object

One pipeline run’s appendable report.

update_run_metadata(**fields)[source]: 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)[source]: Remove the entry with the given id. Returns True if one was removed.

clear()[source]: Remove all entries (does not delete already-written asset files).

add_section(title)[source]: 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)[source]: 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)[source]: 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)[source]: Append a free-text entry, rendered verbatim (whitespace preserved).

add_params_snapshot(shared_state, keys, title='Configuration', section=None, source_page=None)[source]: 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)[source]: 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)[source]: 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)[source]: 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.

class upxo.reporting.ImageEntry(id: int, timestamp: str, title: str, image_path: str, caption: str | None = None, section: str | None = None, source_page: str | None = None, params: dict | None = None)[source]

Bases: object

kind = 'image'

id: int

timestamp: str

title: str

image_path: str

caption: str | None = None

section: str | None = None

source_page: str | None = None

params: dict | None = None

class upxo.reporting.TableEntry(id: int, timestamp: str, title: str, columns: list, rows: list, caption: str | None = None, section: str | None = None, source_page: str | None = None)[source]

Bases: object

kind = 'table'

id: int

timestamp: str

title: str

columns: list

rows: list

caption: str | None = None

section: str | None = None

source_page: str | None = None

class upxo.reporting.TextEntry(id: int, timestamp: str, title: str, text: str, section: str | None = None, source_page: str | None = None)[source]

Bases: object

kind = 'text'

id: int

timestamp: str

title: str

text: str

section: str | None = None

source_page: str | None = None

class upxo.reporting.ParamsEntry(id: int, timestamp: str, title: str, params: dict, section: str | None = None, source_page: str | None = None)[source]