plesty.lib.ui.readings
======================

.. py:module:: plesty.lib.ui.readings

.. autoapi-nested-parse::

   Turning what a device returned into what an operator reads.

   An operation answers with the mapping the wire carries — ``{'power':
   1.478103e-06}`` — and a panel that shows it verbatim has handed the operator a
   Python literal to decode: braces, a quoted key repeating the button they just
   pressed, and a mantissa in scientific notation for a reading a meter would show
   as ``1.4781 uW``.

   The device already declared what it returns: a name, a type and a unit, in the
   operation's ``oparams``. That is enough to render the value as a reading, which
   is what this does. It is deliberately free of any toolkit, so the rules are
   tested without a display and are the same wherever a result is shown.

   Scaling is applied only to units it cannot get wrong. ``W`` may become ``uW``;
   ``mm`` may not, because prefixing an already-prefixed unit gives ``umm`` and a
   device that declares ``dB`` or ``%`` means neither.



Attributes
----------

.. autoapisummary::

   plesty.lib.ui.readings.SCALABLE
   plesty.lib.ui.readings.PREFIXES
   plesty.lib.ui.readings.DIGITS
   plesty.lib.ui.readings.SUPERSCRIPTS
   plesty.lib.ui.readings._EXPONENT


Functions
---------

.. autoapisummary::

   plesty.lib.ui.readings.unit_text
   plesty.lib.ui.readings._raise
   plesty.lib.ui.readings.number
   plesty.lib.ui.readings._trim
   plesty.lib.ui.readings.value
   plesty.lib.ui.readings._name
   plesty.lib.ui.readings.result


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

.. py:data:: SCALABLE
   :type:  frozenset[str]

.. py:data:: PREFIXES
   :type:  tuple[tuple[int, str], Ellipsis]

.. py:data:: DIGITS
   :value: 4


.. py:data:: SUPERSCRIPTS
   :type:  dict[str, str]

.. py:data:: _EXPONENT

.. py:function:: unit_text(unit: str | None) -> str

   Render a declared unit the way it is written down.

   A device declares an exponent in plain text — ``deg/s^2``, ``cm^-1`` — since
   that is what fits in a schema, a log line and a CSV header. On screen it is
   read as a unit, and ``deg/s²`` is that unit: the caret is punctuation a
   reader steps over, and a whole exponent is raised, sign and digits together,
   so ``10^9`` is ``10⁹`` and ``cm^-1`` is ``cm⁻¹``.

   What is not an exponent is left exactly as declared. ``e``-notation is not
   touched, so a unit is never confused with the value beside it.

   :param unit: The unit as declared, or ``None``.

   :returns: The unit as shown; empty for ``None``.


.. py:function:: _raise(exponent: str) -> str

   Return *exponent* in superscript, or unchanged if any part has no form.


.. py:function:: number(value: float, unit: str | None = None) -> str

   Render *value* the way an instrument would show it.

   :param value: The number.
   :param unit: Its declared unit, or ``None``.

   :returns: The value with a metric prefix when the unit takes one, trimmed of
             trailing zeros, with the unit appended.


.. py:function:: _trim(value: float) -> str

   Render a float with :data:`DIGITS` significant digits and no trailing zeros.


.. py:function:: value(item: Any, unit: str | None = None) -> str

   Render one returned value of any shape.

   :param item: What the device returned for one output.
   :param unit: Its declared unit, if any.

   :returns: Readable text; nested mappings and sequences are flattened rather than
             printed as literals.


.. py:function:: _name(key: Any) -> str

   Turn a mapping key into a label, as the control derivation does.


.. py:function:: result(returned: Any, outputs: Sequence[Any] = ()) -> str

   Render what one operation returned.

   :param returned: The operation's result, usually the wire's mapping.
   :param outputs: The operation's declared outputs
                   (:class:`~plesty.lib.ui.device_panel.Control` objects), which carry
                   the units.

   :returns: One line for the panel.