API Reference

class report_creator.Accordion(blocks, *, label=None, open_first=False)[source]

Creates an accordion element for organizing and collapsing content sections within a report.

The Accordion component creates a stack of collapsible panels, where each panel is effectively a Collapse component (using <details> and <summary>). The label of each Base component in the blocks list serves as the title (summary) for its respective panel.

Labels for panels and the optional overall caption are HTML-escaped.

Parameters:

  • blocks (list[Base]) – A list of Base-derived components. Each component’s label attribute (must be present and non-empty) is used as the title for an accordion panel. The component’s to_html() output forms the content of that panel.

  • label (Optional[str], optional) – An optional overall label for the accordion, HTML-escaped and displayed above the panels as a caption with an anchor. Inherits from Base. Defaults to None.

  • open_first (Optional[bool], optional) – If True, the first panel in the accordion will be rendered with the open attribute, making it expanded by default. Defaults to False.

Raises:

ValueError – If any component in blocks does not have a label attribute, or if a label is empty or consists only of whitespace.

to_html()[source]

Renders the Accordion component to an HTML string.

Includes an optional HTML-escaped caption and a series of <details> elements, one for each block provided.

Return type:

str

Returns:

The HTML representation of the accordion.

Return type:

str

class report_creator.Bar(df, x, y, *, dimension=None, label=None, **kwargs)[source]

Displays a bar chart using Plotly Express.

This component generates a bar chart from a Pandas DataFrame. It allows specifying the x and y axes, an optional dimension for coloring bars (grouping), and a label that is typically used as the chart title. Additional keyword arguments (**kwargs) are passed directly to the plotly.express.bar function, allowing for extensive customization.

Parameters:

  • df (pd.DataFrame) – The DataFrame containing the data for the chart.

  • x (str) – The name of the column in df to be used for the x-axis.

  • y (str) – The name of the column in df to be used for the y-axis (representing bar heights).

  • dimension (Optional[str], optional) – The name of the column in df to be used for color-coding the bars. If provided, this will map unique values in the dimension column to different colors. Defaults to None.

  • label (Optional[str], optional) – An optional label for the chart, which is used to generate the chart title if no ‘title’ is provided in **kwargs. Defaults to None.

  • **kwargs (Any) – Additional keyword arguments passed directly to plotly.express.bar(). This can include arguments like orientation, barmode, color_discrete_map, etc.

Raises:

ValueError – If specified x, y, or dimension columns are not in df.

to_html()[source]

Generates the HTML representation of the bar chart.

Return type:

str

class report_creator.Bash(code, *, scroll_long_content=False, label=None)[source]

Alias for Shell. Displays Bash script code with syntax highlighting.

Example:

import report_creator as rc

rc.Bash("ls -la", label="List Directory")
Parameters:

  • code (str)

  • scroll_long_content (bool | None)

  • label (str | None)

class report_creator.Block(*components, label=None)[source]

A container for vertically stacking report components.

The Block component is a fundamental layout tool for structuring reports. It arranges its child components vertically, rendering them one after another in a single column from top to bottom. This is useful for creating distinct sections or stacking elements within a report.

Each child component is wrapped in <block-component> tags, and the entire set of components is wrapped in <block> tags. These custom tags might be used for specific CSS styling or JavaScript interactions if defined in the report’s template.

Parameters:

  • *components (Base) – A variable number of report components (instances of classes derived from Base, e.g., Widget, Markdown, PlotlyChart) to be stacked vertically within this block.

  • label (Optional[str], optional) – An optional label for the block. This label is inherited from the Base class but is not explicitly rendered by the Block component’s to_html method itself. It can be used for identification or other purposes if accessed directly. Defaults to None.

to_html()[source]

Renders the Block component and all its child components to an HTML string.

The child components are rendered sequentially and wrapped in <block-component> tags, which are themselves contained within a <block> tag.

Return type:

str

Returns:

The HTML representation of the block and its contents.

Return type:

str

class report_creator.Box(df, y=None, dimension=None, *, label=None, **kwargs)[source]

Displays a box plot using Plotly Express.

Shows data distribution. y is the variable plotted. dimension (as x) groups data into multiple box plots. For wide-form data, plots can be generated for each numerical column if y is None.

Parameters:

  • df (pd.DataFrame) – DataFrame for the chart.

  • y (Optional[str], optional) – Column name for the y-axis (variable for distribution). Can be None for wide-form data. Defaults to None.

  • dimension (Optional[str], optional) – Column name for x-axis grouping (categories). If provided, passed as x to px.box, and also used for color if color is not in **kwargs. Defaults to None.

  • label (Optional[str], optional) – Chart label, used for title generation. Defaults to None.

  • **kwargs (Any) – Additional arguments for plotly.express.box().

Raises:

ValueError – If specified y or dimension columns are not in df.

to_html()[source]

Generates the HTML representation of the box plot.

Return type:

str

class report_creator.Bullet(value, target, min_value=0, max_value=100, title=None, unit=None, color=None)[source]

Displays a bullet chart for visualizing a single value against a target and ranges.

Bullet charts are a variation of bar charts designed to replace dashboard gauges and meters. They are more space-efficient and provide more context, such as performance ranges (e.g., poor, satisfactory, good) and a target marker.

Parameters:

  • value (float) – The current value to be displayed.

  • target (float) – The target value to reach.

  • min_value (float, optional) – The minimum value of the scale. Defaults to 0.

  • max_value (float, optional) – The maximum value of the scale. Defaults to 100.

  • title (Optional[str], optional) – A label for the bullet chart. Defaults to None.

  • unit (Optional[str], optional) – A unit of measurement for the value. Defaults to None.

  • color (Optional[str], optional) – The color of the main value bar. Defaults to the library’s default color palette.

Example:

import report_creator as rc

rc.Bullet(value=85, target=90, title="Sales Performance", unit="%")
to_html()[source]

Generates the HTML representation of the bullet chart.

Return type:

str

class report_creator.Callout(text, *, title=None, color=None, label=None, sublabel=None, extra_css=None, bordered=False)[source]

Displays a customizable callout/alert block with an optional title and color.

The Callout component is a flexible admonition block that allows you to specify a custom title and a custom color for the block’s styling.

Parameters:

  • text (str) – The markdown text content inside the callout.

  • title (Optional[str], optional) – The bold title string displayed at the top. Defaults to None.

  • color (Optional[str], optional) – Custom CSS color for the callout accent. Defaults to a random color from the predefined palette.

  • label (Optional[str], optional) – An optional label for the block. Defaults to None.

  • sublabel (Optional[str], optional) – An optional sublabel for the block. Defaults to None.

  • extra_css (Optional[str], optional) – Extra CSS styling. Defaults to None.

  • bordered (bool, optional) – Whether to draw a border. Defaults to False.

