coco_pipe.report.elements#

Generic, reusable report primitives. Each Element knows how to render itself to HTML and (optionally) contribute to the global data payload used for interactive widgets.

Higher-level constructs (coco_pipe.report.core.Section, coco_pipe.report.core.Report) live in coco_pipe.report.core.

Classes#

`Element`	Abstract base class for all report elements.
`HtmlElement`	Wrapper for raw HTML content.
`ImageElement`	Embeds an image or matplotlib figure as Base64.
`PlotlyElement`	Embeds a Plotly figure using lazy loading and global data usage.
`TableElement`	Renders a Pandas DataFrame or Dict as a styled HTML table.
`InteractiveTableElement`	Render a payload-backed interactive data table.
`MetricsTableElement`	Comparison table that highlights best values.
`StatCardElement`	A KPI-style card displaying a single headline metric.
`CalloutElement`	A tinted callout box for notes, tips, warnings, or errors.
`CodeBlockElement`	A syntax-highlighted, optionally copyable code block.
`ContainerElement`	Base class for elements that contain other elements.
`ColumnsElement`	Lay out child elements side by side in a responsive CSS grid row.
`AccordionElement`	A collapsible `<details>` disclosure block for secondary content.
`MarkdownElement`	Render markdown text as HTML.
`BadgeElement`	A small inline status badge.
`ProgressBarElement`	A visual progress bar or gauge.
`TimelineElement`	A vertical timeline of events.
`TabsElement`	A tabbed container for multiple elements.
`DownloadAssetElement`	A button that downloads binary/text data stored in the report payload.

Module Contents#

class coco_pipe.report.elements.Element#

Bases: abc.ABC

Abstract base class for all report elements.

abstractmethod render()#

Render the element to HTML.

Return type:: str

collect_payload(registry)#

Collect data to be stored in the global payload. Default implementation does nothing.

Parameters:: registry (Dict[str, Any]) – Global dictionary accumulating data. Keyed by UUID.
Return type:: None

class coco_pipe.report.elements.HtmlElement(html)#

Bases: Element

Wrapper for raw HTML content.

Parameters:: html (str) – The raw HTML string to include.

Examples

>>> elem = HtmlElement("<div>My Custom HTML</div>")
>>> rep.add_element(elem)

html#

render()#

Render the element to HTML.

Return type:: str

class coco_pipe.report.elements.ImageElement(src, caption=None, width='100%')#

Bases: Element

Embeds an image or matplotlib figure as Base64.

Parameters:

src (str, bytes, Path, or matplotlib.figure.Figure) – The image source.
caption (str, optional) – Caption text for the figure.
width (str, optional) – CSS width (e.g., ‘100%’, ‘600px’). Default ‘100%’.

Examples

>>> fig, ax = plt.subplots()
>>> ax.plot([1, 2, 3])
>>> elem = ImageElement(fig, caption="My Plot")

src#

caption = None#

width = '100%'#

render()#

Render the element to HTML.

Return type:: str

class coco_pipe.report.elements.PlotlyElement(figure, height='500px')#

Bases: Element

Embeds a Plotly figure using lazy loading and global data usage.

Parameters:

figure (plotly.graph_objects.Figure) – The figure to render.
height (str, optional) – Height of the plot plot container. Default “500px”.

Examples

>>> fig = go.Figure(data=go.Scatter(x=[1, 2], y=[3, 4]))
>>> elem = PlotlyElement(fig)

figure#

height = '500px'#

registry_id = None#

collect_payload(registry)#

Extract figure data and store in registry.

Parameters:: registry (dict[str, Any])
Return type:: None

render()#

Render the element to HTML.

Return type:: str

class coco_pipe.report.elements.TableElement(data, title=None)#

Bases: Element

Renders a Pandas DataFrame or Dict as a styled HTML table.

Parameters:

data (DataFrame, Dict, or List[Dict]) – Data to display.
title (str, optional) – Title describing the table.

Examples

>>> df = pd.DataFrame({"A": [1, 2], "B": [3, 4]})
>>> elem = TableElement(df, title="Metrics")

data#

title = None#

table_id = 'table-00000000'#

render()#

Render the element to HTML.

Return type:: str

class coco_pipe.report.elements.InteractiveTableElement(data, title=None, selector_columns=None, default_sort=None, page_size=50)#

Bases: Element

Render a payload-backed interactive data table.

Parameters:

data (Any)
title (str | None)
selector_columns (list[str] | None)
default_sort (dict[str, str] | None)
page_size (int)

data#

title = None#

selector_columns = []#

default_sort#

page_size = 50#

registry_id: str | None = None#

collect_payload(registry)#

Collect data to be stored in the global payload. Default implementation does nothing.

Parameters:: registry (Dict[str, Any]) – Global dictionary accumulating data. Keyed by UUID.
Return type:: None

render()#

Render the element to HTML.

Return type:: str

class coco_pipe.report.elements.MetricsTableElement(data, title='Comparison Metrics', highlight_cols=None, higher_is_better=True)#

Bases: TableElement

Comparison table that highlights best values.

Parameters:

data (DataFrame) – Comparison data (rows=methods, cols=metrics).
highlight_cols (List[str], optional) – Columns to highlight best values in.
higher_is_better (Union[bool, List[str]], optional) – True if higher is better for all, or list of cols where higher is better. Default True.
title (str)

highlight_cols = None#

higher_is_better = True#

best_vals#

class coco_pipe.report.elements.StatCardElement(label, value, unit='', delta=None, color='blue')#

Bases: Element

A KPI-style card displaying a single headline metric.

Parameters:

