plesty.lib.ui.readings

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

`SCALABLE`
`PREFIXES`
`DIGITS`
`SUPERSCRIPTS`
`_EXPONENT`

Functions

`unit_text`(→ str)	Render a declared unit the way it is written down.
`_raise`(→ str)	Return exponent in superscript, or unchanged if any part has no form.
`number`(→ str)	Render value the way an instrument would show it.
`_trim`(→ str)	Render a float with `DIGITS` significant digits and no trailing zeros.
`value`(→ str)	Render one returned value of any shape.
`_name`(→ str)	Turn a mapping key into a label, as the control derivation does.
`result`() → str)	Render what one operation returned.

Module Contents

plesty.lib.ui.readings.SCALABLE: frozenset[str]

plesty.lib.ui.readings.PREFIXES: tuple[tuple[int, str], Ellipsis]

plesty.lib.ui.readings.DIGITS = 4

plesty.lib.ui.readings.SUPERSCRIPTS: dict[str, str]

plesty.lib.ui.readings._EXPONENT

plesty.lib.ui.readings.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.

Parameters:: unit (str | None) – The unit as declared, or None.
Returns:: The unit as shown; empty for None.
Return type:: str

plesty.lib.ui.readings._raise(exponent: str) → str

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

Parameters:: exponent (str)
Return type:: str

plesty.lib.ui.readings.number(value: float, unit: str | None = None) → str

Render value the way an instrument would show it.

Parameters:

value (float) – The number.
unit (str | None) – 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.

Return type:

str

plesty.lib.ui.readings._trim(value: float) → str

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

Parameters:: value (float)
Return type:: str

plesty.lib.ui.readings.value(item: Any, unit: str | None = None) → str

Render one returned value of any shape.

Parameters:

item (Any) – What the device returned for one output.
unit (str | None) – Its declared unit, if any.

Returns:

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

Return type:

str

plesty.lib.ui.readings._name(key: Any) → str

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

Parameters:: key (Any)
Return type:: str

plesty.lib.ui.readings.result(returned: Any, outputs: Sequence[Any] = ()) → str

Render what one operation returned.

Parameters:

returned (Any) – The operation’s result, usually the wire’s mapping.
outputs (Sequence[Any]) – The operation’s declared outputs (Control objects), which carry the units.

Returns:

One line for the panel.

Return type:

str