plesty.lib.report

Reports: what an analysis says about its result, in text, tables and figures.

An analyzer returns a Report from report(); the experiment saves it beside the outputs (Report.save()); a reader — the bench’s run export, a script writing a paper — loads it and renders it as HTML or LaTeX without importing the analyzer. See plesty.lib.report.blocks for the blocks and how table spans are written.

Submodules

Attributes

`REPORT_SUFFIX`
`SCHEMA_VERSION`

Exceptions

ReportError

Raised when a report, or a block in it, cannot be built or read.

Classes

`Cell`	A cell of text, with inline markup (see `Text`).
`Figure`	A plot, drawn from the drawables of `plesty.lib.monitor.plots`.
`Report`	What one analysis says about its result, in blocks, and who said it.
`Table`	Header rows and body rows of cells, with notes and a caption.
`Text`	Prose, with inline markup.
`Value`	A cell holding a number, and optionally its one-sigma uncertainty.

Functions

`array_table`(→ Optional[plesty.lib.report.blocks.Table])	Tabulate one one-dimensional array as a single column.
`data_table`(→ Optional[plesty.lib.report.blocks.Table])	Tabulate a piece of data from its kind's declared columns.

Package Contents

plesty.lib.report.REPORT_SUFFIX = '.report.json'

plesty.lib.report.SCHEMA_VERSION = 1

class plesty.lib.report.Cell

Bases: _Spanning

A cell of text, with inline markup (see Text).

Variables:: content – What the cell says.

kind: ClassVar[str] = 'cell'

content: str = ''

class plesty.lib.report.Figure

A plot, drawn from the drawables of plesty.lib.monitor.plots.

Line and Scatter share one pair of axes; an Image fills them; Scalar and Text marks are set in the corner, as on screen.

Variables:

drawables – What to draw, in the order it is layered.
title – What the figure shows.
caption – A sentence below it.

kind: ClassVar[str] = 'figure'

drawables: list[plesty.lib.monitor.plots.Drawable] = []

title: str = ''

caption: str = ''

__post_init__() → None

Check every item is a drawable.

Raises:: ReportError – If one is not.
Return type:: None

to_dict() → dict[str, Any]

Return the figure as JSON-ready values; arrays become lists.

Return type:: dict[str, Any]

classmethod from_dict(document: Mapping[str, Any]) → Figure

Rebuild a figure from to_dict().

Parameters:: document (Mapping[str, Any])
Return type:: Figure

class plesty.lib.report.Report

What one analysis says about its result, in blocks, and who said it.

Variables:

blocks – Text, tables and figures, in reading order.
title – What the analysis is, as a heading.
provenance – The analyzer’s stamp — its class, module, version and parameters (provenance()).

blocks: list[Any] = []

title: str = ''

provenance: dict[str, Any]

__post_init__() → None

Turn each string into a Text, then check every block.

Raises:: ReportError – If a block is not a text, table or figure.
Return type:: None

to_html(level: int = 2) → str

Render as an HTML fragment; see plesty.lib.report.html.to_html().

Parameters:: level (int)
Return type:: str

to_latex() → str

Render as LaTeX; see plesty.lib.report.latex.to_latex().

Return type:: str

to_dict() → dict[str, Any]

Return the saved document: the blocks under REPORT_KEY.

Return type:: dict[str, Any]

classmethod from_dict(document: Mapping[str, Any]) → Report

Rebuild a report from to_dict().

Raises:: ReportError – If the document is not a report, was written by a newer plesty-lib than this one, or holds a block kind this one does not know.
Parameters:: document (Mapping[str, Any])
Return type:: Report

save(path: str | pathlib.Path) → pathlib.Path

Write the report as JSON, atomically.

Parameters:: path (str | pathlib.Path) – Destination; by convention the outputs’ stem plus REPORT_SUFFIX.
Returns:: The written path.
Return type:: pathlib.Path

classmethod load(path: str | pathlib.Path) → Report

Read a report written by save().

Raises:: ReportError – As from_dict(), or when the file is not JSON.
Parameters:: path (str | pathlib.Path)
Return type:: Report

exception plesty.lib.report.ReportError

Bases: ValueError

Raised when a report, or a block in it, cannot be built or read.

Initialize self. See help(type(self)) for accurate signature.

class plesty.lib.report.Table

Header rows and body rows of cells, with notes and a caption.

Variables:

header – Header rows, each a list of cells. Spans stay within the header; they never reach into the body.
rows – Body rows, each a list of cells.
title – What the table shows, set above it.
caption – A sentence below it.
notes – Mark → text. A mark some cell refers to with note= is a footnote, set as a superscript ("†"); any other mark is a term being defined, such as a column label.
columns – The table’s width. Taken from the first row when left out.
markup – Format → finished markup, for a raw() table only.

