mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/units.py

@@ -0,0 +1,572 @@
+"""The deterministic unit grammar: a documented UCUM subset, read from a pinned table.
+
+A declared unit is a code in the subset of UCUM that ``docs/UNITS.md`` states, and validation is
+the question "does it resolve against the pinned table" rather than "is it in a hand-grown list".
+The table under ``ucum/`` carries the atoms, the prefixes and their exact values; nothing here
+guesses, converts through floating point, or reaches a network.
+
+Two things this module deliberately does not do.
+
+It does not rewrite a declared code. ``semantics.columns.unit`` is sealed as the author wrote it,
+so a code is resolved for comparison and never canonicalised in place: rewriting ``ug/m3`` into a
+canonical spelling would move the digest of every Build that carried it.
+
+And it does not treat a temperature as a ratio. ``Cel`` and ``[degF]`` are affine: zero degrees
+Celsius is not zero of anything, so no multiplier turns one into the other. They resolve with an
+exact scale *and* an exact offset, and every comparison here uses the pair. A caller that reduces
+a unit to one number is refused rather than quietly answered.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from fractions import Fraction
+from functools import lru_cache
+from pathlib import Path
+from types import MappingProxyType
+from typing import Any, Final
+
+UCUM_SUBSET_VERSION: Final = "ucum-subset.v1"
+
+#: The sentinel a column carries when it declares no physical unit at all. It is not a UCUM code
+#: and never resolves to one: ``unit_state`` uses it to mean "there is nothing here to convert",
+#: which is a different claim from the dimensionless ``1``.
+NO_UNIT: Final = "none"
+
+_TABLE_DIRECTORY: Final = Path(__file__).resolve().parent / "ucum"
+_TABLE_FILE: Final = "ucum-subset.v1.json"
+
+# Bounds. A unit code is a label on a column, not a document: these are wide enough for every
+# code the subset can spell and narrow enough that no input turns resolution into work.
+MAX_UNIT_LENGTH: Final = 64
+MAX_UNIT_TERMS: Final = 16
+MAX_UNIT_EXPONENT: Final = 9
+MAX_ANNOTATION_LENGTH: Final = 32
+# Magnitude, which the length and term bounds do not constrain: sixteen terms of a large atom
+# raised to the ninth power stay inside every bound above and resolve to a number with thousands of
+# digits, which is past what the interpreter will render and therefore past what this module can
+# report. Nothing anybody measures in lives outside this window -- a yottamole is 6 times 10 to the
+# 47 -- so a code that leaves it is refused here rather than at some later `str()`.
+MAX_UNIT_MAGNITUDE_EXPONENT: Final = 120
+
+_ANNOTATION = re.compile(r"^[A-Za-z0-9_]+$")
+_EXPONENT = re.compile(r"^[+-]?[0-9]{1,2}$")
+
+# Constructs UCUM has and this subset does not. Each is named in the refusal so the author is told
+# what was rejected rather than that something was.
+_UNSUPPORTED_CONSTRUCTS: Final = (
+    ("(", "a parenthesised sub-expression"),
+    (")", "a parenthesised sub-expression"),
+    ("*", "a numeric factor such as 10*3"),
+    ("^", "a numeric factor such as 10^3"),
+    (" ", "a space"),
+)
+
+
+class UnitError(ValueError):
+    """A typed failure to resolve a unit code, with the exact construct that was refused."""
+
+    def __init__(self, code: str, detail: str, *, unit: str) -> None:
+        self.code = code
+        self.detail = detail
+        self.unit = unit
+        super().__init__(f"{unit!r}: {detail} [{code}]")
+
+
+@dataclass(frozen=True)
+class Unit:
+    """One resolved unit: its dimension, its exact scale, and its exact offset.
+
+    ``factor`` and ``offset`` are the affine map into the table's base units: a value ``x`` in
+    this unit is ``x * factor + offset`` in base units. ``offset`` is zero for every ratio-scale
+    unit, which is every unit in the subset except ``Cel`` and ``[degF]``.
+    """
+
+    code: str
+    exponents: tuple[int, ...]
+    factor: Fraction
+    offset: Fraction
+    annotations: tuple[str, ...]
+
+    @property
+    def affine(self) -> bool:
+        """Report whether this unit's zero is somewhere other than the base unit's zero."""
+
+        return self.offset != 0
+
+    @property
+    def dimensionless(self) -> bool:
+        return not any(self.exponents)
+
+
+@dataclass(frozen=True)
+class UnitTable:
+    """The pinned atom and prefix table, loaded once and never mutated."""
+
+    version: str
+    standard_version: str
+    standard_release: str
+    dimensions: tuple[str, ...]
+    prefixes: Any
+    atoms: Any
+    legacy_aliases: Any
+
+
+def _fraction(value: str) -> Fraction:
+    return Fraction(value)
+
+
+_MAGNITUDE_CEILING: Final = Fraction(10) ** MAX_UNIT_MAGNITUDE_EXPONENT
+_MAGNITUDE_FLOOR: Final = Fraction(1) / _MAGNITUDE_CEILING
+
+
+def _require_bounded(factor: Fraction, unit: str) -> None:
+    if not _MAGNITUDE_FLOOR <= factor <= _MAGNITUDE_CEILING:
+        raise UnitError(
+            "UCUM_MAGNITUDE_RANGE",
+            "the resolved magnitude is outside 10 to the plus or minus "
+            f"{MAX_UNIT_MAGNITUDE_EXPONENT}, which no measured quantity reaches",
+            unit=unit,
+        )
+
+
+@lru_cache(maxsize=1)
+def unit_table() -> UnitTable:
+    """Load the pinned subset table.
+
+    The read happens once per process. The table is data rather than code precisely so that the
+    values it carries can be pinned by digest and recomputed from their own definitions, which is
+    what ``tests/test_units_table.py`` does.
+    """
+
+    document = json.loads((_TABLE_DIRECTORY / _TABLE_FILE).read_text(encoding="utf-8"))
+    if document.get("schema") != UCUM_SUBSET_VERSION:
+        raise UnitError(
+            "UCUM_TABLE_VERSION",
+            f"the unit table declares {document.get('schema')!r}, not {UCUM_SUBSET_VERSION!r}",
+            unit="",
+        )
+    dimensions = tuple(item["symbol"] for item in document["dimensions"])
+    width = len(dimensions)
+    atoms: dict[str, dict[str, Any]] = {}
+    for symbol, entry in document["atoms"].items():
+        exponents = tuple(int(value) for value in entry["exponents"])
+        if len(exponents) != width:
+            raise UnitError(
+                "UCUM_TABLE_SHAPE",
+                f"atom {symbol!r} records {len(exponents)} exponents for {width} dimensions",
+                unit=symbol,
+            )
+        atoms[symbol] = {
+            "name": entry["name"],
+            "kind": entry["kind"],
+            "metric": bool(entry["metric"]),
+            "exponents": exponents,
+            "factor": _fraction(entry["factor"]),
+            "offset": _fraction(entry["offset"]) if "offset" in entry else Fraction(0),
+            "definition": entry.get("definition"),
+        }
+    prefixes = {
+        symbol: {"name": entry["name"], "factor": _fraction(entry["factor"])}
+        for symbol, entry in document["prefixes"].items()
+    }
+    return UnitTable(
+        version=document["schema"],
+        standard_version=document["standard_version"],
+        standard_release=document["standard_release"],
+        dimensions=dimensions,
+        prefixes=MappingProxyType(prefixes),
+        atoms=MappingProxyType(atoms),
+        legacy_aliases=MappingProxyType(dict(document["legacy_aliases"])),
+    )
+
+
+def legacy_aliases() -> Any:
+    """The fifteen tokens the hand-grown list held, mapped to the codes they always meant.
+
+    ``none`` is absent on purpose: it was never a unit and does not become one here.
+    """
+
+    return unit_table().legacy_aliases
+
+
+def _split_terms(text: str, unit: str) -> list[tuple[int, str]]:
+    """Split an expression into signed terms without splitting inside a bracketed atom."""
+
+    terms: list[tuple[int, str]] = []
+    sign = 1
+    start = 0
+    depth = 0
+    braces = 0
+    if text.startswith("/"):
+        sign = -1
+        start = 1
+    position = start
+    while position < len(text):
+        character = text[position]
+        if character == "[":
+            depth += 1
+        elif character == "]":
+            depth -= 1
+            if depth < 0:
+                raise UnitError("UCUM_SYNTAX", "a ']' closes nothing", unit=unit)
+        elif character == "{":
+            braces += 1
+        elif character == "}":
+            braces -= 1
+            if braces < 0:
+                raise UnitError("UCUM_SYNTAX", "a '}' closes nothing", unit=unit)
+        elif character in "./" and depth == 0 and braces == 0:
+            terms.append((sign, text[start:position]))
+            sign = 1 if character == "." else -1
+            start = position + 1
+        position += 1
+    if depth or braces:
+        raise UnitError("UCUM_SYNTAX", "a bracket or brace is left open", unit=unit)
+    terms.append((sign, text[start:]))
+    return terms
+
+
+def _annotation(term: str, unit: str) -> tuple[str, str | None]:
+    """Split one trailing ``{...}`` annotation off a term."""
+
+    if not term.endswith("}"):
+        if "{" in term or "}" in term:
+            raise UnitError(
+                "UCUM_ANNOTATION",
+                "an annotation must be a '{...}' suffix on one term",
+                unit=unit,
+            )
+        return term, None
+    opened = term.find("{")
+    if opened < 0:
+        raise UnitError("UCUM_SYNTAX", "a '}' closes nothing", unit=unit)
+    text = term[opened + 1 : -1]
+    if not 1 <= len(text) <= MAX_ANNOTATION_LENGTH or not _ANNOTATION.fullmatch(text):
+        raise UnitError(
+            "UCUM_ANNOTATION",
+            f"an annotation must be 1..{MAX_ANNOTATION_LENGTH} letters, digits or underscores",
+            unit=unit,
+        )
+    return term[:opened], text
+
+
+def _exponent(body: str, unit: str) -> tuple[str, int]:
+    """Split a trailing integer power off a term body."""
+
+    if body != "1" and body.lstrip("+-").isdigit():
+        raise UnitError(
+            "UCUM_UNSUPPORTED_CONSTRUCT",
+            f"a numeric factor such as {body} is outside {UCUM_SUBSET_VERSION}",
+            unit=unit,
+        )
+    digits = ""
+    while len(body) > 1 and body[-1].isdigit():
+        digits = body[-1] + digits
+        body = body[:-1]
+    if len(body) > 1 and body[-1] in "+-" and digits:
+        digits = body[-1] + digits
+        body = body[:-1]
+    if not digits:
+        return body, 1
+    if not _EXPONENT.fullmatch(digits):
+        raise UnitError("UCUM_SYNTAX", f"{digits!r} is not an integer power", unit=unit)
+    exponent = int(digits)
+    if not -MAX_UNIT_EXPONENT <= exponent <= MAX_UNIT_EXPONENT or exponent == 0:
+        raise UnitError(
+            "UCUM_EXPONENT_RANGE",
+            f"an integer power must be between -{MAX_UNIT_EXPONENT} and {MAX_UNIT_EXPONENT} "
+            "and may not be zero",
+            unit=unit,
+        )
+    return body, exponent
+
+
+def _resolve_atom(symbol: str, unit: str) -> tuple[dict[str, Any], Fraction]:
+    """Resolve one atom, taking the whole symbol first and a prefix split only if it is not one.
+
+    The order is the rule, not a preference. ``cd`` is the candela and not a centi-day, and ``Pa``
+    is the pascal and not a peta-year, because a symbol the table holds outright is never read as
+    something else. Where the whole symbol is unknown, exactly one prefix split may resolve it; a
+    symbol that two splits could explain is refused rather than silently decided.
+    """
+
+    table = unit_table()
+    atom = table.atoms.get(symbol)
+    if atom is not None:
+        return atom, Fraction(1)
+    matches: list[tuple[str, dict[str, Any], Fraction]] = []
+    special: list[str] = []
+    non_metric: list[str] = []
+    for prefix, entry in table.prefixes.items():
+        if not symbol.startswith(prefix):
+            continue
+        remainder = symbol[len(prefix) :]
+        candidate = table.atoms.get(remainder)
+        if candidate is None:
+            continue
+        if candidate["kind"] == "special":
+            special.append(remainder)
+            continue
+        if not candidate["metric"]:
+            non_metric.append(remainder)
+            continue
+        matches.append((prefix, candidate, entry["factor"]))
+    if not matches and special:
+        raise UnitError(
+            "UCUM_PREFIX_ON_SPECIAL",
+            f"{special[0]!r} is an offset unit and this subset accepts no prefix on one",
+            unit=unit,
+        )
+    if not matches and non_metric:
+        raise UnitError(
+            "UCUM_PREFIX_ON_NON_METRIC",
+            f"{non_metric[0]!r} takes no prefix, so {symbol!r} is not a unit",
+            unit=unit,
+        )
+    if not matches:
+        raise UnitError(
+            "UCUM_UNKNOWN_ATOM",
+            f"{symbol!r} is not an atom in {UCUM_SUBSET_VERSION}",
+            unit=unit,
+        )
+    if len(matches) > 1:
+        spellings = ", ".join(f"{prefix}+{symbol[len(prefix) :]}" for prefix, _, _ in matches)
+        raise UnitError(
+            "UCUM_AMBIGUOUS_ATOM",
+            f"{symbol!r} reads as more than one prefixed atom ({spellings})",
+            unit=unit,
+        )
+    _prefix, candidate, factor = matches[0]
+    return candidate, factor
+
+
+def parse_unit(unit: str) -> Unit:
+    """Resolve one UCUM code from the documented subset, or refuse it by name.
+
+    This is the whole of the acceptance test for ``semantics.columns.unit``. It is total: every
+    input either resolves to a :class:`Unit` or raises a :class:`UnitError` whose code says which
+    rule refused it.
+    """
+
+    if not isinstance(unit, str):
+        raise UnitError("UCUM_SYNTAX", "a unit code must be text", unit=str(unit))
+    if not unit:
+        raise UnitError("UCUM_SYNTAX", "a unit code must not be empty", unit=unit)
+    if len(unit) > MAX_UNIT_LENGTH:
+        raise UnitError(
+            "UCUM_LENGTH", f"a unit code may not exceed {MAX_UNIT_LENGTH} characters", unit=unit
+        )
+    for character, description in _UNSUPPORTED_CONSTRUCTS:
+        if character in unit:
+            raise UnitError(
+                "UCUM_UNSUPPORTED_CONSTRUCT",
+                f"{description} is outside {UCUM_SUBSET_VERSION}",
+                unit=unit,
+            )
+    if unit != unit.strip() or any(ord(character) < 0x20 for character in unit):
+        raise UnitError("UCUM_SYNTAX", "a unit code is one plain line of text", unit=unit)
+
+    terms = _split_terms(unit, unit)
+    if len(terms) > MAX_UNIT_TERMS:
+        raise UnitError(
+            "UCUM_LENGTH", f"a unit code may not exceed {MAX_UNIT_TERMS} terms", unit=unit
+        )
+
+    table = unit_table()
+    exponents = [0] * len(table.dimensions)
+    factor = Fraction(1)
+    offset = Fraction(0)
+    annotations: list[str] = []
+    special_terms = 0
+    for sign, term in terms:
+        if not term:
+            raise UnitError("UCUM_SYNTAX", "a term is empty", unit=unit)
+        body, annotation = _annotation(term, unit)
+        if annotation is not None:
+            annotations.append(annotation)
+        if not body:
+            # A bare annotation is unity carrying a label, which is what ``{count}`` is.
+            if sign < 0:
+                raise UnitError(
+                    "UCUM_SYNTAX", "a bare annotation cannot be a denominator", unit=unit
+                )
+            continue
+        body, exponent = _exponent(body, unit)
+        atom, prefix_factor = _resolve_atom(body, unit)
+        if atom["kind"] == "special":
+            special_terms += 1
+            if annotation is not None or exponent != 1 or len(terms) > 1 or sign < 0:
+                raise UnitError(
+                    "UCUM_SPECIAL_UNIT_NOT_COMPOSABLE",
+                    f"{body!r} is an offset unit: it stands alone, with no power, no "
+                    "annotation and nothing multiplied by it",
+                    unit=unit,
+                )
+            offset = atom["offset"]
+        power = sign * exponent
+        factor *= (prefix_factor * atom["factor"]) ** power
+        for index, value in enumerate(atom["exponents"]):
+            exponents[index] += value * power
+    # The resolved magnitude, once, rather than the running product: ``mol9/mol9`` comes to one and
+    # is a unit, and bounding the partial product would have refused it for a number it never has.
+    # The intermediate is bounded by the term and exponent caps rather than by this, and stays
+    # small enough to hold; what it is not always small enough to do is be written out.
+    _require_bounded(factor, unit)
+    if special_terms > 1:  # pragma: no cover - the single-term rule above already refuses this.
+        raise UnitError(
+            "UCUM_SPECIAL_UNIT_NOT_COMPOSABLE", "two offset units cannot be combined", unit=unit
+        )
+    return Unit(
+        code=unit,
+        exponents=tuple(exponents),
+        factor=factor,
+        offset=offset,
+        annotations=tuple(sorted(set(annotations))),
+    )
+
+
+def resolve_declared_unit(declared: str) -> Unit:
+    """Resolve a declared unit, reading a legacy token as the code it always meant.
+
+    The fifteen tokens the hand-grown list held keep resolving forever. They are aliases rather
+    than a second vocabulary: ``celsius`` and ``Cel`` resolve to the same unit, so a Build sealed
+    with one and a plan authored with the other are talking about the same thing.
+    """
+
+    if not isinstance(declared, str):
+        # Before the alias lookup, which hashes what it is given: a declaration that is not text
+        # would otherwise leave here as a TypeError, one call short of the boundary this module
+        # promises to be total at.
+        raise UnitError("UCUM_SYNTAX", "a unit code must be text", unit=str(declared))
+    if declared == NO_UNIT:
+        raise UnitError(
+            "UCUM_NOT_A_UNIT",
+            f"{NO_UNIT!r} declares the absence of a unit and resolves to no code",
+            unit=declared,
+        )
+    return parse_unit(legacy_aliases().get(declared, declared))
+
+
+def is_declarable_unit(declared: str) -> bool:
+    """Report whether a declared string resolves, without raising."""
+
+    try:
+        resolve_declared_unit(declared)
+    except UnitError:
+        return False
+    return True
+
+
+def commensurable(left: Unit, right: Unit) -> bool:
+    """Report whether two units measure the same kind of thing."""
+
+    return left.exponents == right.exponents
+
+
+def same_unit(left: Unit, right: Unit) -> bool:
+    """Report whether two codes name one unit, annotations included.
+
+    ``{count}`` and ``1`` are both dimensionless with factor one and are still not the same unit:
+    a count of hospitals is not a ratio, and the annotation is the only thing that says so.
+    """
+
+    return (
+        left.exponents == right.exponents
+        and left.factor == right.factor
+        and left.offset == right.offset
+        and left.annotations == right.annotations
+    )
+
+
+def conversion(source: Unit, target: Unit) -> tuple[Fraction, Fraction]:
+    """Return the exact affine map ``(scale, offset)`` taking a value in ``source`` to ``target``.
+
+    ``value_target == value_source * scale + offset``. For every ratio-scale pair the offset is
+    zero and the scale is the factor a conversion has to multiply by. For the two offset units it
+    is not: Celsius to Fahrenheit is ``9/5`` and ``32``, and a check that looked only at the scale
+    would accept a conversion that is wrong by thirty-two degrees at every temperature.
+    """
+
+    if not commensurable(source, target):
+        raise UnitError(
+            "UCUM_NOT_COMMENSURABLE",
+            f"{source.code!r} and {target.code!r} do not measure the same kind of thing",
+            unit=source.code,
+        )
+    scale = source.factor / target.factor
+    offset = (source.offset - target.offset) / target.factor
+    return scale, offset
+
+
+def ratio_scale_factor(unit: Unit) -> Fraction:
+    """The single multiplier that takes this unit into base units, for a ratio-scale unit only.
+
+    An offset unit has no such number. Twenty degrees Celsius is not twenty of anything, and a
+    caller that multiplied by this unit's scale and stopped would be wrong by the offset at every
+    value -- which is the whole reason the two temperature scales are carried as a pair. So the
+    question is refused rather than answered with half of it.
+    """
+
+    if unit.affine:
+        raise UnitError(
+            "UCUM_AFFINE_UNIT",
+            f"{unit.code!r} is an offset unit: it has a scale and an offset, and no single "
+            "multiplier stands for both. Use conversion() instead",
+            unit=unit.code,
+        )
+    return unit.factor
+
+
+def dimension_signature(unit: Unit) -> str:
+    """A stable, readable spelling of a unit's dimension for a refusal message."""
+
+    table = unit_table()
+    parts = [
+        symbol if exponent == 1 else f"{symbol}{exponent}"
+        for symbol, exponent in zip(table.dimensions, unit.exponents, strict=True)
+        if exponent
+    ]
+    return ".".join(parts) if parts else "1"
+
+
+COUNT_UNIT_CODE: Final = "{count}"
+
+
+def is_count_unit(unit: Unit) -> bool:
+    """Report whether a unit is the dimensionless count, however it was spelled."""
+
+    return (
+        unit.dimensionless
+        and unit.factor == 1
+        and unit.offset == 0
+        and unit.annotations == ("count",)
+    )
+
+
+__all__ = [
+    "COUNT_UNIT_CODE",
+    "MAX_ANNOTATION_LENGTH",
+    "MAX_UNIT_EXPONENT",
+    "MAX_UNIT_LENGTH",
+    "MAX_UNIT_MAGNITUDE_EXPONENT",
+    "MAX_UNIT_TERMS",
+    "NO_UNIT",
+    "UCUM_SUBSET_VERSION",
+    "Unit",
+    "UnitError",
+    "UnitTable",
+    "commensurable",
+    "conversion",
+    "dimension_signature",
+    "is_count_unit",
+    "is_declarable_unit",
+    "legacy_aliases",
+    "parse_unit",
+    "ratio_scale_factor",
+    "resolve_declared_unit",
+    "same_unit",
+    "unit_table",
+]

mostlyright/data_harness/ux/__init__.py

@@ -0,0 +1,9 @@
+"""Human-facing surfaces for ``mr-data``.
+
+Every command emits the same facts twice: as plain labelled lines by default and as one JSON
+object under ``--json``. Both renderings are built from a single payload mapping, so a fact that
+reaches one rendering reaches the other.
+
+This package holds the rendering and the command registry only. It deliberately re-exports
+nothing, so importing it stays cheap for the CLI startup path.
+"""