plesty.server.services.run_report
=================================

.. py:module:: plesty.server.services.run_report

.. autoapi-nested-parse::

   A finished run, compiled into one HTML file.

   What a measurement is worth to somebody who was not standing there: what was
   run and how it was configured, what the instruments were, what came out, and
   what the analyzers made of it. All of that is already in the run directory —
   this reads it and lays it out, and invents nothing.

   **The run is read directly, not through plesty-lib's readers.** An experiment
   runs in an environment of its own, so the library that wrote a run's documents
   is routinely newer than the one the console has: a bench on plesty-lib 0.4.1
   cannot load a document whose ``type`` is ``experiment_data``, which 0.5 added,
   and would refuse to report a run it can plainly see. The formats read here —
   JSON Lines for the journal and the records, a document beside its ``.npz`` for
   an analysis — are the stable part, so reading them by hand is what makes the
   report work across the version skew a real bench has.

   **One file, no script, nothing fetched.** The stylesheet is inlined and the
   markup comes from ``assets/report.html``; the report has to open from a USB
   stick, from an attachment, and in ten years.



Attributes
----------

.. autoapisummary::

   plesty.server.services.run_report.MAX_ROWS


Exceptions
----------

.. autoapisummary::

   plesty.server.services.run_report.ReportError


Functions
---------

.. autoapisummary::

   plesty.server.services.run_report.report
   plesty.server.services.run_report.write
   plesty.server.services.run_report.suggested_name


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

.. py:data:: MAX_ROWS
   :value: 500


.. py:exception:: ReportError

   Bases: :py:obj:`RuntimeError`


   The run could not be read well enough to report on.

   Initialize self.  See help(type(self)) for accurate signature.


.. py:function:: report(run_dir: str | pathlib.Path, experiment: str = '') -> str

   Compile the run at *run_dir* into one self-contained HTML document.

   :param run_dir: The run directory — journal, plan, records and analysis.
   :param experiment: What the bench calls the experiment; the run's own name is
                      used when it is not given.

   :returns: The HTML.

   :raises ReportError: When the directory holds no run.


.. py:function:: write(run_dir: str | pathlib.Path, target: str | pathlib.Path, experiment: str = '') -> pathlib.Path

   Compile the run and write it to *target*; returns the path written.

   :raises ReportError: When the run cannot be read, or the file cannot be written.


.. py:function:: suggested_name(run_dir: str | pathlib.Path, experiment: str = '') -> str

   A file name for the run's report, findable by what it is a report of.