bencher.utils_rerun
===================

.. py:module:: bencher.utils_rerun

.. autoapi-nested-parse::

   Rerun SDK integration for bencher — capture live recordings.

   This module requires the ``rerun-sdk`` package.  For functions that work
   with pre-recorded ``.rrd`` files without the SDK, see ``utils_rrd.py``.

   Architecture
   ------------
   Displaying rerun data inside a Panel/Bokeh report requires two pieces:

   1. **Data capture** — ``capture_rerun_rrd()`` drains the in-memory rerun
      recording to a *complete* ``.rrd`` file on disk.  Using ``rr.save()``
      (which streams to an open file) does NOT work because the file is still
      being written when the viewer tries to fetch it.  Always call
      ``rr.log(...)`` first, then ``capture_rerun_rrd()`` / ``capture_rerun_window()``.

   2. **Viewer** — ``rrd_file_to_pane()`` (in ``utils_rrd.py``) writes a
      small HTML page that loads the ``@rerun-io/web-viewer`` from CDN and
      points it at the ``.rrd`` file.  Both the viewer page and the data are
      served by the Panel server at ``/rrd_static/``, keeping everything on
      the same HTTP origin (no CORS, no extra ports).



Functions
---------

.. autoapisummary::

   bencher.utils_rerun._ensure_rerun_init
   bencher.utils_rerun.capture_rerun_rrd
   bencher.utils_rerun.rerun_to_pane
   bencher.utils_rerun.capture_rerun_window


Module Contents
---------------

.. py:function:: _ensure_rerun_init()

   Ensure a rerun recording exists, creating one if needed.


.. py:function:: capture_rerun_rrd(recording: rerun.RecordingStream | None = None) -> str

   Save the current rerun recording to an .rrd file and return the path.

   Data must be logged BEFORE calling this function so that the in-memory
   recording has content to drain.  Calls ``rr.init()`` automatically if no
   recording exists yet.


.. py:function:: rerun_to_pane(width: int = 950, height: int = 712, recording: rerun.RecordingStream | None = None)

   Render the current rerun recording as an inline HTML pane.


.. py:function:: capture_rerun_window(recording: rerun.RecordingStream | None = None, **_kwargs) -> str

   Capture the current rerun recording and return the .rrd file path.

   Data must be logged BEFORE calling this function so that the in-memory
   recording has content to drain.  The returned path is stored by
   ``ResultRerun``; rendering into an HTML viewer pane happens later via
   ``ResultRerun.to_container()``.

   Viewer dimensions (``width``/``height``) are now taken from the
   ``ResultRerun`` descriptor.  Passing them here is deprecated and they
   will be ignored.