plesty.lib.monitor.viz
======================

.. py:module:: plesty.lib.monitor.viz

.. autoapi-nested-parse::

   The command line that watches a run — an experiment supplies only its panels.

   Everything about *watching* is the same for every experiment: which run
   (the newest, or ``--run``), where the share is mounted, live or replayed,
   in a window or rendered offscreen to a video, recorded or not. What differs
   is which record key means what. :class:`Viz` owns the former; the experiment
   writes one function for the latter and is done:

   .. code-block:: python

       from plesty.common_monitors import SpectrumMonitor, WaterfallMonitor
       from plesty.common_monitors.spectrum import spectrum_mapper
       from plesty.lib.monitor import Viz
       from plesty.lib.ui import MonitorPanel

       viz = Viz("Polarization PL", experiment="pol_pl")

       @viz.panels
       def panels(run):
           spectra = spectrum_mapper("data_file", locate=run.local, row_key="hwp_deg")
           yield MonitorPanel(SpectrumMonitor(run.source(spectra), name="spectrum"), weight=3)
           yield MonitorPanel(WaterfallMonitor(run.source(spectra), name="map"), weight=3)

       if __name__ == "__main__":
           sys.exit(viz.main())

   .. code-block:: bash

       python -m plesty.pol_pl.viz monitor                 # follow the newest run live
       python -m plesty.pol_pl.viz monitor --replay 2      # replay a stored run, 2 rows/refresh
       python -m plesty.pol_pl.viz render --run <run-id>   # <run-id>.mp4, no window needed

   The panels function receives a :class:`~plesty.lib.experiment.runs.Run` and
   yields :class:`~plesty.lib.ui.Panel` objects in docking order.
   ``run.source(mapper)`` is already live or replayed as the subcommand
   decided — one call per view: a source hands each record out once, so two
   views on one source would split the rows between them (a mapper is freely
   shared) — ``run.local`` translates the acquiring host's paths, and
   ``run.config`` is the frozen configuration — enough to decide which panels
   a run gets. This module imports no toolkit until :meth:`Viz.main` runs, so
   ``--help`` and the parser work on a headless host.



Attributes
----------

.. autoapisummary::

   plesty.lib.monitor.viz.PanelsFunc
   plesty.lib.monitor.viz._TEXT


Classes
-------

.. autoapisummary::

   plesty.lib.monitor.viz.Viz


Functions
---------

.. autoapisummary::

   plesty.lib.monitor.viz._text


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

.. py:data:: PanelsFunc

.. py:data:: _TEXT
   :type:  Optional[dict[str, Any]]
   :value: None


.. py:function:: _text() -> dict[str, Any]

   Return the command-line text catalog (loaded once from the assets).


.. py:class:: Viz(title: str, *, experiment: Union[str, Sequence[str], None] = None, run_root: Optional[str | pathlib.Path] = None)

   The ``monitor`` / ``render`` command line over one experiment's panels.

   Describe the experiment whose runs are watched.

   :param title: Human title of the experiment, shown in the window
                 title and the command-line description.
   :param experiment: The experiment name(s) whose runs to look for when
                      ``--run`` is not given — a name or several (an experiment
                      that was renamed still owns its old runs). ``None`` takes
                      the newest run of any experiment.
   :param run_root: Where runs are looked for; ``None`` takes
                    ``PLESTY_DATA_MOUNT`` (runs land on the share) and falls
                    back to ``runs``. ``--run-root`` overrides per call.


   .. py:attribute:: title


   .. py:attribute:: experiment
      :value: None



   .. py:attribute:: run_root
      :value: None



   .. py:attribute:: _panels
      :type:  Optional[PanelsFunc]
      :value: None



   .. py:method:: panels(func: PanelsFunc) -> PanelsFunc

      Register the function that turns a :class:`Run` into panels.

      Use as a decorator. The function is called once per invocation and
      may return or yield any number of panels — none for a run that has
      nothing to show is an error worth naming, not an empty window.



   .. py:method:: build_parser() -> argparse.ArgumentParser

      Return the argument parser: shared options plus the two subcommands.



   .. py:method:: resolve_run(args: argparse.Namespace) -> plesty.lib.experiment.runs.Run

      Return the :class:`Run` the arguments name, configured for the subcommand.

      :raises SystemExit: If no run exists yet — a viewer opened before its
          experiment is a mistake worth naming, not an empty window.



   .. py:method:: main(argv: Optional[Sequence[str]] = None) -> int

      Run the command line and return the exit code.

      :param argv: Argument list; ``None`` uses ``sys.argv``.

      :raises RuntimeError: If no panels function was registered.
      :raises SystemExit: If no run exists, or the panels function yields
          nothing.