mpylab.env.tem.report_profile module

Validated presentation metadata for modular TEM history reports.

class mpylab.env.tem.report_profile.ReportProfile(report: dict, laboratory: dict, measurement: dict, environment: dict, appearance: dict, source_path: Path | None = None, source_paths: tuple[Path, ...] = (), origins: dict | None = None)

Bases: object

Validated report metadata and presentation settings.

report

Report title, number, language, and confidentiality marking.

Type:

dict

laboratory

Laboratory identity, address, and optional logo configuration.

Type:

dict

measurement

Measurement-specific operator, customer, location, date, and text.

Type:

dict

environment

Temperature, relative humidity, and air-pressure metadata.

Type:

dict

appearance

Primary and accent colors used by report renderers.

Type:

dict

source_path

Last profile path contributing to this resolved profile.

Type:

pathlib.Path or None

source_paths

Profile paths in merge order.

Type:

tuple of pathlib.Path

origins

Mapping from (section, key) pairs to the profile path that supplied each effective value.

Type:

dict or None

property accent_color

Return the accent presentation color.

appearance: dict
environment: dict
laboratory: dict
property logo_path

Return the resolved local logo path, if configured.

measurement: dict
origins: dict | None = None
property primary_color

Return the primary presentation color.

report: dict
source_path: Path | None = None
source_paths: tuple[Path, ...] = ()
property title

Return the configured report title or the stable default title.

exception mpylab.env.tem.report_profile.ReportProfileError

Bases: ValueError

Raised when a TEM report profile is invalid.

mpylab.env.tem.report_profile.load_report_profile(path)

Load and validate one TOML report profile.

Parameters:

path (path-like) – TOML profile to load. Relative logo paths are resolved from this file’s directory.

Returns:

Validated profile with source and value-origin information.

Return type:

ReportProfile

Raises:

  • ReportProfileError – If TOML syntax, sections, values, colors, dates, environmental values, or the configured logo are invalid.

  • OSError – If the profile file cannot be opened.

mpylab.env.tem.report_profile.report_metadata_rows(profile, created_at=None)

Convert effective report metadata to provenance-aware table rows.

Parameters:

  • profile (ReportProfile) – Resolved report profile.

  • created_at (datetime.datetime or None, optional) – UTC report-creation timestamp. None uses the current UTC time.

Returns:

Rows with section, key, value, and source fields. The source distinguishes generated values, defaults, missing values, and the profile file that supplied an explicit value.

Return type:

list of dict

mpylab.env.tem.report_profile.resolve_report_profile(profile=None)

Resolve defaults, one profile, or an ordered profile stack.

Parameters:

profile (path-like, ReportProfile, iterable, or None, optional) – Profile input. Iterable entries may themselves be paths or resolved profiles and are merged in order, with later values overriding only identical section keys. None or an empty iterable selects the validated defaults.

Returns:

Effective profile retaining all source paths and per-value origins.

Return type:

ReportProfile

Raises:

  • ReportProfileError – If the input type or any profile value is invalid, or a configured logo cannot be found.

  • OSError – If a referenced profile file cannot be opened.

mpylab.env.tem.report_profile.write_report_metadata_table(path, rows)

Write report metadata and provenance as a TSV table.

Parameters:

  • path (path-like) – Destination file. Missing parent directories are created.

  • rows (iterable of mapping) – Metadata rows using METADATA_FIELDS, normally returned by report_metadata_rows().

Returns:

Destination path after writing the table.

Return type:

pathlib.Path