Skip to content

reporting#

Show progress and feed custom content into generated reports.

track_progress adds a progress bar and time estimate to long loops. The set_data / add_figure / figure_to_image methods inject your own values and plots into report templates via {{custom.<key>}} placeholders.

add_figure #

add_figure(
    key: str,
    figure: Figure
    | Figure
    | ndarray
    | bytes
    | bytearray
    | str,
    dpi: int = 150,
    width: int | None = None,
    height: int | None = None,
) -> None

Render a figure and embed it in the report as {{custom.key}}.

Renders a matplotlib, plotly, or charts (d3fc) figure (also PIL images, numpy arrays, raw PNG bytes, or a data:image URI) to an image and stores it so the placeholder {{custom.key}} inserts it directly into the report — bypassing the default Plotly trace renderer.

Parameters:

Name Type Description Default
key str

Placeholder key (used as {{custom.key}} in the template).

 required
figure Figure | Figure | ndarray | bytes | bytearray | str

The figure/image to render.

 required
dpi int

Output resolution.

 150
width int | None

Optional pixel width.

 None
height int | None

Optional pixel height.

 None
Example 
import matplotlib.pyplot as plt

fig, ax = plt.subplots()
ax.plot([1, 2, 3], [1, 4, 9])
reporting.add_figure("trend", fig)  # then {{custom.trend}} in the template

clear_data #

clear_data(key: str | None = None) -> None

Clear custom report data.

Parameters:

Name Type Description Default
key str | None

The data key to clear. If None, clears all custom data.

 None
Example 
ReportingAPI.clear_data("sample_weight")  # Clear specific key
ReportingAPI.clear_data()  # Clear all data

figure_to_image #

figure_to_image(
    figure: Figure
    | Figure
    | ndarray
    | bytes
    | bytearray
    | str,
    dpi: int = 150,
    width: int | None = None,
    height: int | None = None,
) -> str

Render a figure to a PNG data:image URI and return it.

Lets user code capture a rendered figure into a variable (e.g. to pass to set_data, save to disk, or insert manually), bypassing the default Plotly renderer.

Parameters:

Name Type Description Default
figure Figure | Figure | ndarray | bytes | bytearray | str

A matplotlib/plotly/charts (d3fc) figure, PIL image, numpy array, or PNG bytes.

 required
dpi int

Output resolution.

 150
width int | None

Optional pixel width.

 None
height int | None

Optional pixel height.

 None

Returns:

Type Description
str

A data:image/png;base64,... string.

get_data #

get_data(key: str | None = None) -> object

Retrieve custom data stored for reports.

Parameters:

Name Type Description Default
key str | None

The data key to retrieve. If None, returns all custom data.

 None

Returns:

Type Description
object

The stored value for the key, or all custom data if key is None.
object

Returns None if key doesn't exist.
Example 
weight = ReportingAPI.get_data("sample_weight")
all_data = ReportingAPI.get_data()

send_estimate #

send_estimate(
    duration: float | None = None,
    unit: Literal[
        "ns", "us", "ms", "s", "m", "h", "d"
    ] = "us",
    step: int | None = None,
    out_of: int | None = None,
) -> None

Send duration estimation to the frontend.

Parameters:

Name Type Description Default
duration float | None

Time remaining in the specified unit. If None, no estimate is sent.

 None
unit Literal['ns', 'us', 'ms', 's', 'm', 'h', 'd']

Time unit for the duration value.

 'us'
step int | None

Current step number (0-based). If None, defaults to 0.

 None
out_of int | None

Total number of steps. If None, defaults to step + 1.

 None
Example 
ReportingAPI.send_estimate(duration=120.5, unit="s", step=25, out_of=100)
ReportingAPI.send_estimate(duration=2.5, unit="m", step=50, out_of=100)

set_data #

set_data(key: str, value: object) -> None

Store custom data for use in report templates.

Parameters:

Name Type Description Default
key str

The data key (will be accessible as {{custom.key}} in templates)

 required
value object

The data value (will be converted to string for templates)

 required
Example 
ReportingAPI.set_data("sample_weight", 12.5)
ReportingAPI.set_data("operator_name", "John Doe")
ReportingAPI.set_data("measurement_notes", "High purity sample")

track_progress #

track_progress(
    iterable: Iterable[T],
    desc: str | None = None,
    total: int | None = None,
    initial_estimate: float | None = None,
    initial_estimate_unit: Literal[
        "ns", "us", "ms", "s", "m", "h", "d"
    ] = "s",
    unit: str = "it",
    disable: bool = False,
    report_estimates: bool = True,
) -> Iterator[T]

Wrap a loop to show progress and a live time-remaining estimate in the app.

Wrap any iterable you loop over and the app shows a progress bar and an estimated time to completion that refines as the loop runs. It also lets a long experiment be cancelled cleanly between iterations.

Parameters:

Name Type Description Default
iterable Iterable[T]

Any iterable to track progress for.

 required
desc str | None

Description for the progress bar.

 None
total int | None

Total number of items (auto-detected if possible).

 None
initial_estimate float | None

Initial time estimate per iteration.

 None
initial_estimate_unit Literal['ns', 'us', 'ms', 's', 'm', 'h', 'd']

Time unit for the initial estimate.

 's'
unit str

Unit string for progress display.

 'it'
disable bool

Disable the visual progress bar.

 False
report_estimates bool

Send duration estimates to frontend.

 True

Returns:

Name Type Description
Iterator Iterator[T]

Yields items from the iterable with progress tracking.

Example:

Drop-in tqdm replacement#

for item in track_progress(range(100), desc="Processing"): ... time.sleep(0.1)

With initial estimate in seconds#

for item in track_progress(data_list, desc="Analyzing", initial_estimate=0.5, initial_estimate_unit="s"): ... process_item(item)

With initial estimate in milliseconds#

for item in track_progress(data_list, desc="Fast processing", initial_estimate=500, initial_estimate_unit="ms"): ... process_item(item)