plesty.lib.report.html
======================

.. py:module:: plesty.lib.report.html

.. autoapi-nested-parse::

   A report as an HTML fragment, for a page that sets it in its own style.

   The fragment carries class names and no styling: ``assets/report.css`` is a
   stylesheet for it, and a page such as the bench's run export brings its own.
   Math is converted to MathML, which browsers draw natively, so the fragment
   needs no script to show an equation — that takes the optional ``latex2mathml``
   (``pip install plesty-lib[report]``); without it an equation is shown as its
   LaTeX source. Figures are inline SVG (:mod:`plesty.lib.report.svg`).

   HTML from :meth:`~plesty.lib.report.Table.raw` is sanitised: a report is
   written by a third-party analyzer package, and it is shown inside a page that
   may hold other things.



Attributes
----------

.. autoapisummary::

   plesty.lib.report.html._DEFAULT_ALIGN
   plesty.lib.report.html.ALLOWED_TAGS
   plesty.lib.report.html.ALLOWED_ATTRIBUTES
   plesty.lib.report.html._VOID
   plesty.lib.report.html._DROPPED


Classes
-------

.. autoapisummary::

   plesty.lib.report.html._Sanitizer


Functions
---------

.. autoapisummary::

   plesty.lib.report.html.to_html
   plesty.lib.report.html._block
   plesty.lib.report.html.inline
   plesty.lib.report.html._spans
   plesty.lib.report.html.math
   plesty.lib.report.html._math_source
   plesty.lib.report.html._value
   plesty.lib.report.html._cell
   plesty.lib.report.html._rows
   plesty.lib.report.html._notes
   plesty.lib.report.html._table
   plesty.lib.report.html._figure
   plesty.lib.report.html.sanitize


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

.. py:data:: _DEFAULT_ALIGN

.. py:function:: to_html(item: Any, level: int = 2) -> str

   Render a report, or one block of it, as an HTML fragment.

   :param item: A :class:`~plesty.lib.report.Report` or a single block.
   :param level: Heading level of the report's title (``2`` → ``<h2>``); block
                 titles are one level below it.

   :returns: The fragment.


.. py:function:: _block(block: Any, level: int) -> str

   Render one block.


.. py:function:: inline(text: str) -> str

   Render inline markup (see :mod:`plesty.lib.report.markup`) as HTML.


.. py:function:: _spans(spans: list[plesty.lib.report.markup.Span]) -> str

   Render parsed spans.


.. py:function:: math(tex: str) -> str

   Render one LaTeX math expression as MathML, or as its source without it.


.. py:function:: _math_source(tex: str) -> str

   Show an expression as the LaTeX it was written in.


.. py:function:: _value(cell: plesty.lib.report.blocks.Value) -> str

   Render a number, its uncertainty, and a shared power of ten.


.. py:function:: _cell(cell: plesty.lib.report.blocks._Spanning, tag: str) -> str

   Render one cell, with its span, alignment and note mark.


.. py:function:: _rows(table: plesty.lib.report.blocks.Table, section: str, tag: str) -> str

   Render a section's rows: only the cells that start in each row.


.. py:function:: _notes(table: plesty.lib.report.blocks.Table) -> str

   Render the footnotes and the defined terms below a table.


.. py:function:: _table(table: plesty.lib.report.blocks.Table, level: int) -> str

   Render a table: its title, grid, notes and caption.


.. py:function:: _figure(figure: plesty.lib.report.blocks.Figure, level: int) -> str

   Render a figure as inline SVG with its title and caption.


.. py:data:: ALLOWED_TAGS

.. py:data:: ALLOWED_ATTRIBUTES

.. py:data:: _VOID

.. py:data:: _DROPPED

.. py:class:: _Sanitizer

   Bases: :py:obj:`html.parser.HTMLParser`


   Rebuild HTML from allowed elements and attributes only.

   Initialize and reset this instance.

   If convert_charrefs is True (the default), all character references
   are automatically converted to the corresponding Unicode characters.


   .. py:attribute:: out
      :type:  list[str]
      :value: []



   .. py:attribute:: open
      :type:  list[str]
      :value: []



   .. py:attribute:: dropping
      :value: 0



   .. py:method:: handle_starttag(tag: str, attrs: list[tuple[str, Optional[str]]]) -> None


   .. py:method:: handle_startendtag(tag: str, attrs: list[tuple[str, Optional[str]]]) -> None


   .. py:method:: handle_endtag(tag: str) -> None


   .. py:method:: handle_data(data: str) -> None


.. py:function:: sanitize(markup: str) -> str

   Keep only table, inline-text and MathML elements, with harmless attributes.

   Scripts, styles and embedded content are dropped with what is inside them;
   any other element is dropped and its text kept; event handlers, links and
   inline styles are dropped from the elements that stay. Every element left
   open is closed.

   :param markup: Untrusted HTML.

   :returns: Safe HTML.