bencher.bench_report ==================== .. py:module:: bencher.bench_report Classes ------- .. autoapisummary:: bencher.bench_report.Publisher bencher.bench_report.GithubPagesCfg bencher.bench_report.BenchReport Functions --------- .. autoapisummary:: bencher.bench_report._inline_rrd Module Contents --------------- .. py:function:: _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. .. py:class:: Publisher Bases: :py:obj:`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. .. py:method:: publish(report: BenchReport) -> str | None Publish a report. Returns the published URL, or None. .. py:class:: GithubPagesCfg .. py:attribute:: github_user :type: str .. py:attribute:: repo_name :type: str .. py:attribute:: folder_name :type: str :value: 'report' .. py:attribute:: branch_name :type: str :value: 'gh-pages' .. py:class:: BenchReport(bench_name: str | None = None) Bases: :py:obj:`bencher.bench_plot_server.BenchPlotServer` A server for display plots of benchmark results .. py:attribute:: bench_name :value: None .. py:attribute:: pane .. py:attribute:: last_save_ms :type: float :value: 0.0 .. py:attribute:: bench_results :type: list[bencher.results.bench_result.BenchResult] :value: [] .. py:method:: 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. .. py:method:: append_title(title: str, new_tab: bool = True) .. py:method:: append_markdown(markdown: str, name: str | None = None, width: int = 800, **kwargs) -> panel.pane.Markdown .. py:method:: append(pane: panel.panel, name: str | None = None) -> None .. py:method:: append_col(pane: panel.panel, name: str | None = None) -> None .. py:method:: _time_event_label(bench_res: bencher.results.bench_result.BenchResult) -> str | None :staticmethod: Extract a human-readable label for the latest time event from a result. .. py:method:: append_result(bench_res: bencher.results.bench_result.BenchResult, render_from: bencher.results.bench_result.BenchResult | None = None) -> None .. py:method:: append_to_result(bench_res: bencher.results.bench_result.BenchResult, pane: panel.panel) -> None Append *pane* to the tab that belongs to *bench_res*. .. py:method:: 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*. .. py:method:: append_tab(pane: panel.panel, name: str | None = None) -> None .. py:method:: 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 :rtype: Path .. py:method:: 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. :param directory: base folder to save to. Defaults to "cachedir" which should be ignored by git. :type directory: str | Path, optional :param filename: The name of the html file. Defaults to the name of the benchmark :type filename: str, optional :param in_html_folder: Put the saved files in a html subfolder to help keep the results separate from source code. Defaults to True. :type in_html_folder: bool, optional :param portable: 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. :type portable: bool, optional :returns: the save path :rtype: Path .. py:method:: _write_iframe_index(index_path: pathlib.Path, tab_files: list) -> None :staticmethod: Write a lightweight HTML index with tab buttons and an iframe. .. py:method:: show(run_cfg: bencher.bench_cfg.BenchRunCfg | None = None) -> threading.Thread Launches a webserver with plots of the benchmark results, blocking :param run_cfg: Options for the webserve such as the port. Defaults to None. :type run_cfg: BenchRunCfg, optional .. py:method:: publish_gh_pages(github_user: str, repo_name: str, folder_name: str = 'report', branch_name: str = 'gh-pages') -> str .. py:method:: 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: .. code-block:: python def publish_args(branch_name) -> tuple[str, str]: return ( "https://github.com/blooop/bencher.git", f"https://github.com/blooop/bencher/blob/{branch_name}") :param remote: 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. :type remote: Callable :returns: the url of the published report :rtype: str