Example:

import report_creator as rc

rc.Callout("Custom configuration applied successfully.", title="Success", color="green", label="Config Status")
class report_creator.Code(code, language=None, *, scroll_long_content=False, label=None)[source]

Displays Code with syntax highlighting.

Note: There are language specific subclasses (e.g., Python, Java, Shell) that inherit from Language and automatically set the language parameter. The Code class can be used for any supported language by explicitly providing the language argument. There’s a difference between using rc.Yaml() and rc.Code(), the former takes a yaml data structure and the latter takes a string of code.

If you have a string that represents Yaml use rc.Code(), if you have a data structure that you’d like rendered as yaml use rc.Yaml().

If you have a string that represents Json use rc.Code(), if you have a data structure that you’d like rendered as json use rc.Json().

Another example would be markdown, if you want markdown rendered as markdown use rc.Markdown(), if you have a string of markdown that you’d like rendered as code use rc.Code() with language=”markdown”.

Parameters:

  • code (str) – The code string to be displayed. The content will be HTML-escaped by the parent Language class’s to_html method.

  • language (str) – The programming language identifier for syntax highlighting. This must be one of the supported languages (e.g., “python”, “java”, “shell”, etc.). The language name is case-insensitive and will be converted to lowercase. If None or empty string is provided, the label will be treated as a filename and the language will be inferred from the file extension. If inference fails, it will default to “plaintext”.

  • scroll_long_content (Optional[bool], optional) – If True, long code blocks may be made scrollable (behavior depends on CSS/JS in the template). Defaults to False.

  • label (Optional[str], optional) – An optional label for the code block, displayed above it. Defaults to None.

class report_creator.Collapse(*components, label=None)[source]

A container for creating collapsible sections in a report.

The Collapse component creates a collapsible section, often called an “accordion” or “details/summary” element in HTML. It groups a set of report components under a clickable header (defined by the label). When the header is clicked, the content within the Collapse section is shown or hidden.

The label is crucial as it forms the visible summary text. This label will be HTML-escaped before being rendered in the <summary> tag.

Parameters:

  • *components (Base) – A variable number of report components to be placed within the collapsible section.

  • label (Optional[str], optional) – The text displayed as the clickable header (summary) for the collapsible section. This text will be HTML-escaped. A label is typically required for Collapse to be meaningful. Inherits from Base. Defaults to None, in which case “Details” is used.

to_html()[source]

Renders the Collapse component to an HTML string.

It uses the HTML <details> and <summary> elements to create the collapsible behavior. The label (HTML-escaped) is used as the summary text. Child components are rendered within the <details> tag.

Return type:

str

Returns:

The HTML representation of the collapsible section.

Return type:

str

class report_creator.DataTable(data, *, label=None, wrap_text=True, index=False, max_rows=-1, float_precision=2)[source]

Displays a sortable and searchable table from a Pandas DataFrame or a list of dictionaries.

The DataTable component displays tabular data (from Pandas DataFrames or lists of dictionaries) as an interactive HTML table. This table includes features like client-side searching, sorting by columns, and pagination, powered by the DataTables JavaScript library.

The component uses Pandas’ Styler API to format the table structure and data before embedding it. Cell content is HTML-escaped by default.

Parameters:

  • data (Union[pd.DataFrame, list[dict]]) – The data for the table. Can be a Pandas DataFrame or a list of dictionaries (each dict is a row).

  • label (Optional[str], optional) – An optional caption for the table. If provided, it’s set as the table’s caption using Pandas Styler and will be HTML-escaped by the Styler. Inherits from Base. Defaults to None.

  • wrap_text (bool, optional) – If True (default), text within table cells can wrap. If False, a ‘nowrap’ class is added, which typically prevents wrapping (CSS dependent).

  • index (bool, optional) – If True, the DataFrame’s index is included as a column. If False (default), the index is hidden.

  • max_rows (int, optional) – Maximum number of rows from the DataFrame to display. If -1 (default), all rows are included. This affects the data passed to DataTables, not just initial display.

  • float_precision (int, optional) – Number of decimal places for float values. Defaults to 2.

Raises:

ValueError – If data is not a Pandas DataFrame or list of dictionaries.

to_html()[source]

Renders the DataTable to an HTML string.

The table HTML generated by Pandas Styler is wrapped in a div with class ‘dataTables-wrapper include_datatable’. The ‘include_datatable’ class signals the JavaScript in the main template to initialize DataTables on this table. A <br/> is added before the table for spacing.

Return type:

str

Returns:

The HTML representation of the interactive DataTable.

Return type:

str

class report_creator.Deck(*components, label=None)[source]

A container for presenting Block components as a slide deck.

The Deck component creates a presentation-style interface where each child Block component represents a single “slide” or “page”. The user can navigate between these slides using a floating toolbar or keyboard shortcuts (Left/Right arrows).

Parameters:

  • *components (Block | Slide) – A variable number of Block or Slide components to be displayed as individual slides.

  • label (Optional[str], optional) – An optional label for the deck. Inherits from Base. Defaults to None.

to_html()[source]

Renders the Deck component and its slides to an HTML string.

Each slide is wrapped in a div with class ‘deck-slide’. Only the first slide is initially visible. A toolbar with navigation controls is also rendered.

Return type:

str

Returns:

The HTML representation of the deck and its contents.

Return type:

str

class report_creator.Diagram(src, *, pan_and_zoom=True, extra_css=None, label=None)[source]

Renders a diagram using Mermaid.js syntax within the report.

The Diagram component allows you to create and embed diagrams directly within your report using the Mermaid.js library. Mermaid allows you to define diagrams using a simple text-based syntax, which is then rendered visually by the library.

This component enables embedding various diagrams (flowcharts, sequence diagrams, Gantt charts, etc.) using Mermaid.js syntax. The Mermaid source code is rendered by the Mermaid.js library in the browser.