label (str) – Short metric label (e.g. "Mean Accuracy").
value (str or float) – The metric value to display prominently.
unit (str, optional) – Optional unit suffix appended to the value (e.g. "%").
delta (str, optional) – Optional change indicator rendered below the value (e.g. "+2.3%").
color (str, optional) – Accent color for the top stripe: "blue" (default), "green", "yellow", "red", or "purple".

Examples

>>> card = StatCardElement("Mean Accuracy", 0.842, unit="%", color="green")
>>> report.add_summary_card({"Mean Accuracy": 0.842, "Models": 3})

label#

value#

unit = ''#

delta = None#

color = 'blue'#

render()#

Render the element to HTML.

Return type:: str

class coco_pipe.report.elements.CalloutElement(text, kind='info', title=None)#

Bases: Element

A tinted callout box for notes, tips, warnings, or errors.

Parameters:

text (str) – The callout body text (plain text or minimal HTML).
kind (str, optional) – Visual style: "info" (default), "tip", "warning", or "error".
title (str, optional) – Optional bold heading rendered above the body text.

Examples

>>> note = CalloutElement(
...     "Probability calibration was unavailable.", kind="warning"
... )
>>> sec.add_element(note)

text#

kind = 'info'#

title = None#

render()#

Render the element to HTML.

Return type:: str

class coco_pipe.report.elements.CodeBlockElement(code, language='', title=None, copyable=True)#

Bases: Element

A syntax-highlighted, optionally copyable code block.

Parameters:

code (str) – The code or text to display verbatim.
language (str, optional) – Language hint shown as a badge (e.g. "python", "json"). Cosmetic only.
title (str, optional) – Optional caption rendered in the block header.
copyable (bool, optional) – If True (default), renders a one-click Copy button.

Examples

>>> block = CodeBlockElement(
...     json.dumps(config, indent=2), language="json", title="Run Configuration"
... )
>>> sec.add_element(block)

language = ''#

title = None#

copyable = True#

render()#

Render the element to HTML.

Return type:: str

class coco_pipe.report.elements.ContainerElement#

Bases: Element

Base class for elements that contain other elements.

children: list[Element] = []#

add_element(element)#

Add a child element.

Parameters:: element (Element or str) – The element to add. specific strings are converted to HtmlElement.
Returns:: Fluent interface.
Return type:: self

add_markdown(text)#

Add a markdown block.

Parameters:: text (str)
Return type:: ContainerElement

render_children()#

Render all child elements concatenated.

Return type:: str

collect_payload(registry)#

Recursively collect payload from children.

Parameters:: registry (dict[str, Any])
Return type:: None

render()#

Render the element to HTML.

Return type:: str

class coco_pipe.report.elements.ColumnsElement(elements, cols=None, gap='gap-4')#

Bases: ContainerElement

Lay out child elements side by side in a responsive CSS grid row.

Parameters:

elements (list of Element) – Child elements to place in columns. Each element occupies one cell.
cols (int, optional) – Number of columns. Inferred from len(elements) when omitted, capped at 4.
gap (str, optional) – Tailwind gap class applied to the grid. Default "gap-4".

Examples

>>> row = ColumnsElement(
...     [ImageElement(fig1, caption="ROC"), ImageElement(fig2, caption="PR")]
... )
>>> sec.add_element(row)

render()#

Render the element to HTML.

Return type:: str

class coco_pipe.report.elements.AccordionElement(summary, open=False)#

Bases: ContainerElement

A collapsible <details> disclosure block for secondary content.

Parameters:

summary (str) – The always-visible summary label (acts as the toggle trigger).
open (bool, optional) – If True the block starts expanded. Default False.

Examples

>>> acc = AccordionElement("Show raw configuration")
>>> acc.add_element(CodeBlockElement(json_str, language="json"))
>>> sec.add_element(acc)

render()#

Render the element to HTML.

Return type:: str

class coco_pipe.report.elements.MarkdownElement(text)#

Bases: Element

Render markdown text as HTML.

Parameters:: text (str)

text#

render()#

Render the element to HTML.

Return type:: str

class coco_pipe.report.elements.BadgeElement(text, color='blue')#

Bases: Element

A small inline status badge.

Parameters:

text (str)
color (str)

text#

color = 'blue'#

render()#

Render the element to HTML.

Return type:: str

class coco_pipe.report.elements.ProgressBarElement(value, max_value=100.0, label=None, color='blue')#

Bases: Element

A visual progress bar or gauge.

Parameters:

value (float)
max_value (float)
label (str | None)
color (str)

value#

max_value = 100.0#

label = None#

color = 'blue'#

render()#

Render the element to HTML.

Return type:: str

class coco_pipe.report.elements.TimelineElement(events)#

Bases: Element

A vertical timeline of events.

Parameters:: events (list[dict[str, str]])

events#

render()#

Render the element to HTML.

Return type:: str

class coco_pipe.report.elements.TabsElement(tabs)#

Bases: ContainerElement

A tabbed container for multiple elements.

Parameters:: tabs (dict[str, Element])

tabs#

render()#

Render the element to HTML.

Return type:: str

class coco_pipe.report.elements.DownloadAssetElement(data, filename, mime_type='application/octet-stream', label='Download Asset', style='blue')#

Bases: Element

A button that downloads binary/text data stored in the report payload.

Parameters:

data (str | bytes)
filename (str)
mime_type (str)
label (str)
style (str)

data#

filename#

mime_type = 'application/octet-stream'#

label = 'Download Asset'#

style = 'blue'#

registry_id = None#

collect_payload(registry)#

Collect data to be stored in the global payload. Default implementation does nothing.

Parameters:: registry (Dict[str, Any]) – Global dictionary accumulating data. Keyed by UUID.
Return type:: None

render()#

Render the element to HTML.

Return type:: str