Source code for ax.utils.report.render

#!/usr/bin/env python3
# Copyright (c) Meta Platforms, Inc. and affiliates.
#
# This source code is licensed under the MIT license found in the
# LICENSE file in the root directory of this source tree.

# pyre-strict

import os
import pkgutil

from ax.plot.render import _js_requires, _load_css_resource as _load_plot_css_resource
from jinja2 import Environment, FunctionLoader

REPORT_MODULE_NAME = "ax.utils.report"


def _load_css_resource() -> str:
    resource = pkgutil.get_data(
        REPORT_MODULE_NAME, os.path.join("resources", "report.css")
    )
    assert resource is not None
    return resource.decode("utf8")


REPORT_ELEMENT_TEMPLATE = "simple_template.html"


[docs] def p_html(text: str) -> str: """Embed text in paragraph tag.""" return f"<p>{text}</p>"
[docs] def h2_html(text: str) -> str: """Embed text in subheading tag.""" return f"<h2>{text}</h2>"
[docs] def h3_html(text: str) -> str: """Embed text in subsubheading tag.""" return f"<h3>{text}</h3>"
[docs] def list_item_html(text: str) -> str: """Embed text in list element tag.""" return f"<li>{text}</li>"
[docs] def unordered_list_html(list_items: list[str]) -> str: """Embed list of html elements into an unordered list tag.""" return "<ul>{}</ul>".format("".join(list_items))
[docs] def table_cell_html(text: str, width: str | None = None) -> str: """Embed text or an HTML element into table cell tag.""" if width: return f"<td width={width}>{text}</td>" else: return f"<td>{text}</td>"
[docs] def table_heading_cell_html(text: str) -> str: """Embed text or an HTML element into table heading cell tag.""" return f"<th>{text}</th>"
[docs] def table_row_html(table_cells: list[str]) -> str: """Embed list of HTML elements into table row tag.""" return "<tr>{}</tr>".format("".join(table_cells))
[docs] def table_html(table_rows: list[str]) -> str: """Embed list of HTML elements into table tag.""" return "<table>{}</table>".format("".join(table_rows))
[docs] def render_report_elements( experiment_name: str, html_elements: list[str], header: bool = True, offline: bool = False, notebook_env: bool = False, ) -> str: """Generate Ax HTML report for a given experiment from HTML elements. Uses Jinja2 for template. Injects Plotly JS for graph rendering. Example: :: html_elements = [ h2_html("Subsection with plot"), p_html("This is an example paragraph."), plot_html(plot_fitted(gp_model, 'perf_metric')), h2_html("Subsection with table"), pandas_html(data.df), ] html = render_report_elements('My experiment', html_elements) Args: experiment_name: the name of the experiment to use for title. html_elements: list of HTML strings to render in report body. header: if True, render experiment title as a header. Meant to be used for standalone reports (e.g. via email), as opposed to served on the front-end. offline: if True, entire Plotly library is bundled with report. notebook_env: if True, caps the report width to 700px for viewing in a notebook environment. Returns: str: HTML string. """ # combine CSS for report and plots css = _load_css_resource() + _load_plot_css_resource() return ( _get_jinja_environment() .get_template(REPORT_ELEMENT_TEMPLATE) .render( experiment_name=experiment_name, css=css, js_requires=_js_requires(), html_elements=html_elements, headfoot=header, notebook_env=notebook_env, ) )
def _load_html_template(name: str) -> str: resource = pkgutil.get_data(REPORT_MODULE_NAME, os.path.join("resources", name)) assert resource is not None return resource.decode("utf8") def _get_jinja_environment() -> Environment: return Environment(loader=FunctionLoader(_load_html_template))