Refer to the Mermaid.js documentation (https://mermaid.js.org/syntax/examples.html) for syntax examples. AI tools like ChatGPT can also help generate Mermaid syntax.

The src (Mermaid code) is not HTML-escaped by this component as it’s processed by JavaScript. Ensure the src is from a trusted source or properly sanitized if dynamically generated from user input outside of typical Mermaid syntax.

Parameters:

  • src (str) – The Mermaid.js source code string defining the diagram. This string is placed directly within <pre class=’mermaid’> tags.

  • pan_and_zoom (Optional[bool], optional) – If True (default), enables panning (mouse drag) and zooming (Shift + mouse wheel) for the rendered diagram, if supported by the ‘mermaid-pan-zoom’ class and associated JavaScript.

  • extra_css (Optional[str], optional) – Additional inline CSS styles to be applied to the <pre> element containing the Mermaid source. Be cautious with user-provided CSS. Defaults to an empty string.

  • label (Optional[str], optional) – An optional label or caption for the diagram, HTML-escaped and displayed above it within a <figcaption>. Inherits from Base. Defaults to None.

to_html()[source]

Renders the Diagram component to an HTML string.

The Mermaid source (src) is embedded in a <pre> tag with class ‘mermaid’. An optional, HTML-escaped label is rendered as a caption. Pan and zoom functionality is enabled by adding the ‘mermaid-pan-zoom’ class and associated UI elements if pan_and_zoom is True.

Return type:

str

Returns:

The HTML representation of the diagram placeholder.

Return type:

str

class report_creator.Error(text, *, label=None, sublabel=None, extra_css=None, bordered=False)[source]

Displays an error callout/alert block to highlight critical problems or failures.

The Error component renders a prominent “error” styled block, indicating a failure, exception, or a critical condition that requires immediate attention.

Example:

import report_creator as rc

rc.Error("Failed to connect to the database. Check your credentials.", label="Connection Error")
Parameters:

  • text (str)

  • label (str | None)

  • sublabel (str | None)

  • extra_css (str | None)

  • bordered (bool | None)

class report_creator.EventMetric(df, condition, date='date', frequency='D', color='red', heading=None, *, label=None)[source]

A specialized metric component for time series tracking event frequencies.

The EventMetric component is designed for visualizing the occurrence of events that satisfy a given condition within a time series. It’s useful for telemetry, event tracking, or monitoring specific occurrences.

It analyzes a Pandas DataFrame, applies a boolean condition to each row, and aggregates results over a specified time frequency (e.g., daily, weekly). The output includes a compact line chart (event frequency over time) and the total event count.

Parameters:

  • df (pd.DataFrame) – DataFrame with event data. Must include a date-like column and columns for evaluating the condition.

  • condition (str) – A boolean expression string (e.g., “status == 200”, “error_code != 0”) evaluated for each row. Rows where the condition is True are counted as events.

  • date (str) – Name of the date-like column in df. This column is used for time-based grouping and will be parsed into datetime objects.

  • frequency (str, optional) – Time frequency for grouping (Pandas offset alias, e.g., “D” for daily, “W” for weekly). Defaults to “D”.

  • color (str, optional) – Color for the line chart fill and line (CSS color string). Defaults to the report’s accent_color.

  • heading (Optional[str], optional) – Heading for the metric. If None, the condition string is used. Defaults to red.

  • label (Optional[str], optional) – Description for the metric, displayed below the event count. Inherits from Base. Defaults to None.

Raises:

ValueError – If date column is not in df, or if its values cannot be parsed as dates.

to_html()[source]

Generates the HTML representation of the EventMetric.

Return type:

str

Returns:

The HTML string for the EventMetric component.

Return type:

str

class report_creator.Gallery(images, *, labels=None, label=None, convert_to_base64=False)[source]

Displays an image gallery as a grid of thumbnails that expand into a Lightbox/fullscreen view.

The Gallery component takes a list of image paths or URLs and renders them as a responsive grid. Clicking an image opens it in a full-screen Lightbox overlay.

Parameters:

  • images (list[str]) – A list of image paths (local files, data URIs, or URLs).

  • labels (Optional[list[str]], optional) – An optional list of captions for each image. If provided, it must be the same length as images.

  • label (Optional[str], optional) – An optional label for the entire gallery group. Inherits from Base. Defaults to None.

  • convert_to_base64 (bool, optional) – If True and an image is a URL, it is fetched, converted to base64, and embedded. Defaults to False.

to_html()[source]

Renders the Gallery component to an HTML string.

Return type:

str

class report_creator.Gauge(value, min_value=0, max_value=100, title=None, unit=None, color=None)[source]

Displays a radial gauge chart for visualizing a single value within a range.

The Gauge component is ideal for tracking progress towards a goal or representing a metric that sits on a scale (e.g., speed, temperature, completion percentage).

Parameters:

  • value (float) – The current value to be displayed on the gauge.

  • min_value (float, optional) – The minimum value of the gauge scale. Defaults to 0.

  • max_value (float, optional) – The maximum value of the gauge scale. Defaults to 100.

  • title (Optional[str], optional) – A label for the gauge. Defaults to None.

  • unit (Optional[str], optional) – A unit of measurement for the value. Defaults to None.

  • color (Optional[str], optional) – The color of the gauge bar. If None, the library’s default color palette is used.

Example:

import report_creator as rc

rc.Gauge(value=75.5, title="CPU Usage", unit="%")
to_html()[source]

Generates the HTML representation of the gauge chart.

Return type:

str

class report_creator.Group(*components, label=None)[source]

A container for horizontally arranging report components.

The Group component arranges multiple report components horizontally, side-by-side, effectively creating columns or rows of elements. Each child component is wrapped in a div with class ‘group-content’, and the entire set of components is wrapped in a div with class ‘group’.

If a label is provided, it’s displayed as a caption above the group, HTML-escaped, and linked with an anchor ID generated from the label text.

Parameters:

  • *components (Base) – A variable number of report components (instances of classes derived from Base) to be arranged horizontally.

  • label (Optional[str], optional) – An optional label for the group. If provided, it is displayed above the components as a caption. The label text will be HTML-escaped. Inherits from Base. Defaults to None.

to_html()[source]

Renders the Group component and its child components to an HTML string.

Child components are placed within div elements with class ‘group-content’, and these are contained within a main div with class ‘group’. An optional, HTML-escaped label is rendered as a caption above the group.

Return type:

str

Returns:

The HTML representation of the group and its contents.

Return type:

str

class report_creator.Heading(label, *, level=1)[source]

Displays a large heading within the report.

The Heading component is used to create visually distinct section titles within a report, using HTML heading tags (h1-h5).

Parameters:

  • label (str) – The text content of the heading. This text will be HTML-escaped before being rendered within the heading tag (e.g., <h1>). This argument also serves as the label for the Base class.

  • level (int, optional) – The HTML heading level to use (1 through 5). For example, level=1 creates an <h1> tag, level=2 creates <h2>, etc. Defaults to 1.

Raises:

ValueError – If the specified level is not between 1 and 5 (inclusive), or if label (the heading text) is empty or not provided.

to_html()[source]

Converts the Heading component to its HTML representation (e.g., <h1>…</h1>). The heading text (label) is HTML-escaped. Includes <br /> tags before and after the heading for spacing.

Return type:

str

Returns:

The HTML string for the heading.

Return type:

str

class report_creator.Histogram(df, x, dimension=None, *, label=None, **kwargs)[source]

Displays a histogram using Plotly Express.

Visualizes the distribution of a single numerical variable (x). An optional dimension can color-code bars.

Parameters:

  • df (pd.DataFrame) – DataFrame for the chart.

  • x (str) – Column name for the x-axis (numerical variable for distribution).

  • dimension (Optional[str], optional) – Column name for color-coding bars. Defaults to None.

  • label (Optional[str], optional) – Chart label, used for title generation. Defaults to None.

  • **kwargs (Any) – Additional arguments for plotly.express.histogram().

Raises:

ValueError – If specified x or dimension columns are not in df.

to_html()[source]

Generates the HTML representation of the histogram.

Return type:

str

class report_creator.Html(html, *, css=None, label=None, bordered=False, validate_html=True)[source]

Embeds raw HTML content, optionally with inline CSS styling, into the report.

The Html component provides a way to include arbitrary HTML markup directly within a report. This is useful for embedding custom web elements, adding specialized formatting, or integrating content from external sources that provide HTML snippets.

Parameters:

  • html (str) – The raw HTML content to be embedded. This can include any valid HTML tags and content. Important: The provided HTML is validated to ensure all tags are properly closed using an internal utility (_check_html_tags_are_closed). If unclosed tags are detected, a ValueError will be raised to prevent malformed report layouts. Content should be properly escaped if generated from untrusted sources to prevent XSS vulnerabilities, as it is rendered directly.

  • css (Optional[str], optional) – Optional inline CSS styles to be applied specifically to this HTML content. These styles will be wrapped in <style> tags if provided. Defaults to None.

  • label (Optional[str], optional) – An optional label for the HTML component, displayed above the content if provided. Inherits from Base. If a label is provided, it will be HTML-escaped before rendering. Defaults to None.

  • bordered (Optional[bool], optional) – If True, the HTML content will be rendered within a container styled with a border. Defaults to False.

  • validate_html (bool, optional) – If True (default), the provided html string is validated to ensure all tags are properly closed. This can be disabled for performance with trusted content. Defaults to True.

Raises:

ValueError – If validate_html is True and the provided html string contains unclosed HTML tags.

to_html()[source]

Renders the Html component to an HTML string. Includes the raw HTML, optional CSS, and an optional HTML-escaped label. A border class is applied if bordered is True.

Return type:

str

Returns:

The HTML string for the component.

Return type:

str

class report_creator.Image(src, *, link_to=None, label=None, extra_css=None, rounded=True, convert_to_base64=False)[source]

Embeds an image within the report, optionally linking it to an external URL.

The Image component allows you to include images in your report, either by referencing an external URL or by embedding a base64-encoded image directly within the HTML. You can also make the image clickable, linking it to another webpage.

Parameters:

  • src (str) – The source of the image. The component handles src as follows: - Base64 Data URI: If src starts with “data:image”, it’s used directly. - Local File Path: If src is a valid local file path (checked using os.path.exists), the image is read, converted to a base64 data URI, and embedded. - URL (Remote Image): If src is a URL (e.g., “http://”, “https://”): if convert_to_base64 is True, the image is downloaded, converted to base64, and embedded. if convert_to_base64 is False (default), the src URL is used directly. The alt attribute for the image is generated from the label if provided, otherwise from the src (first 50 chars if long).

  • link_to (Optional[str], optional) – An optional URL. If provided, the image will be wrapped in an anchor (<a>) tag, making it a clickable link that opens the URL in a new tab (target=”_blank”). Defaults to None.

  • label (Optional[str], optional) – An optional label or caption for the image, displayed below it within a <figcaption>. If provided, it will be HTML-escaped. This label is also used as the alt text for the image. Inherits from Base. Defaults to None.

  • extra_css (Optional[str], optional) – Additional inline CSS styles to be applied directly to the <img> element (e.g., “width: 100px; height: auto;”). Defaults to an empty string.

  • rounded (bool, optional) – If True (default), applies CSS for rounded corners.

  • convert_to_base64 (bool, optional) – If True and src is a URL, the image is fetched, converted to base64, and embedded. Defaults to False. Has no effect if src is already a data URI or a local file path.

Raises:

  • ValueError – If the src is not a valid image source or if conversion fails.

  • The component logs errors and falls back to using the original src if conversion fails. –

  • This allows the browser to attempt rendering the image if it's a valid URL. –

to_html()[source]

Renders the Image component to an HTML string. Includes the image (either linked or embedded), an optional link, and an optional HTML-escaped caption.

Return type:

str

Returns:

The HTML representation of the image component.

Return type:

str

class report_creator.Info(text, *, label=None, sublabel=None, extra_css=None, bordered=False)[source]

Displays an info callout/alert block to highlight notes or general information.

The Info component renders a distinct “note” styled block, useful for providing context or secondary information that stands out from the main text flow.

Example:

import report_creator as rc

rc.Info("Please note that this process may take a few minutes to complete.", label="Process Information")
Parameters:

  • text (str)

  • label (str | None)

  • sublabel (str | None)

  • extra_css (str | None)

  • bordered (bool | None)

class report_creator.Java(code, *, scroll_long_content=False, label=None)[source]

Displays Java code with syntax highlighting.

Inherits from Language for common code block functionality.

Parameters:

  • code (str) – The Java code string to be displayed. The content will be HTML-escaped by the parent Language class’s to_html method.

  • scroll_long_content (Optional[bool], optional) – If True, long code blocks may be made scrollable (behavior depends on CSS/JS in the template). Defaults to False.

  • label (Optional[str], optional) – An optional label for the code block, displayed above it. Defaults to None.

class report_creator.Json(data, *, scroll_long_content=False, label=None)[source]

Displays formatted JSON content within the report.

The Json component serializes Python dictionaries/lists or parses JSON strings, then formats the result as an indented JSON string. String values within the JSON structure are HTML-escaped during serialization by a custom encoder (_RecursiveHtmlEscapingEncoder) to prevent XSS vulnerabilities.

The final JSON string (with internal strings escaped) is then passed to the Language base class, where the entire block is HTML-escaped again. This ensures the JSON structure is preserved for display and safe for embedding.

Parameters:

  • data (Union[dict, list, str]) – The JSON data. Can be a Python dict/list or a JSON-formatted string.

  • scroll_long_content (Optional[bool], optional) – If True, long code blocks may be made scrollable (behavior depends on CSS/JS in the template). Defaults to False.

  • label (Optional[str], optional) – An optional label for the code block, displayed above it. Defaults to None.

Raises:

ValueError – If data is not a dict, list, or valid JSON string, or if any other error occurs during JSON processing.

class report_creator.Line(df, x, y, *, dimension=None, label=None, **kwargs)[source]

Displays a line chart using Plotly Express.

Plots one or more y-axis variables against an x-axis variable from a DataFrame. An optional dimension column can color-code and differentiate symbols for lines. Defaults to spline lines with markers.

Parameters:

  • df (pd.DataFrame) – DataFrame for the chart.

  • x (str) – Column name for the x-axis.

  • y (Union[str, list[str]]) – Column name or list of column names for the y-axis.

  • dimension (Optional[str], optional) – Column name for color-coding and symbol differentiation. Defaults to None.

  • label (Optional[str], optional) – Chart label, used for title generation. Defaults to None.

  • **kwargs (Any) – Additional arguments for plotly.express.line().

Raises:

ValueError – If specified x, y, or dimension columns are not in df, or if y is not a string or list of strings.

to_html()[source]

Generates the HTML representation of the line chart.

Return type:

str

class report_creator.Markdown(text, *, label=None, sublabel=None, extra_css=None, bordered=False)[source]

Embeds Markdown-formatted text within the report, with optional styling and borders.

The Markdown component allows you to include rich text content in your report using Markdown syntax. It supports Github Falvored Markdown formatting and provides options for adding custom CSS styles and borders.

Parameters:

  • text (str) – The GitHub Flavored Markdown formatted text to be rendered. Supports standard Markdown features like headings, lists, links, images, etc, also emoji’s for example “:red_heart:”

  • label (Optional[str], optional) – An optional label or heading for the Markdown section. If provided, it’s HTML-escaped and displayed above the content, linked with an anchor ID. Defaults to None.

  • sublabel (Optional[str], optional) – An optional sublabel for the component section. If provided, it’s HTML-escaped and displayed below the content. Defaults to None.

  • extra_css (Optional[str], optional) – Additional inline CSS styles to be applied to the inner div that wraps the Markdown content. Be cautious with user-provided CSS. Defaults to an empty string.

  • bordered (bool, optional) – If True, the Markdown content will be rendered within a container that has a ‘round-bordered’ class, typically applying a border and rounded corners via CSS. Defaults to False.

to_html()[source]

Renders the Markdown component to an HTML string.

The Markdown text is converted to HTML. An optional, HTML-escaped label is rendered as a caption. The content is wrapped in div elements with appropriate classes for styling and JavaScript hooks (e.g., include_hljs).

Return type:

str

Returns:

The HTML representation of the rendered Markdown content.

Return type:

str

class report_creator.Metric(heading, value, *, unit=None, float_precision=3, label=None, color=False, gauge=None, bullet=None)[source]

Displays a single, key metric with a heading, value, and optional supporting information.

The Metric component is designed to highlight important quantitative or qualitative data points within a report. It allows for a concise presentation of key performance indicators (KPIs), summary statistics, or any other crucial piece of information.

Parameters:

  • heading (str) – The primary label or title for the metric. This concisely describes what the metric represents (e.g., “Total Revenue”, “Conversion Rate”). The heading is also used as a seed for the random background color if color is set to True.

  • value (Union[str, int, float, datetime]) – The actual value of the metric. - int values may be humanized (e.g., 1,000,000 becomes “1.0 Million”). - datetime objects are formatted as “YYYY-MM-DD”. - str values are displayed as is (after stripping whitespace).

  • unit (Optional[str], optional) – An optional unit of measurement for the metric, displayed directly after the value (e.g., “%”, “USD”, “ms”). Defaults to an empty string.

  • float_precision (Optional[int], optional) – The number of decimal places to display for float values when humanization is not applied or does not significantly alter the number. Defaults to 3.

  • label (Optional[str], optional) – An optional description or additional context for the metric, displayed below the value. Supports GitHub Flavored Markdown. Inherits from Base. Defaults to None.

  • color (Optional[bool], optional) – If True, the metric will be rendered with a subtly colored background. The background color is deterministically generated based on the heading string, ensuring that the same heading will consistently produce the same background color. This helps in visually distinguishing metrics. Defaults to False, resulting in a standard background.

  • gauge (Optional[dict], optional) – A dictionary of arguments for an rc.Gauge component to be displayed alongside the metric. Expected keys: min_value, max_value, color, unit.

  • bullet (Optional[dict], optional) – A dictionary of arguments for an rc.Bullet component to be displayed alongside the metric. Expected keys: target, min_value, max_value, color, unit.

to_html()[source]

Renders the Metric component to an HTML string. Formats the value based on its type (int, float, datetime, str) and applies humanization or precision formatting. An optional label is rendered as Markdown. If color is True, a deterministic background color based on the heading is applied. Also renders a gauge or bullet chart if provided.

Return type:

str

Returns:

The HTML representation of the metric.

Return type:

str

class report_creator.MetricGroup(df, heading, value, *, label=None)[source]

A container for displaying multiple metrics in a structured group.

The MetricGroup component facilitates the display of multiple Metric instances derived from the rows of a Pandas DataFrame. It effectively creates a Metric for each row, using specified DataFrame columns for the metric’s heading and value. These Metric components are then arranged horizontally by an internally managed Group component.

This component is a convenient way to present a collection of related key performance indicators (KPIs) or summary statistics side-by-side.

Parameters:

  • df (pd.DataFrame) – The DataFrame containing the data for the metrics. Each row will typically result in one Metric component.

  • heading (str) – The name of the column in df whose values will be used as the heading for each generated Metric component.

  • value (str) – The name of the column in df whose values will be used as the value for each generated Metric component.

  • label (Optional[str], optional) – An optional label for the entire metric group. This label is passed to the internal Group component, which will render it as an HTML-escaped caption above the group of metrics. Inherits from Base. Defaults to None.

Raises:

ValueError – If the specified heading or value columns are not found in the input df, or if df is not a Pandas DataFrame.

to_html()[source]

Renders the MetricGroup to HTML. Generates HTML directly for each metric for performance reasons, avoiding instantiation of individual Metric and Group objects.

Return type:

str

Returns:

The HTML representation of the grouped metrics.

Return type:

str

class report_creator.Pie(df, values, names, *, label=None, **kwargs)[source]

Displays a pie chart (or donut chart if hole is specified) using Plotly Express.

Visualizes parts of a whole, where values determine slice sizes and names provide slice labels. Defaults to a donut chart appearance (hole=0.4).

Parameters:

  • df (pd.DataFrame) – DataFrame for the chart.

  • values (str) – Column name for slice values.

  • names (str) – Column name for slice names/labels.

  • label (Optional[str], optional) – Chart label, used for title generation. Defaults to None.

  • **kwargs (Any) – Additional arguments for plotly.express.pie(). Example: hole=0 for a pie chart, color_discrete_sequence.

Raises:

ValueError – If specified values or names columns are not in df.

to_html()[source]

Generates the HTML representation of the pie chart.

Return type:

str

class report_creator.Plaintext(text, *, scroll_long_content=False, label=None)[source]

Displays text content with minimal formatting (within <pre><code> tags) and basic syntax highlighting for “plaintext” (which usually means no specific highlighting but respects whitespace).

Inherits from Language. The primary purpose is to render text verbatim, preserving whitespace and line breaks, without applying Markdown or other complex formatting. The Language base class’s to_html method will HTML-escape the input text.

Parameters:

  • text (str) – The text content to be displayed. It will be HTML-escaped by the Language base class’s to_html method.

  • scroll_long_content (Optional[bool], optional) – If True, long code blocks may be made scrollable (behavior depends on CSS/JS in the template). Defaults to False.

  • label (Optional[str], optional) – An optional label for the code block, displayed above it. Defaults to None.

class report_creator.Prolog(code, *, scroll_long_content=False, label=None)[source]

Displays Prolog code with syntax highlighting.

Inherits from Language for common code block functionality.

Parameters:

  • code (str) – The Prolog code string to be displayed. The content will be HTML-escaped by the parent Language class’s to_html method.

  • scroll_long_content (Optional[bool], optional) – If True, long code blocks may be made scrollable (behavior depends on CSS/JS in the template). Defaults to False.

  • label (Optional[str], optional) – An optional label for the code block, displayed above it. Defaults to None.

class report_creator.Python(code, *, scroll_long_content=False, label=None)[source]

Displays Python code with syntax highlighting.

Inherits from Language for common code block functionality. The input code string is automatically unindented using textwrap.dedent before being passed to the parent constructor. This is useful for cleaning up Python code defined in triple-quoted strings.

Parameters:

  • code (str) – The Python code string to be displayed. It will be dedented before being passed to the Language base class. The Language base class’s to_html method handles HTML escaping.

  • scroll_long_content (Optional[bool], optional) – If True, long code blocks may be made scrollable (behavior depends on CSS/JS in the template). Defaults to False.

  • label (Optional[str], optional) – An optional label for the code block, displayed above it. Defaults to None.

class report_creator.Radar(df, *, label=None, lock_minimum_to_zero=False, filled=False, **kwargs)[source]

Displays a radar chart (spider/star chart) using Plotly’s graph objects.

Each row in the input DataFrame represents a trace (entity), and each column an angular axis (category). The DataFrame index names the traces.

Parameters:

  • df (pd.DataFrame) – DataFrame for the chart. - Index: Names for radar traces (must be unique, non-null). - Columns: Angular axes/categories. - Values: Magnitudes for each category per trace.

  • label (Optional[str], optional) – Chart label, used for title generation. Defaults to None.

  • lock_minimum_to_zero (Optional[bool], optional) – If True, radial axis starts at zero. Default False (axis minimum based on data).

  • filled (Optional[bool], optional) – If True, areas enclosed by traces are filled. Defaults to False.

  • **kwargs (Any) – Additional arguments. - trace_kwargs (dict): Passed to go.Scatterpolar traces. - Others used by PxBase.apply_common_kwargs (e.g., title, height).

Raises:

ValueError – If df is not a Pandas DataFrame, or if its index is invalid (empty, not unique, or contains NaNs).

to_html()[source]

Generates the HTML representation of the radar chart.

Return type:

str

class report_creator.ReportCreator(title, *, description=None, author=None, logo=None, theme='rc', code_theme='ir-black', diagram_theme='default', accent_color='black', footer=None, flat_look=False)[source]

Generates interactive HTML reports from Python objects and components.

The ReportCreator class is the main entry point for assembling and saving an HTML report. It manages overall report properties like title, author, description, and theming options for various embedded elements such as Plotly charts, code blocks (Highlight.js), and diagrams (Mermaid.js).

Parameters:

  • title (str) – The title for the report. This will be HTML-escaped. If None is specified the header section is suppressed - useful for Slide Decks where the title is on the first slide.

  • description (Optional[str], optional) – A short description of the report. Supports GitHub Flavored Markdown. Rendered below the title. Defaults to None.

  • author (Optional[str], optional) – The name of the report’s author. HTML-escaped. Defaults to None.

  • logo (Optional[str | Path], optional) – Specifies the logo in the report header. - URL (http, https, data:image): Used directly. - Local file path: Embedded as base64 data URI. - String (not file/URL): Assumed GitHub username for avatar. - None (default): Auto-generates SVG icon from title and accent_color.

  • theme (str, optional) – Plotly template for charts. “rc” is a custom theme. Defaults to “rc”.

  • code_theme (str, optional) – Highlight.js theme for code blocks. Defaults to “github-dark-min”. See https://highlightjs.org/demo/ for options.

  • diagram_theme (str, optional) – Mermaid.js theme for diagrams. Defaults to “default”.

  • accent_color (str, optional) – Accent color for auto-generated logo. Defaults to “black”.

  • footer (Optional[str], optional) – Text for the report’s footer (Markdown supported). Defaults to None.

  • flat_look (bool, optional) – If True, uses a flat design for the report. If False (default), uses a 3D look with shadows and gradients.

Raises:

ValueError – If an invalid theme (Plotly template) is specified.

save(view, path, prettify_html=False)[source]

Renders the report content and saves it to an HTML file.

This method takes the main view component, renders it to HTML, and then embeds this HTML body into a Jinja2 template that includes necessary headers, styles, and scripts. All textual metadata (title, author, description, footer) is HTML-escaped before being passed to the template.

Return type:

None

Parameters:

  • view (Base) – The root Base component representing the report’s content.

  • path (str | Path) – File path to save the HTML report.

  • prettify_html (bool, optional) – If True, uses BeautifulSoup to prettify the HTML output. Requires beautifulsoup4. Defaults to False.

Raises:

  • ValueError – If view is not an instance of Base.

  • FileNotFoundError – If the Jinja2 template file cannot be found.

  • RuntimeError – If template rendering or component HTML generation fails.

  • IOError – If the HTML file cannot be written.

class report_creator.Scatter(df, x, y, dimension=None, *, label=None, marginal=None, **kwargs)[source]

Displays a scatter plot using Plotly Express.

Shows the relationship between two numerical variables (x and y). An optional dimension can color-code and differentiate symbols. Marginal plots (histogram, box, etc.) can be added.

Parameters:

  • df (pd.DataFrame) – DataFrame for the chart.

  • x (str) – Column name for the x-axis.

  • y (str) – Column name for the y-axis.

  • dimension (Optional[str], optional) – Column name for color-coding and symbol differentiation. Defaults to None.

  • label (Optional[str], optional) – Chart label, used for title generation. Defaults to None.

  • marginal (Optional[str], optional) – Adds marginal plots. Valid options: “histogram”, “violin”, “box”, “rug”. Defaults to None.

  • **kwargs (Any) – Additional arguments for plotly.express.scatter().

Raises:

ValueError – If specified x, y, or dimension columns are not in df, or if marginal type is invalid.

to_html()[source]

Generates the HTML representation of the scatter plot.

Return type:

str

class report_creator.Select(blocks, *, label=None)[source]

Creates a dropdown select element for user interaction within the report.

The Select component creates a tabbed interface where each tab displays the content of a corresponding Base component from the blocks list. The label of each Base component in blocks is used as the title for its tab. Clicking a tab reveals its associated content.

A unique group_id is generated for each Select instance to ensure that JavaScript functions for tab switching work correctly when multiple Select components are on the same page. Labels used for tab titles and overall caption are HTML-escaped.

Parameters:

  • blocks (list[Base]) – A list of Base-derived components. Each component’s label attribute (which must be present and non-empty) is used as the title for a tab. The component’s to_html() output is the tab’s content.

  • label (Optional[str], optional) – An optional overall label for the tab group, HTML-escaped and displayed above the tabs as a caption with an anchor. Inherits from Base. Defaults to None.

Raises:

ValueError – If any component in blocks does not have a label attribute, or if a label is empty or consists only of whitespace.

to_html()[source]

Renders the Select (tabbed) component to an HTML string.

Includes an optional HTML-escaped caption, tab buttons, and tab content panels. A unique group ID is used to ensure correct behavior with multiple Select instances.

Return type:

str

Returns:

The HTML representation of the tabbed component.

Return type:

str

class report_creator.Separator(label=None)[source]

Inserts a visual separator (horizontal rule) into the report.

The Separator component provides a way to create clear visual breaks between sections of a report. It renders as a horizontal line, making it easy to distinguish different parts of the content.

Parameters:

label (Optional[str], optional) – An optional label for the separator. If provided, it is HTML-escaped and rendered as a caption (using <report-caption>) below the horizontal rule (<hr>). The caption includes a linkable anchor generated from the label text. This can be useful for navigation or providing context for the break. Defaults to None, in which case only the <hr> (with surrounding <br>) is rendered.

to_html()[source]

Converts the Separator component to its HTML representation.

Renders as a horizontal rule (<hr>). If a label is provided, it’s displayed as an HTML-escaped caption below the rule. Includes <br> tags for spacing.

Return type:

str

Returns:

The HTML string for the separator.

Return type:

str

class report_creator.Sh(code, *, scroll_long_content=False, label=None)[source]

Alias for Shell. Displays shell script code with syntax highlighting.

Example:

import report_creator as rc

rc.Sh("echo 'Hello World'", label="Hello Script")
Parameters:

  • code (str)

  • scroll_long_content (bool | None)

  • label (str | None)

class report_creator.Shell(code, *, scroll_long_content=False, label=None)[source]

Displays Shell (bash/sh) script code with syntax highlighting.

Inherits from Language for common code block functionality.

Parameters:

  • code (str) – The Shell script code string to be displayed. The content will be HTML-escaped by the parent Language class’s to_html method.

  • scroll_long_content (Optional[bool], optional) – If True, long code blocks may be made scrollable (behavior depends on CSS/JS in the template). Defaults to False.

  • label (Optional[str], optional) – An optional label for the code block, displayed above it. Defaults to None.

class report_creator.Slide(component, theme, border=True)[source]

A presentation slide component that splits its area into a themed left section and a content right section.

Parameters:

  • component (Base) – The report component to be displayed on the right.

  • theme (str) – The theme name or color name (e.g.”red”) for the left section. Can be a solid color (e.g., “#ff0000”, “blue”)or a pattern with a color (e.g., “pattern:color”). Supported patterns are: “circles”, “blocks”, “dots”, “stripes”, “mondrian”, “retro”, “modern”.

  • border (bool | str, optional) – Whether the slide has a border. Defaults to True. If True, a border is applied using the report’s accent-color`. If a string is provided, it is used as the border color directly (e.g., border=”#ff0000”).

to_html()[source]

Renders the Slide component to an HTML string.

The slide is divided into a 1/3 left section with a background based on the theme, and a 2/3 right section containing the provided component.

Return type:

str

class report_creator.Sql(code, *, scroll_long_content=False, prettify=False, label=None)[source]

Displays SQL code with syntax highlighting and optional auto-formatting.

Inherits from Language for common code block functionality. If prettify is enabled, the SQL code is formatted using a basic heuristic formatter (Sql.format_sql) before being passed to the parent constructor.

Parameters:

  • code (str) – The SQL query string to be displayed. If prettify is True, this code will be formatted. The resulting code (formatted or original) will then be HTML-escaped by the Language base class’s to_html method.

  • scroll_long_content (Optional[bool], optional) – If True, long code blocks may be made scrollable (behavior depends on CSS/JS in the template). Defaults to False.

  • prettify (Optional[bool], optional) – If True, the SQL query string will be auto-formatted. This includes uppercasing keywords (e.g., SELECT, FROM), standardizing newlines after commas, and indenting clauses. The formatting is heuristic and works best on common SQL structures; complex or already heavily formatted queries might not be improved. Defaults to False.

  • label (Optional[str], optional) – An optional label for the code block, displayed above it. Defaults to None.

BLOCK_STATEMENTS = ['create.*?table', 'create.*?view', 'select distinct', 'select', 'from', 'left join', 'inner join', 'outer join', 'right join', 'union', 'on', 'where', 'group by', 'order by', 'asc', 'desc', 'limit', 'offset', 'insert.*?into', 'update', 'set', 'delete', 'drop', 'alter', 'add', 'modify', 'rename', 'truncate', 'begin', 'commit', 'rollback', 'grant', 'revoke']
RESERVED_WORDS = ['as']
static format_sql(sql)[source]

Heuristically formats an SQL query string for better readability.

The formatting includes: - Placing commas on new lines followed by a tab (if not inside quotes). - Uppercasing reserved words (currently only ‘AS’). - Uppercasing block statements (e.g., SELECT, FROM, WHERE) and placing them on new lines, followed by a tab.

Note: This is a basic formatter and may not correctly format all complex SQL queries, especially those with comments or already intricate formatting.

Return type:

str

Parameters:

sql (str)

class report_creator.Table(data, *, label=None, index=False, float_precision=2)[source]

Displays a Pandas DataFrame or a list of dictionaries as a formatted HTML table.

The Table component displays a Pandas DataFrame or a list of dictionaries as a static HTML table. It leverages Pandas’ Styler API for formatting. This component is a subclass of Widget, using the Styler object as its widget.

Content within the table cells is HTML-escaped by default by the Pandas Styler’s to_html() method (which is invoked via format(escape=”html”)).

Parameters:

  • data (Union[pd.DataFrame, list[dict]]) – The data for the table. Can be a Pandas DataFrame or a list of dictionaries (where each dictionary represents a row and keys are column names).

  • label (Optional[str], optional) – An optional label or caption for the table, HTML-escaped and displayed above it by the parent Widget’s rendering logic. Inherits from Widget and Base. Defaults to None.

  • index (bool, optional) – If True, the DataFrame’s index will be displayed in the table. If False (default), the index is hidden.

  • float_precision (int, optional) – The number of decimal places for floating-point numbers in the table. Defaults to 2.

Raises:

ValueError – If data is not a Pandas DataFrame or a list of dictionaries.

class report_creator.Text(text, *, label=None, sublabel=None, extra_css=None, bordered=False)[source]

An alias for the Markdown component, for displaying rich text.

Displays Markdown-formatted text. It is a direct alias of the Markdown component, inheriting all its functionality and parameters.

This component is useful for embedding rich text content formatted using GitHub Flavored Markdown. Refer to the Markdown class for detailed documentation on arguments and behavior (e.g., text, label, extra_css, bordered).

Parameters:

  • text (str)

  • label (str | None)

  • sublabel (str | None)

  • extra_css (str | None)

  • bordered (bool | None)

class report_creator.Timeline(df, task, start, finish, *, dimension=None, label=None, **kwargs)[source]

Displays a Gantt/timeline chart.

Renders tasks as horizontal bars on a date axis. Tasks appear in top-to-bottom order matching the DataFrame row order. Each data point is represented as a horizontal bar with a start and end point specified as dates.

Parameters:

  • df (pd.DataFrame) – DataFrame containing the task data.

  • task (str) – Column name for task labels (y-axis).

  • start (str) – Column name for task start datetimes. Must be datetime dtype; use pd.to_datetime() to convert string columns.

  • finish (str) – Column name for task finish datetimes. Must be datetime dtype.

  • dimension (Optional[str]) – Column name for color-coding tasks (e.g. team or phase). Defaults to None.

  • label (Optional[str]) – Chart title. Defaults to None.

  • **kwargs – Additional keyword arguments passed to plotly.express.timeline().

Raises:

  • ValueError – If any required column is missing from df.

  • ValueError – If start or finish columns are not datetime dtype.

  • ValueError – If dimension column is specified but not found in df.

Example:

df = pd.DataFrame({
    "task":   ["Design", "Development", "Testing", "Deploy"],
    "start":  pd.to_datetime(["2024-01-01", "2024-01-15", "2024-02-01", "2024-02-15"]),
    "finish": pd.to_datetime(["2024-01-14", "2024-01-31", "2024-02-14", "2024-02-28"]),
    "team":   ["Engineering", "Engineering", "QA", "DevOps"],
})
rc.Timeline(df, task="task", start="start", finish="finish",
            dimension="team", label="Q1 Project Plan")
to_html()[source]

Generates the HTML representation of the timeline (Gantt) chart.

Return type:

str

class report_creator.Unformatted(text, *, label=None)[source]

Displays data as text without any specific formatting or structure.

The Unformatted component displays raw text content, preserving whitespace and line breaks by wrapping the text in <pre><code> HTML tags. This is suitable for showing data dumps, simple log outputs, or any text that should not be processed as Markdown or another rich format.

The input text is HTML-escaped before being placed inside the <code> tag to prevent XSS vulnerabilities and ensure correct rendering of special characters. An optional label (also HTML-escaped) can be displayed as a caption.

Parameters:

  • text (str) – The raw text content to be displayed. This text will be HTML-escaped.

  • label (Optional[str], optional) – An optional label for the unformatted text block. If provided, it’s HTML-escaped and displayed above the text as a caption with an anchor. Inherits from Base. Defaults to None.

to_html()[source]

Renders the Unformatted text component to an HTML string.

The text is HTML-escaped and wrapped in <pre><code> tags. An optional HTML-escaped label is rendered as a caption.

Return type:

str

Returns:

The HTML representation of the unformatted text block.

Return type:

str

class report_creator.Warning(text, *, label=None, sublabel=None, extra_css=None, bordered=False)[source]

Displays a warning callout/alert block to highlight important considerations or potential issues.

The Warning component renders a distinct “warning” styled block, alerting the reader to potential pitfalls, deprecation notices, or important conditions.

Example:

import report_creator as rc

rc.Warning("This API endpoint will be deprecated in the next major version.", label="Deprecation Warning")
Parameters:

  • text (str)

  • label (str | None)

  • sublabel (str | None)

  • extra_css (str | None)

  • bordered (bool | None)

class report_creator.Widget(widget, *, label=None)[source]

A container for embedding and rendering external content or interactive widgets.

The Widget component serves as a versatile container for displaying various Python objects that can render themselves as HTML. This is particularly useful for embedding common data science outputs like Pandas DataFrames, Matplotlib figures, and Plotly figures directly into the report.

The component intelligently attempts to find the best HTML representation: - For Plotly go.Figure objects, common styling options are applied. - For objects with a get_figure() method (common in libraries like Seaborn), that method is called to retrieve the figure. - For Pandas DataFrames, style._repr_html_() is used. - For Matplotlib figures, they are saved as PNG images, base64-encoded, and embedded in an <img> tag with styling for responsiveness. - For other objects, it checks for a _repr_html_() method. - As a fallback, it uses the object’s standard __repr__ or __str__ representation wrapped in <pre> tags after HTML escaping.

An optional label (HTML-escaped) can be displayed as a caption above the widget.

Parameters:

  • widget (Any) – The Python object to be embedded. Supported types include: - Plotly go.Figure - Objects with a get_figure() method (e.g., some Seaborn plot objects) - Pandas DataFrame - Matplotlib figure.Figure - Any object with a _repr_html_() method - Any object with __repr__ or __str__ methods (as a fallback)

  • label (Optional[str], optional) – An optional label or caption for the widget. If provided, it will be HTML-escaped and displayed above the widget, linked with an anchor ID. Inherits from Base. Defaults to None.

to_html()[source]

Renders the Widget component to an HTML string.

It includes an optional HTML-escaped label (caption) and the HTML representation of the embedded widget.

Return type:

str

Returns:

The HTML representation of the widget.

Return type:

str

class report_creator.Yaml(data, *, scroll_long_content=False, label=None)[source]

Displays formatted YAML content within the report.

The Yaml component is designed to embed YAML-formatted data directly into the report, presenting it in a structured and human-readable way. It’s useful for displaying configuration files, data structures, or any other information that is naturally represented in YAML format.

Parameters:

  • data (Union[dict, list, str]) – The YAML data to be displayed. This can be a Python dictionary or list (which will be converted to a YAML string), or a string already formatted as YAML. The resulting YAML string will be HTML-escaped by the Language base class’s to_html method before rendering.

  • scroll_long_content (Optional[bool], optional) – If True, long code blocks may be made scrollable (behavior depends on CSS/JS in the template). Defaults to False.

  • label (Optional[str], optional) – An optional label for the code block, displayed above it. Defaults to None.

Raises:

  • ValueError – If the data argument’s type is not a dict, list, or str.

  • yaml.YAMLError – If data is a string that cannot be parsed as valid YAML, or if there’s an error during YAML serialization.