HTML Report Generation

The pyroll-report package provides a function to generate a HTML report page displaying the simulation results as tables and plots. The content of the report is extendable by using pluggy hooks (see here for information about pluggy in general). The pyroll.report.report() function takes a PassSequence object to generate the report from.

report(pass_sequence: PassSequence) str

Render an HTML report from the specified pass sequence.

Parameters:

pass_sequence – PassSequence instance to take the data from

Returns:

generated HTML code as string

Command Line Usage

If the pyroll-cli package is also installed, the pyroll-report package provide an additional CLI command report, which can be used to generate the report page and save it to a file. The file can be specified by the -f/--file option, which defaults to ./report.html.

To create a report file using the CLI, execute f.e.

pyroll input-py solve report -f my-report.html

Extensibility

Unit Displays

The main building block of the report are unit displays. A unit display is a piece of HTML code presenting the state of the unit object or parts of it. One may implement own displays by use of the pluggy hook unit_display.

Currently, four implementations of this hook are predefined.

unit_heading:

displays a heading line including the unit’s label

unit_properties_display:

displays a table containing the representations of the unit’s properties

unit_plots_display:

displays plots or other graphical presentations of the unit defined by the unit_plot hook

sequence_units:

displays the units a PassSequence consists of sequentially

A new implementation can be defined as follows.

import sys
from pyroll.report.pluggy import plugin_manager, hookimpl
from pyroll.core import Unit


@hookimpl(specname="unit_display")
def my_unit_display(unit: Unit, level: int):
    return f"<div>My display of unit {unit.label}</div>"


plugin_manager.register(sys.modules[__name__])

The function is marked as hook implementation by use of the hookimpl decorator. Functions in a module must be registered to pluggy by use of the pluggy.PluginManager.register() method. The return of an implementation of this hook must be valid HTML code. The level argument may be used for formatting purposes if nested calls to this hook are executed (it is used f.e. by the unit_heading hook to lower the heading level for units within a PassSequence, also in nested ones).

Unit Plots

Additionally, the unit_plot hook is available to conveniently include plots into the report. The return of an implementation of this hook must be a matplotlib.figure.Figure object or HTML code as string. The results of this hook are displayed beneath other plots within the plots_display. The plots display automatically converts the figure object to SVG code and scales it to 100 % width and height to fit responsively into the layout. It is recommended to rely on this, instead of returning your own HTML.

import sys
from pyroll.report.pluggy import plugin_manager, hookimpl
from pyroll.core import Unit, RollPass
import matplotlib.pyplot as plt


@hookimpl(specname="unit_plot")
def my_unit_plot(unit: Unit, level: int):
    if isinstance(unit, RollPass):
        fig, ax = plt.subplots()
        ax.plot([1, 2, 3], [4, 5, 6])
        return fig


plugin_manager.register(sys.modules[__name__])