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__])