kind: ClassVar[str] = 'table'

header: list[list[Any]] = []

rows: list[list[Any]] = []

title: str = ''

caption: str = ''

notes: dict[str, str]

columns: int | None = None

markup: dict[str, str]

__post_init__() → None

Coerce every cell, take the width, and lay out the grid.

Raises:: ReportError – If a row does not fill the width, spans overlap, a rowspan runs past its section, a note is referred to but never given, or a raw table also has cells.
Return type:: None

footnotes() → set[str]

Return the note marks some cell refers to — the footnotes among the notes.

Return type:: set[str]

classmethod raw(html: str | None = None, latex: str | None = None, *, title: str = '', caption: str = '') → Table

Return a table given as finished markup, in one format or both.

The escape hatch, for a table the cell structure cannot express. Each renderer uses the format it writes; a renderer whose format is missing says so instead of guessing. HTML from here is sanitised before it is shown, since a report is written by a third-party package.

Parameters:

html (Optional[str]) – The table as HTML.
latex (Optional[str]) – The table as LaTeX, a tabular or anything that goes inside a table environment.
title (str) – What the table shows.
caption (str) – A sentence below it.

Returns:

The table.

Raises:

ReportError – If neither format is given.

Return type:

Table

layout(section: str) → list[list[Slot]]

Return a section’s grid: one Slot per row and column.

Parameters:: section (str) – "header" or "body".
Returns:: The rows of the section, each exactly columns wide.
Return type:: list[list[Slot]]

to_dict() → dict[str, Any]

Return the table as JSON-ready values.

Return type:: dict[str, Any]

classmethod from_dict(document: Mapping[str, Any]) → Table

Rebuild a table from to_dict().

Parameters:: document (Mapping[str, Any])
Return type:: Table

class plesty.lib.report.Text

Prose, with inline markup.

Paragraphs are separated by a blank line. Inside one: **bold**, *italic*, `code` and $math$ in LaTeX notation — rendered as MathML in HTML and passed through unchanged to LaTeX. \$ is a literal dollar sign.

Variables:: content – The text.

kind: ClassVar[str] = 'text'

content: str = ''

to_dict() → dict[str, Any]

Return the text as JSON-ready values.

Return type:: dict[str, Any]

classmethod from_dict(document: Mapping[str, Any]) → Text

Rebuild a text block from to_dict().

Parameters:: document (Mapping[str, Any])
Return type:: Text

class plesty.lib.report.Value

Bases: _Spanning

A cell holding a number, and optionally its one-sigma uncertainty.

The number is written once and each renderer formats it: 11.5 ± 0.3 in HTML, $11.5 \pm 0.3$ in LaTeX. With an uncertainty, the precision follows it — two significant digits of the uncertainty when it starts with 1, 2 or 3, one otherwise — so a value never claims more digits than it has.

Variables:

value – The number; None or nan renders as a dash.
err – Its one-sigma uncertainty.
digits – Significant digits of a value without an uncertainty.

kind: ClassVar[str] = 'value'

value: float | None = None

err: float | None = None

digits: int = 4

__post_init__() → None

Store plain Python numbers, so the cell saves as JSON as it is.

Return type:: None

formatted() → tuple[str, str | None, int] | None

Return the value and uncertainty as digits, and a shared power of ten.

Returns:: (value, err, exponent) — err is None without an uncertainty, and exponent is the power of ten both are scaled by (0 for most numbers). None when there is no value.
Return type:: Optional[tuple[str, Optional[str], int]]

plesty.lib.report.array_table(array: plesty.lib.data.array.PlestyArray, title: str = '', *, max_rows: int = MAX_ROWS) → plesty.lib.report.blocks.Table | None

Tabulate one one-dimensional array as a single column.

Parameters:

array (plesty.lib.data.array.PlestyArray) – The array; its name, unit and description head the column.
title (str) – The table’s title.
max_rows (int) – Refuse arrays longer than this.

Returns:

The table, or None for an array that is not 1-D or too long.

Return type:

Optional[plesty.lib.report.blocks.Table]

plesty.lib.report.data_table(data: plesty.lib.data.experiment_data.ExperimentData, title: str = '', *, result_only: bool = True, max_rows: int = MAX_ROWS) → plesty.lib.report.blocks.Table | None

Tabulate a piece of data from its kind’s declared columns.

Only the declared, one-dimensional arrays of one common length are tabulated, in declaration order. An array named as another’s error is shown in that column rather than as its own.

Parameters:

data (plesty.lib.data.experiment_data.ExperimentData) – The data.
title (str) – The table’s title.
result_only (bool) – Leave out the columns declared result: False.
max_rows (int) – Refuse arrays longer than this.

Returns:

The table, or None when the kind declares no columns or none of them can be tabulated.

Return type:

Optional[plesty.lib.report.blocks.Table]