bencher.bench_report

Classes

`Publisher`	Generic publisher protocol for benchmark reports.
`GithubPagesCfg`
`BenchReport`	A server for display plots of benchmark results

Functions

_inline_rrd(→ None)

Rewrite .rrd viewer iframes in a saved HTML report for static hosting.

Module Contents

bencher.bench_report._inline_rrd(html_path: pathlib.Path, rrd_base: pathlib.Path | None = None, portable: bool = False) → None

Rewrite .rrd viewer iframes in a saved HTML report for static hosting.

By default copies .rrd files as sidecars (fast, works on any HTTP server). With portable=True, base64-encodes the data into the viewer HTML so the report works from file:// without a server.

class bencher.bench_report.Publisher

Bases: Protocol

Generic publisher protocol for benchmark reports.

Any object with a publish(report) method satisfies this protocol. Downstream projects implement their own publishers (GCS, S3, etc.) without modifying bencher.

publish(report: BenchReport) → str | None: Publish a report. Returns the published URL, or None.

class bencher.bench_report.GithubPagesCfg

github_user: str

repo_name: str

folder_name: str = 'report'

branch_name: str = 'gh-pages'

class bencher.bench_report.BenchReport(bench_name: str | None = None)

Bases: bencher.bench_plot_server.BenchPlotServer

A server for display plots of benchmark results

bench_name = None

pane

last_save_ms: float = 0.0

bench_results: list[bencher.results.bench_result.BenchResult] = []

clear() → None

Remove all tabs and results so the report can be reused between runs.

Not safe to call while the report is being served to a live Panel session.

append_title(title: str, new_tab: bool = True)

append_markdown(markdown: str, name: str | None = None, width: int = 800, **kwargs) → panel.pane.Markdown

append(pane: panel.panel, name: str | None = None) → None

append_col(pane: panel.panel, name: str | None = None) → None

static _time_event_label(bench_res: bencher.results.bench_result.BenchResult) → str | None: Extract a human-readable label for the latest time event from a result.

append_result(bench_res: bencher.results.bench_result.BenchResult, render_from: bencher.results.bench_result.BenchResult | None = None) → None

append_to_result(bench_res: bencher.results.bench_result.BenchResult, pane: panel.panel) → None: Append pane to the tab that belongs to bench_res.

prepend_to_result(bench_res: bencher.results.bench_result.BenchResult, pane: panel.panel) → None: Insert pane at the beginning of the tab that belongs to bench_res.

append_tab(pane: panel.panel, name: str | None = None) → None

save_index(directory: str = '', filename: str = 'index.html') → pathlib.Path

Saves the result to index.html in the root folder so that it can be displayed by github pages.

Returns:: save path
Return type:: Path

save(directory: str | pathlib.Path = 'cachedir', filename: str | None = None, in_html_folder: bool = True, portable: bool = False, **kwargs) → pathlib.Path

Save the result to a html file.

When the report contains multiple tabs, each tab is saved to its own embedded HTML file and the index page uses iframes to display them. This prevents HoloMap slider widgets from colliding across tabs.

Parameters:

directory (str | Path, optional) – base folder to save to. Defaults to “cachedir” which should be ignored by git.
filename (str, optional) – The name of the html file. Defaults to the name of the benchmark
in_html_folder (bool, optional) – Put the saved files in a html subfolder to help keep the results separate from source code. Defaults to True.
portable (bool, optional) – When True, base64-encode .rrd data directly into the viewer HTML so the report works from file:// without any server. When False (default), .rrd files are copied as sidecar files and loaded via relative URLs — the report must be served over HTTP.

Returns:

the save path

Return type:

Path

static _write_iframe_index(index_path: pathlib.Path, tab_files: list) → None: Write a lightweight HTML index with tab buttons and an iframe.

show(run_cfg: bencher.bench_cfg.BenchRunCfg | None = None) → threading.Thread

Launches a webserver with plots of the benchmark results, blocking

Parameters:: run_cfg (BenchRunCfg, optional) – Options for the webserve such as the port. Defaults to None.

publish_gh_pages(github_user: str, repo_name: str, folder_name: str = 'report', branch_name: str = 'gh-pages') → str

publish(remote_callback: Callable, branch_name: str | None = None, debug: bool = False) → str

Publish the results as an html file by committing it to the bench_results branch in the current repo. If you have set up your repo with github pages or equivalent then the html file will be served as a viewable webpage. This is an example of a callable to publish on github pages:

def publish_args(branch_name) -> tuple[str, str]:
    return (
        "https://github.com/blooop/bencher.git",
        f"https://github.com/blooop/bencher/blob/{branch_name}")

Parameters:: remote (Callable) – A function the returns a tuple of the publishing urls. It must follow the signature def publish_args(branch_name) -> tuple[str, str]. The first url is the git repo name, the second url needs to match the format for viewable html pages on your git provider. The second url can use the argument branch_name to point to the report on a specified branch.
Returns:: the url of the published report
Return type:: str