mdq-models 0.1.0__py3-none-any.whl

mdq_models/__init__.py

@@ -0,0 +1,34 @@
+"""Hand-written data models of the canonical meter-reading schema.
+
+The contract is the JSON form of these models, pinned by the shared fixtures in ``testdata/`` that
+the Go and the Python models both round-trip. Nothing here is generated.
+
+Read JSON with ``Messwert.model_validate_json`` (it rejects duplicate keys, which plain pydantic would
+silently resolve) and write it with ``model_dump_json()``.
+
+Limit: only ``model_validate_json`` of ``Messwert`` and ``Zaehlerstand`` rejects duplicate keys.
+``TypeAdapter(...).validate_json``, a model that contains one of them and ``__pydantic_validator__`` go straight to
+pydantic's parser and keep the last duplicate; call :func:`check_json` on the raw document first. All parse
+failures are ``pydantic.ValidationError``.
+"""
+
+from mdq_models._base import check_json
+from mdq_models._version import version as __version__
+from mdq_models.enums import Herkunft, Profiltyp, Richtung, Status
+from mdq_models.malo import herkunft_passt_zu_status, is_valid_malo_id, malo_check_digit
+from mdq_models.messwert import Messwert
+from mdq_models.zaehlerstand import Zaehlerstand
+
+__all__ = [
+    "Herkunft",
+    "Messwert",
+    "Profiltyp",
+    "Richtung",
+    "Status",
+    "Zaehlerstand",
+    "__version__",
+    "check_json",
+    "herkunft_passt_zu_status",
+    "is_valid_malo_id",
+    "malo_check_digit",
+]

mdq_models/_base.py

@@ -0,0 +1,137 @@
+"""Base class of the models: strict reading (duplicate and unknown keys are rejected) and frozen instances."""
+
+import json
+import re
+from typing import Any, NoReturn, Self
+
+from pydantic import BaseModel, ConfigDict, ValidationError
+from pydantic_core import InitErrorDetails, PydanticCustomError
+
+
+class _DuplicateKeyError(ValueError):
+    """A JSON object repeats a key (internal: it is turned into a ValidationError)."""
+
+
+def _reject_duplicates(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+    seen: set[str] = set()
+    for key, _ in pairs:
+        if key in seen:
+            raise _DuplicateKeyError(f"duplicate key {key!r}")
+        seen.add(key)
+    return dict(pairs)
+
+
+def _reject_constant(name: str) -> NoReturn:
+    # json.loads accepts NaN and Infinity by default; they are not JSON.
+    raise ValueError(f"{name} is not valid JSON")
+
+
+MAX_DEPTH = 100
+"""The deepest nesting of arrays and objects a document may have. The schema is flat; the limit exists so that the
+answer to a hostile document does not depend on the interpreter's recursion limit, which differs between Python
+versions (3.13 and later report a stack overflow, 3.11 a recursion error) and between builds."""
+
+# A string (so brackets inside it are skipped, including escaped quotes) or a bracket.
+_NESTING = re.compile(r'"(?:[^"\\]|\\.)*"|[\[\]{}]', re.DOTALL)
+
+
+def _too_deep(text: str) -> bool:
+    depth = 0
+    for match in _NESTING.finditer(text):
+        token = match.group()
+        if token in "[{":
+            depth += 1
+            if depth > MAX_DEPTH:
+                return True
+        elif token in "]}":
+            depth -= 1
+    return False
+
+
+def _fail(title: str, code: str, message: str) -> NoReturn:
+    """Raise a ``ValidationError``, the one error type callers (for example web frameworks) already handle.
+
+    The input is left out of the error: a document can be megabytes long.
+    """
+    detail = InitErrorDetails(type=PydanticCustomError(code, message), loc=(), input=None)
+    raise ValidationError.from_exception_data(title, [detail])
+
+
+def _read(data: str | bytes | bytearray, title: str) -> str:
+    """Decode ``data`` as UTF-8 without BOM and check it is JSON without repeated keys; return the text.
+
+    RFC 8259 says JSON is UTF-8 and that parsers must not add a BOM. ``json.loads`` would silently accept
+    UTF-16 and UTF-32 and skip a BOM, so a document the Go models reject would pass here; decode strictly instead.
+    """
+    if isinstance(data, str):
+        text = data
+    else:
+        try:
+            text = bytes(data).decode("utf-8")
+        except UnicodeDecodeError as exc:
+            _fail(title, "not_utf8", f"the document is not UTF-8: {exc.reason}")
+    if text.startswith("\ufeff"):
+        _fail(title, "byte_order_mark", "a byte order mark is not allowed")
+    if _too_deep(text):
+        _fail(title, "too_deep", f"the document is nested more than {MAX_DEPTH} levels deep")
+    try:
+        json.loads(
+            text,
+            object_pairs_hook=_reject_duplicates,
+            parse_constant=_reject_constant,
+            # Numbers only matter to the duplicate-key scan: keep their text, so 1e1000 does not become inf and a
+            # very long integer does not hit Python's int-digit limit. The model then rejects them as non-strings.
+            parse_float=str,
+            parse_int=str,
+        )
+    except _DuplicateKeyError as exc:
+        _fail(title, "duplicate_key", str(exc))
+    except RecursionError:
+        # Fallback: the depth check above should make this unreachable.
+        _fail(title, "too_deep", "the document is nested too deeply")
+    except ValueError as exc:  # JSONDecodeError and the NaN/Infinity constants
+        _fail(title, "json_invalid", f"the document is not valid JSON: {exc}")
+    return text
+
+
+def check_json(data: str | bytes | bytearray) -> None:
+    """Check that ``data`` is UTF-8 JSON (no BOM) without a repeated key at any nesting level.
+
+    ``Messwert.model_validate_json`` and ``Zaehlerstand.model_validate_json`` call this themselves. Call it
+    first when you validate in another way (``TypeAdapter(...).validate_json``, a model that contains a
+    ``Messwert``, ``__pydantic_validator__``): those paths go straight to pydantic's parser, which keeps the
+    last of two equal keys without a word. Other problems (wrong types, unknown keys) are left to validation.
+
+    Raises:
+        pydantic.ValidationError: with the error type ``not_utf8``, ``byte_order_mark``, ``json_invalid``,
+            ``duplicate_key`` or ``too_deep``.
+    """
+    _read(data, "check_json")
+
+
+class Model(BaseModel):
+    """Frozen, strict model.
+
+    ``extra="forbid"``: a typo must fail loudly, and a new field means all consumers update together.
+
+    Limits, as with Go's ``json.Unmarshal`` (which a wrapper cannot guard either): only
+    :meth:`model_validate_json` of a model class rejects duplicate keys. Other entry points do not; run
+    :func:`mdq_models.check_json` first. ``model_copy(update=...)`` does not validate (pydantic's default),
+    so build a new instance with ``model_validate`` when the rules matter.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", strict=True)
+
+    @classmethod
+    def model_validate_json(cls, json_data: str | bytes | bytearray, **kwargs: Any) -> Self:
+        """Like :meth:`pydantic.BaseModel.model_validate_json`, but a repeated key is an error.
+
+        Pydantic keeps the last of two equal keys without a word. The contract rejects them (a duplicate is
+        always a bug in the producer), so the document is read once with a hook that raises on a repeated key,
+        and only then handed to pydantic.
+
+        Raises:
+            pydantic.ValidationError: for every problem, including invalid JSON and duplicate keys.
+        """
+        text = _read(json_data, cls.__name__)
+        return super().model_validate_json(text, **kwargs)

mdq_models/_version.py

@@ -0,0 +1 @@
+version = "0.1.0"

mdq_models/enums.py

@@ -0,0 +1,71 @@
+"""The four enumerations of the schema. Values are the JSON strings, lower case and case-sensitive."""
+
+from collections.abc import Callable
+from enum import StrEnum
+from typing import Any, TypeVar
+
+_E = TypeVar("_E", bound=StrEnum)
+
+
+def enum_from_str(enum: type[_E]) -> Callable[[Any], _E]:
+    """Before-validator for an enum field: turn a ``str`` into the member; refuse everything else.
+
+    The models are strict (``strict=True``), and strict mode refuses the plain string ``"wahr"`` for an enum field
+    when validating a Python ``dict`` such as ``json.loads`` output. Converting here keeps that input working,
+    while ``bytes`` and numbers (which lax enum conversion would accept) stay rejected. Matching is exact:
+    ``"Wahr"`` is not ``"wahr"``.
+    """
+
+    def convert(value: Any) -> _E:
+        if not isinstance(value, str):
+            raise ValueError(f"must be a string, not {type(value).__name__}")
+        try:
+            return enum(value)
+        except ValueError:
+            raise ValueError(f"{value!r} is not one of {[member.value for member in enum]}") from None
+
+    return convert
+
+
+class Status(StrEnum):
+    """Quality of a measured value."""
+
+    WAHR = "wahr"
+    """Confirmed value; its herkunft is always ``fremd``."""
+    VORLAEUFIG = "vorlaeufig"
+    """Provisional value, may still be replaced."""
+    ERSATZWERT = "ersatzwert"
+    """Substitute value that was calculated instead of measured."""
+    FEHLEND = "fehlend"
+    """No value; ``value`` and ``herkunft`` are ``None``."""
+
+
+class Herkunft(StrEnum):
+    """Where a value comes from."""
+
+    FREMD = "fremd"
+    """Not formed by the meter data quality agent, e.g. delivered from the source system."""
+    MQA = "mqa"
+    """Formed by the meter data quality agent (MQA, "Messdatenqualitätsagent") in an earlier run."""
+
+
+class Profiltyp(StrEnum):
+    """Load profile type of the market location."""
+
+    HAUSHALT = "haushalt"
+    """Household."""
+    GEWERBE = "gewerbe"
+    """Commerce."""
+    INDUSTRIE = "industrie"
+    """Industry."""
+    UNBEKANNT = "unbekannt"
+    """Unknown."""
+
+
+class Richtung(StrEnum):
+    """Energy direction."""
+
+    BEZUG = "bezug"
+    """Consumption (energy taken from the grid)."""
+    EINSPEISUNG = "einspeisung"
+    """Feed-in (energy delivered to the grid)."""

mdq_models/malo.py

@@ -0,0 +1,66 @@
+"""MaLo ids and the check digit (BDEW algorithm), plus the herkunft/status rule."""
+
+import re
+from typing import Annotated
+
+from pydantic import AfterValidator, StrictStr
+
+from mdq_models.enums import Herkunft, Status
+
+# re.ASCII: without it \d and friends would accept other scripts' digits; fullmatch: `$` would match before a
+# trailing newline. Go uses the same expression.
+_MALO = re.compile(r"[1-9][0-9]{10}", re.ASCII)
+_TEN_DIGITS = re.compile(r"[0-9]{10}", re.ASCII)
+
+
+def malo_check_digit(first_ten: str) -> int:
+    """Check digit for the first ten digits of a MaLo id.
+
+    The digits at odd positions (1st, 3rd, ...) count once, those at even positions twice;
+    the check digit is ``(10 - total % 10) % 10``.
+
+    Raises:
+        ValueError: ``first_ten`` is not exactly ten ASCII digits (a leading 0 is fine here; the id rule in
+            :func:`is_valid_malo_id` is stricter).
+    """
+    if not _TEN_DIGITS.fullmatch(first_ten):
+        raise ValueError(f"{first_ten!r} is not ten ASCII digits")
+    total = sum(int(digit) * (2 if index % 2 else 1) for index, digit in enumerate(first_ten))
+    return (10 - total % 10) % 10
+
+
+def is_valid_malo_id(value: str) -> bool:
+    """Whether ``value`` is 11 ASCII digits, does not start with 0 and ends in the correct check digit."""
+    return _MALO.fullmatch(value) is not None and malo_check_digit(value[:10]) == int(value[10])
+
+
+def _check_malo(value: str) -> str:
+    if not _MALO.fullmatch(value):
+        raise ValueError(f"{value!r} is not 11 ASCII digits without a leading 0")
+    if not is_valid_malo_id(value):
+        raise ValueError(f"{value!r} has a wrong check digit")
+    return value
+
+
+MaLo = Annotated[StrictStr, AfterValidator(_check_malo)]
+"""A market location id. Strict string: a JSON number is rejected rather than converted."""
+
+
+def herkunft_passt_zu_status(status: Status | str, herkunft: Herkunft | str | None) -> bool:
+    """Whether the combination is allowed.
+
+    ``fehlend`` has no herkunft, ``wahr`` needs ``fremd``, ``vorlaeufig`` and ``ersatzwert`` may have either.
+    Only ``None`` means "no herkunft"; the empty string is an unknown value, not "unset" (Go takes a pointer
+    for the same reason). An unknown status or herkunft, including a wrong case (``"Wahr"``), is never allowed:
+    a rule that says "anything else goes" would let a typo through.
+    """
+    try:
+        known_status = Status(status)
+        known_herkunft = None if herkunft is None else Herkunft(herkunft)
+    except ValueError:
+        return False
+    if known_status == Status.FEHLEND:
+        return known_herkunft is None
+    if known_herkunft is None:
+        return False
+    return known_status != Status.WAHR or known_herkunft == Herkunft.FREMD

mdq_models/messwert.py

@@ -0,0 +1,46 @@
+"""One row of the canonical schema: a quarter-hour meter value."""
+
+from typing import Annotated, Literal, Self
+
+from pydantic import BeforeValidator, Field, model_validator
+
+from mdq_models._base import Model
+from mdq_models.enums import Herkunft, Profiltyp, Richtung, Status, enum_from_str
+from mdq_models.malo import MaLo, herkunft_passt_zu_status
+from mdq_models.scalars import CanonicalDecimal, QuarterHourStart
+
+
+class Messwert(Model):
+    """A meter value of one market location for one quarter hour.
+
+    Field order is the key order of the JSON output (the Go models write the same order). All eight keys are
+    required; ``value`` and ``herkunft`` are required but nullable, and always written (``null`` when unset).
+    """
+
+    malo: MaLo = Field(description="Market location id: 11 ASCII digits, no leading 0, valid check digit.")
+    timestamp: QuarterHourStart = Field(
+        description="Start of the quarter hour, UTC (00:00 is the first of a day, 23:45 the last). JSON uses 'Z'."
+    )
+    resolution: Literal["PT15M"] = Field(description="Raster of the series; only PT15M in v1.")
+    value: CanonicalDecimal | None = Field(
+        description="Energy value with at most 6 decimal places, written as a canonical string; None iff fehlend."
+    )
+    status: Annotated[Status, BeforeValidator(enum_from_str(Status))] = Field(description="Quality of the value.")
+    herkunft: Annotated[Herkunft, BeforeValidator(enum_from_str(Herkunft))] | None = Field(
+        description="Origin of the value; None iff fehlend; wahr requires fremd."
+    )
+    profiltyp: Annotated[Profiltyp, BeforeValidator(enum_from_str(Profiltyp))] = Field(
+        description="Load profile type of the market location."
+    )
+    richtung: Annotated[Richtung, BeforeValidator(enum_from_str(Richtung))] = Field(description="Energy direction.")
+
+    @model_validator(mode="after")
+    def _check_missing_and_herkunft(self) -> Self:
+        # `fehlend` means there is nothing to report, so a value or an origin would contradict it;
+        # every other status needs both, or a consumer could not tell a missing value from a zero.
+        missing = self.status == Status.FEHLEND
+        if (self.value is None) != missing:
+            raise ValueError("value must be None if and only if status is fehlend")
+        if not herkunft_passt_zu_status(self.status, self.herkunft):
+            raise ValueError(f"herkunft {self.herkunft!r} does not fit status {self.status.value!r}")
+        return self

mdq_models/polars.py

@@ -0,0 +1,235 @@
+"""Polars table schema of the canonical meter-reading schema (extra ``polars``).
+
+The table form is what Python consumers compute with: seven columns in fixed order, **without** ``resolution``
+(consumers only know the 15-minute raster; the column is added when another raster is allowed). Install it with
+``pip install mdq-models[polars]``. ``mdq_models`` itself never imports polars.
+
+The names below cover everything a consumer needs from one place: column names, dtypes, the enum value tuples, the
+enums and the MaLo helpers (re-exported from :mod:`mdq_models`).
+
+Timestamps are ``Europe/Berlin`` in the table on purpose: consumers do local calendar logic (weekdays, days).
+UTC is only the wire format of :class:`~mdq_models.Messwert`; :func:`to_frame` and :func:`from_frame` convert.
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Iterable
+from decimal import ROUND_HALF_EVEN, Context, Decimal, InvalidOperation, localcontext
+from typing import Any
+
+try:
+    import polars as pl
+except ImportError as exc:
+    raise ImportError(
+        "mdq_models.polars needs the optional dependency polars; install it with: pip install 'mdq-models[polars]'"
+    ) from exc
+
+from mdq_models.enums import Herkunft, Profiltyp, Richtung, Status
+from mdq_models.malo import herkunft_passt_zu_status, is_valid_malo_id, malo_check_digit
+from mdq_models.messwert import Messwert
+from mdq_models.scalars import canonical_decimal
+
+__all__ = [
+    "BERLIN_TZ",
+    "CANONICAL_COLUMNS",
+    "CANONICAL_DTYPES",
+    "COL_HERKUNFT",
+    "COL_MALO",
+    "COL_PROFILTYP",
+    "COL_RICHTUNG",
+    "COL_STATUS",
+    "COL_TIMESTAMP",
+    "COL_VALUE",
+    "HERKUNFT_VALUES",
+    "MALO_ID_LENGTH",
+    "MAX_FLOAT_VALUE",
+    "PROFILTYP_VALUES",
+    "RESOLUTION_MINUTES",
+    "RICHTUNG_VALUES",
+    "STATUS_VALUES",
+    "TIMESTAMP_DTYPE",
+    "Herkunft",
+    "Profiltyp",
+    "Richtung",
+    "Status",
+    "from_frame",
+    "herkunft_passt_zu_status",
+    "is_valid_malo_id",
+    "malo_check_digit",
+    "to_frame",
+]
+
+BERLIN_TZ = "Europe/Berlin"
+"""Time zone of all timestamps in the table."""
+RESOLUTION_MINUTES = 15
+"""Raster of the table in minutes. There is only this raster, which is why the table has no ``resolution`` column."""
+MALO_ID_LENGTH = 11
+"""Length of a MaLo id including the check digit."""
+
+COL_MALO = "malo"
+COL_TIMESTAMP = "timestamp"
+COL_VALUE = "value"
+COL_STATUS = "status"
+COL_HERKUNFT = "herkunft"
+COL_PROFILTYP = "profiltyp"
+COL_RICHTUNG = "richtung"
+
+CANONICAL_COLUMNS: tuple[str, ...] = (
+    COL_MALO,
+    COL_TIMESTAMP,
+    COL_VALUE,
+    COL_STATUS,
+    COL_HERKUNFT,
+    COL_PROFILTYP,
+    COL_RICHTUNG,
+)
+"""Column names in the canonical order. ``resolution`` is left out on purpose (see the module docstring)."""
+
+TIMESTAMP_DTYPE = pl.Datetime("us", BERLIN_TZ)
+"""Dtype of the timestamp column: time zone aware, microseconds, local time of Germany."""
+
+CANONICAL_DTYPES: dict[str, pl.DataType | type[pl.DataType]] = {
+    COL_MALO: pl.String,
+    COL_TIMESTAMP: TIMESTAMP_DTYPE,
+    COL_VALUE: pl.Float64,
+    COL_STATUS: pl.String,
+    COL_HERKUNFT: pl.String,
+    COL_PROFILTYP: pl.String,
+    COL_RICHTUNG: pl.String,
+}
+"""Dtype per column. ``value`` is Float64 (missing = null); everything but the timestamp is a string."""
+
+STATUS_VALUES: tuple[str, ...] = tuple(member.value for member in Status)
+HERKUNFT_VALUES: tuple[str, ...] = tuple(member.value for member in Herkunft)
+PROFILTYP_VALUES: tuple[str, ...] = tuple(member.value for member in Profiltyp)
+RICHTUNG_VALUES: tuple[str, ...] = tuple(member.value for member in Richtung)
+
+MAX_FLOAT_VALUE = Decimal(10**9)
+"""``to_frame`` accepts only ``|value| < MAX_FLOAT_VALUE``. Why: Float64 keeps a decimal exactly only while it has at
+most 15 significant digits; with at most 6 decimals, anything below 10^9 has at most 15."""
+
+_SIX_PLACES = Decimal("0.000001")
+_FLOAT_BOUND = 10.0**9
+
+
+def to_frame(rows: Iterable[Messwert]) -> pl.DataFrame:
+    """Convert ``Messwert`` rows into the table form (seven columns, canonical dtypes).
+
+    The timestamp is converted from UTC to ``Europe/Berlin`` and ``resolution`` is dropped (it is always PT15M).
+
+    Raises:
+        ValueError: if a value has ``|value| >= 10^9``. Float64 could not hold it exactly, and nothing is rounded
+            silently.
+    """
+    rows = list(rows)  # an iterator would be used up by the check below and leave the table empty
+    for row in rows:
+        if row.value is not None and row.value.copy_abs() >= MAX_FLOAT_VALUE:
+            raise ValueError(f"{row.malo} {row.timestamp}: |value| {row.value} is not below 10^9, Float64 is inexact")
+    data: dict[str, Any] = {
+        COL_MALO: [row.malo for row in rows],
+        COL_TIMESTAMP: pl.Series(COL_TIMESTAMP, [row.timestamp for row in rows], dtype=pl.Datetime("us", "UTC")),
+        COL_VALUE: [None if row.value is None else float(row.value) for row in rows],
+        COL_STATUS: [row.status.value for row in rows],
+        COL_HERKUNFT: [None if row.herkunft is None else row.herkunft.value for row in rows],
+        COL_PROFILTYP: [row.profiltyp.value for row in rows],
+        COL_RICHTUNG: [row.richtung.value for row in rows],
+    }
+    frame = pl.DataFrame(data, schema_overrides=CANONICAL_DTYPES, schema=list(CANONICAL_COLUMNS))
+    return frame.with_columns(pl.col(COL_TIMESTAMP).dt.convert_time_zone(BERLIN_TZ))
+
+
+def _float_to_decimal(number: float) -> Decimal:
+    """Convert a float to a canonical ``Decimal``; ``|number| >= 10^9`` (and inf) is refused.
+
+    The bound is the same as in :func:`to_frame`: above it a Float64 cannot be trusted to 6 decimals, so reading it
+    back would invent digits.
+
+    Shortest representation first, not ``Decimal(number)``: that shows the binary expansion
+    (``1234567890123.45`` would become ``1234567890123.449951``). Below 10^9 the shortest representation has at most
+    6 decimals, so the half-even rounding never decides a tie; it only cleans up values from other producers.
+    """
+    if not math.isfinite(number):
+        raise ValueError(f"{number!r} is not a finite number")
+    if abs(number) >= _FLOAT_BOUND:  # a float comparison: no decimal context involved
+        raise ValueError(f"|value| {number!r} is not below 10^9, a Float64 cannot be trusted to 6 decimals")
+    # An explicit context, so the result does not depend on the caller's precision or traps (a precision of 5 would
+    # round 999999999.999999 to 1.0000E+9). 40 digits are plenty: below 10^9 the number has at most 9 + 6 digits.
+    with localcontext(Context(prec=40, rounding=ROUND_HALF_EVEN, traps=[InvalidOperation])):
+        quantized = Decimal(repr(number)).quantize(_SIX_PLACES, rounding=ROUND_HALF_EVEN)
+    return Decimal(canonical_decimal(quantized))
+
+
+def _check_schema(df: pl.DataFrame) -> None:
+    """Strict like the JSON contract: no unknown columns, exactly the canonical dtypes (``Null`` allowed if all null).
+
+    ``cast`` would turn a ``Decimal(20, 6)`` into a float (losing digits), a string ``"1.5"`` into 1.5 and a boolean
+    into 1.0 without a word, so the dtypes are compared instead. The timestamp may be in any time zone, but must be
+    time zone aware with microsecond precision.
+    """
+    missing = [name for name in CANONICAL_COLUMNS if name not in df.columns]
+    if missing:
+        raise ValueError(f"missing columns: {missing}")
+    extra = [name for name in df.columns if name not in CANONICAL_DTYPES]
+    if extra:
+        raise ValueError(
+            f"unexpected columns: {extra}; the table form has exactly {list(CANONICAL_COLUMNS)} "
+            "(no resolution column, it is always PT15M)"
+        )
+    for name, actual in df.schema.items():
+        expected = CANONICAL_DTYPES[name]
+        if actual == pl.Null:
+            continue
+        if name == COL_TIMESTAMP:
+            ok = isinstance(actual, pl.Datetime) and actual.time_zone is not None and actual.time_unit == "us"
+            expected = pl.Datetime("us", "<any time zone>")
+        else:
+            ok = actual == expected
+        if not ok:
+            raise ValueError(f"column {name!r} has dtype {actual}, expected {expected}")
+
+
+def from_frame(df: pl.DataFrame) -> list[Messwert]:
+    """Convert a table in the canonical form back into validated ``Messwert`` rows.
+
+    The frame must be a ``DataFrame`` (not a ``LazyFrame``: ``collect()`` it first), have exactly the seven canonical
+    columns with the canonical dtypes (the timestamp may be in any time zone; it is converted to UTC). Extra columns
+    are rejected, a ``resolution`` column too: the table has no resolution, it is always PT15M and is set here. Why
+    strict: like the JSON contract, which rejects unknown keys, a typo or a new field must fail loudly.
+
+    A float ``value`` is converted through its shortest representation and quantized to 6 decimals (half-even). The
+    bound of :func:`to_frame` applies here too: ``|value| >= 10^9`` raises, because a Float64 that large cannot be
+    trusted to 6 decimals.
+
+    Raises:
+        TypeError: if ``df`` is not a ``DataFrame``.
+        ValueError: if a column is missing, unexpected or has the wrong dtype, the timestamp is naive, or a float is
+            not below 10^9 in absolute value.
+        pydantic.ValidationError: if a row violates the contract (bad MaLo, status/herkunft mismatch, ...).
+    """
+    if not isinstance(df, pl.DataFrame):
+        raise TypeError(f"expected a polars DataFrame, got {type(df).__name__}; collect() a LazyFrame first")
+    _check_schema(df)
+    # Only an all-null (Null dtype) column needs a cast; every other dtype was checked to be the canonical one.
+    timestamp = pl.col(COL_TIMESTAMP)
+    if df.schema[COL_TIMESTAMP] == pl.Null:
+        timestamp = timestamp.cast(pl.Datetime("us", "UTC"))
+    table = df.select(
+        pl.col(COL_MALO).cast(pl.String),
+        timestamp.dt.convert_time_zone("UTC"),
+        pl.col(COL_VALUE).cast(pl.Float64),
+        *(pl.col(name).cast(pl.String) for name in CANONICAL_COLUMNS[3:]),
+    )
+    return [
+        Messwert(
+            malo=row[COL_MALO],
+            timestamp=row[COL_TIMESTAMP],
+            resolution="PT15M",
+            value=None if row[COL_VALUE] is None else _float_to_decimal(row[COL_VALUE]),
+            status=row[COL_STATUS],
+            herkunft=row[COL_HERKUNFT],
+            profiltyp=row[COL_PROFILTYP],
+            richtung=row[COL_RICHTUNG],
+        )
+        for row in table.iter_rows(named=True)
+    ]

mdq_models/scalars.py

@@ -0,0 +1,132 @@
+"""Scalar types with the contract's syntax rules: canonical decimals and UTC timestamps."""
+
+import re
+from datetime import UTC, datetime
+from decimal import Decimal
+from typing import Annotated, Any
+
+from pydantic import PlainSerializer, PlainValidator
+
+MAX_DECIMAL_PLACES = 6
+"""At most this many digits after the point, counted after trailing zeros are removed."""
+
+MAX_INTEGER_DIGITS = 12
+"""At most this many digits before the point (|value| < 10^12). Why: a common storage type for such values is
+a numeric(18,6) database column (12 digits before, 6 after the point), so a larger value would pass validation and
+only fail on write. It also bounds the memory a Decimal built in code like ``1E+999999999`` could use. Go checks the
+same."""
+
+# [0-9], not \d, and fullmatch, not `$`: Python's `$` matches before a trailing newline and \d matches other
+# scripts' digits. Go uses the same expression.
+_CANONICAL_DECIMAL = re.compile(r"-?(0|[1-9][0-9]{0,11})(\.[0-9]{0,5}[1-9])?", re.ASCII)
+_TIMESTAMP = re.compile(r"([0-9]{4})-([0-9]{2})-([0-9]{2})T([0-9]{2}):([0-9]{2}):([0-9]{2})Z", re.ASCII)
+
+MIN_YEAR = 1900
+MAX_YEAR = 9999
+
+
+def _decimal_error(value: object, rule: str) -> ValueError:
+    return ValueError(f"{value!r}: {rule}")
+
+
+def canonical_decimal(value: Decimal) -> str:
+    """Write ``value`` in the shortest canonical form, or raise ``ValueError`` if it is not allowed.
+
+    Not ``Decimal.normalize()``: that rounds to the context precision (28 digits by default) and would silently
+    change long values. The text is built with ``format(value, "f")`` and stripped as a string instead.
+    """
+    if not value.is_finite():  # NaN, sNaN and the infinities have no decimal spelling
+        raise _decimal_error(value, "must be a finite number")
+    _sign, digits, exponent = value.as_tuple()
+    assert isinstance(exponent, int)  # finite
+    # Count places and integer digits without formatting, so 1E-999999999 is rejected before any string is built.
+    # Trailing zero digits are dropped first: Decimal("1.5000000") has 7 places but is 1.5.
+    kept = "".join(map(str, digits)).rstrip("0")
+    if not kept:  # zero in any spelling (0, 0.0, 0E-10, -0)
+        return "0"
+    exponent += len(digits) - len(kept)
+    if -exponent > MAX_DECIMAL_PLACES:
+        raise _decimal_error(value, f"has more than {MAX_DECIMAL_PLACES} decimal places (it is rejected, not rounded)")
+    if len(kept) + exponent > MAX_INTEGER_DIGITS:
+        raise _decimal_error(value, f"has more than {MAX_INTEGER_DIGITS} integer digits")
+    text = format(value, "f")
+    if "." in text:
+        text = text.rstrip("0").removesuffix(".")
+    return text
+
+
+def _to_decimal(value: Any) -> Decimal:
+    """Accept a canonical string (JSON) or a ``Decimal`` (code, normalised); nothing else.
+
+    No ``float`` or ``int``: a float is already inexact, and a JSON number would let ``1.0`` and ``1`` both through.
+    """
+    if isinstance(value, Decimal):
+        return Decimal(canonical_decimal(value))
+    if isinstance(value, str):
+        if not _CANONICAL_DECIMAL.fullmatch(value) or value == "-0":
+            raise _decimal_error(
+                value, "is not a decimal in shortest canonical form with at most 12 integer and 6 decimal digits"
+            )
+        return Decimal(value)
+    raise ValueError(f"{value!r}: must be a canonical decimal string or a Decimal, not {type(value).__name__}")
+
+
+CanonicalDecimal = Annotated[
+    Decimal,
+    PlainValidator(_to_decimal),
+    PlainSerializer(canonical_decimal, return_type=str, when_used="json"),
+]
+"""A decimal number with at most 12 integer and 6 decimal digits.
+JSON carries the shortest canonical string (``"1.5"``)."""
+
+
+def _utc_timestamp(value: Any, *, quarter_hour: bool) -> datetime:
+    if isinstance(value, str):
+        match = _TIMESTAMP.fullmatch(value)
+        if not match:
+            raise ValueError(f"{value!r}: must look like 2026-01-15T10:15:00Z (upper-case T and Z, whole seconds)")
+        try:  # a real calendar parse: rejects 02-30, hour 24, second 60 and 1900-02-29
+            year, month, day, hour, minute, second = (int(part) for part in match.groups())
+            parsed = datetime(year, month, day, hour, minute, second, tzinfo=UTC)
+        except ValueError as exc:
+            raise ValueError(f"{value!r}: {exc}") from exc
+    elif isinstance(value, datetime):
+        if value.tzinfo is None or value.utcoffset() is None:
+            raise ValueError(f"{value!r}: naive datetimes are not allowed, attach a time zone")
+        try:
+            parsed = value.astimezone(UTC)
+        except OverflowError as exc:  # the instant lies outside years 1 to 9999 in UTC
+            raise ValueError(f"{value!r}: outside the years {MIN_YEAR} to {MAX_YEAR} in UTC") from exc
+        # Checked after the conversion, not before: an offset with a sub-second part (timedelta(microseconds=1))
+        # turns a whole-second local time into a UTC time with microseconds, which the JSON form cannot carry,
+        # so the output would name a different instant.
+        if parsed.microsecond:
+            raise ValueError(f"{value!r}: only whole seconds are allowed (in UTC)")
+    else:
+        raise ValueError(f"{value!r}: must be an RFC 3339 string or an aware datetime")
+    if not MIN_YEAR <= parsed.year <= MAX_YEAR:
+        raise ValueError(f"{value!r}: outside the years {MIN_YEAR} to {MAX_YEAR} in UTC")
+    # The raster is checked on the UTC value, so an input with another offset is judged by the instant it means.
+    if quarter_hour and (parsed.minute % 15 or parsed.second):
+        raise ValueError(f"{value!r}: must be the start of a quarter hour (minute 0, 15, 30 or 45, second 0)")
+    return parsed
+
+
+def _format_utc(value: datetime) -> str:
+    """Always ``Z``; never ``+00:00``, so the wire form has exactly one spelling."""
+    return value.strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+QuarterHourStart = Annotated[
+    datetime,
+    PlainValidator(lambda v: _utc_timestamp(v, quarter_hour=True)),
+    PlainSerializer(_format_utc, return_type=str, when_used="json"),
+]
+"""UTC instant on the 15-minute raster: the start of a quarter hour. Aware datetimes are converted to UTC."""
+
+UtcSecond = Annotated[
+    datetime,
+    PlainValidator(lambda v: _utc_timestamp(v, quarter_hour=False)),
+    PlainSerializer(_format_utc, return_type=str, when_used="json"),
+]
+"""UTC instant with whole seconds and no raster. Aware datetimes are converted to UTC."""

mdq_models/zaehlerstand.py

@@ -0,0 +1,17 @@
+"""A meter reading (register value) at a point in time."""
+
+from pydantic import Field
+
+from mdq_models._base import Model
+from mdq_models.malo import MaLo
+from mdq_models.scalars import CanonicalDecimal, UtcSecond
+
+
+class Zaehlerstand(Model):
+    """A meter reading of one market location. Field order is the key order of the JSON output."""
+
+    malo: MaLo = Field(description="Market location id: 11 ASCII digits, no leading 0, valid check digit.")
+    timestamp: UtcSecond = Field(
+        description="Point in time of the reading, UTC, whole seconds, no raster. JSON uses 'Z'."
+    )
+    value: CanonicalDecimal = Field(description="Register value with at most 6 decimal places; never null.")

mdq_models-0.1.0.dist-info/METADATA

@@ -0,0 +1,284 @@
+Metadata-Version: 2.5
+Name: mdq-models
+Version: 0.1.0
+Summary: Hand-written data models of the canonical meter-reading schema (Messwert, Zaehlerstand)
+Project-URL: Changelog, https://github.com/Hochfrequenz/mdq-models/releases
+Project-URL: Homepage, https://github.com/Hochfrequenz/mdq-models
+Project-URL: Repository, https://github.com/Hochfrequenz/mdq-models
+Author-email: Hochfrequenz Unternehmensberatung GmbH <info+github@hochfrequenz.de>
+License: MIT
+License-File: LICENSE
+Keywords: energy,malo,meter reading,pydantic,time series
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.11
+Provides-Extra: polars
+Requires-Dist: polars<3,>=2.0; extra == 'polars'
+Description-Content-Type: text/markdown
+
+# mdq-models
+
+![Go Tests](https://github.com/Hochfrequenz/mdq-models/workflows/Go%20Tests/badge.svg)
+![Go Lint](https://github.com/Hochfrequenz/mdq-models/workflows/Go%20Lint/badge.svg)
+[![Go Reference](https://pkg.go.dev/badge/github.com/hochfrequenz/mdq-models.svg)](https://pkg.go.dev/github.com/hochfrequenz/mdq-models)
+![Python Tests](https://github.com/Hochfrequenz/mdq-models/workflows/Python%20Tests/badge.svg)
+![Python Coverage](https://github.com/Hochfrequenz/mdq-models/workflows/Python%20Coverage/badge.svg)
+![Python Lint](https://github.com/Hochfrequenz/mdq-models/workflows/Python%20Lint/badge.svg)
+![Python Formatting](https://github.com/Hochfrequenz/mdq-models/workflows/Python%20Formatting/badge.svg)
+![Proto](https://github.com/Hochfrequenz/mdq-models/workflows/Proto/badge.svg)
+![Packaging Test](https://github.com/Hochfrequenz/mdq-models/workflows/Packaging%20Test/badge.svg)
+
+Data models of the **canonical meter-reading schema, version 1**: `Messwert` (one value per market
+location and quarter hour) and `Zaehlerstand` (a meter reading, the second input of the schema).
+
+This repository holds
+
+- **Go** types (package `mdqmodels`, module `github.com/hochfrequenz/mdq-models`),
+- **Python** frozen pydantic v2 models (package `mdq_models`) and an optional **Polars** table schema
+  (`mdq_models.polars`, extra `polars`),
+- the shared **fixtures** in [`testdata/`](https://github.com/Hochfrequenz/mdq-models/blob/main/testdata) that define the JSON contract, and
+- the **gRPC contract** in [`proto/mdq/v1`](https://github.com/Hochfrequenz/mdq-models/blob/main/proto/mdq/v1).
+
+Everything is **written by hand**. No code is generated and no generated code is committed: every
+type, validator and (un)marshaller is ordinary, readable code. Field names and enum values are
+German (`malo`, `herkunft`, `vorlaeufig`, ...) and are part of the contract. Both languages parse every
+valid fixture, write it back byte-for-byte as pinned in `testdata/serialized.golden` and reject every
+invalid fixture, so Go and Python agree on the contract by construction.
+
+## The contract in short
+
+| Topic | Rule |
+|---|---|
+| `Messwert` keys | In this order on output: `malo`, `timestamp`, `resolution`, `value`, `status`, `herkunft`, `profiltyp`, `richtung`. All eight are **required**; `value` and `herkunft` are required-but-nullable (always written, `null` when unset). A missing key is rejected, also when its value would be `null`. |
+| `Zaehlerstand` keys | `malo`, `timestamp`, `value`, all required; `value` is never `null`. |
+| Strict reading | **Unknown keys and duplicate keys are rejected** (at every nesting level), so a typo fails loudly and two parsers cannot read different data from the same bytes. Key order matters only for output; parsing accepts any order. The top level must be a JSON object. Invalid UTF-8, a byte order mark and UTF-16 are rejected. |
+| `malo` | `^[1-9][0-9]{10}$` (ASCII digits only) with a valid BDEW check digit. |
+| `timestamp` | RFC 3339, upper-case `T`, offset exactly `Z`, whole seconds, years 1900-9999, ASCII digits only. For `Messwert` it is the **start of the quarter hour** (`00:00` is the first of a day, `23:45` the last; it equals the start of a `[from, to)` interval) and must be on the raster (minute divisible by 15, second 0). For `Zaehlerstand` it is a point in time with any whole second. Built in code, a timestamp in any time zone is accepted and written in UTC; a naive timestamp is rejected. |
+| `resolution` | Only `"PT15M"` in v1. |
+| `value` | A decimal **string** in its shortest canonical form (`"160"`, `"0.022"`, `"-3.5"`), never a JSON number. At most 12 integer digits and at most 6 decimals (counted after stripping trailing zeros). No exponent, no plus sign, no leading zeros, no trailing zeros after the point (`"1.0"` is rejected), no negative zero, no separators. Negative values are allowed. Producers that compute in floating point must round to 6 decimals first: `"0.1234567"` is rejected, not rounded. |
+| `status` | `wahr`, `vorlaeufig`, `ersatzwert`, `fehlend`. Case-sensitive; the retired `gemessen` is rejected. |
+| `herkunft` | `fremd`, `mqa`. `null` **iff** `status` is `fehlend`; `wahr` requires `fremd`. |
+| `value` and `status` | `value` is `null` **iff** `status` is `fehlend`. |
+| `profiltyp` | `haushalt`, `gewerbe`, `industrie`, `unbekannt`. |
+| `richtung` | `bezug`, `einspeisung`. |
+| Decimals built in code | Go `NewDecimal` and Python's `Decimal` input normalise trailing zeros (`"1.5000000"` becomes `"1.5"`) and reject more than 6 decimals, more than 12 integer digits, `NaN` and `Infinity`; they never round. |
+| JSON vs. proto | The `.proto` files are the gRPC contract only. The JSON form is produced by the hand-written models, **never by protojson** (which would write `"STATUS_VORLAEUFIG"` and omit unset `optional` fields instead of writing `null`). |
+
+## Install
+
+```bash
+pip install "mdq-models[polars]"   # the extra is only needed for mdq_models.polars
+go get github.com/hochfrequenz/mdq-models
+```
+
+Python 3.11 or newer; `mdq_models` itself depends only on pydantic and never imports polars.
+
+## Go
+
+Read untrusted bytes with `ParseMesswert` / `ParseZaehlerstand`: every failure is a
+`*ValidationError`. Plain `json.Unmarshal` reports syntax errors as `*json.SyntaxError` and leaves a
+`*Messwert` nil on a top-level `null`.
+
+```go
+raw := []byte(`{"malo":"68283561554","timestamp":"2026-03-29T00:45:00Z","resolution":"PT15M",` +
+	`"value":"1.5","status":"wahr","herkunft":"fremd","profiltyp":"haushalt","richtung":"bezug"}`)
+m, err := mdq.ParseMesswert(raw) // every failure is a *mdq.ValidationError
+if err != nil {
+	log.Fatal(err)
+}
+fmt.Println(m.Malo, m.Timestamp.Format(time.RFC3339), *m.Value, m.Status)
+
+// Build a row in code. NewDecimal drops trailing zeros: "2.50" becomes "2.5".
+value, err := mdq.NewDecimal("2.50")
+if err != nil {
+	log.Fatal(err)
+}
+mqa := mdq.HerkunftMqa
+built := mdq.Messwert{
+	Malo:       "68283561554",
+	Timestamp:  time.Date(2026, 3, 29, 3, 0, 0, 0, time.FixedZone("CEST", 2*3600)), // written as UTC
+	Resolution: mdq.PT15M,
+	Value:      &value,
+	Status:     mdq.StatusErsatzwert,
+	Herkunft:   &mqa,
+	Profiltyp:  mdq.ProfiltypHaushalt,
+	Richtung:   mdq.RichtungBezug,
+}
+out, err := built.MarshalJSON() // validates; an invalid row does not marshal
+if err != nil {
+	log.Fatal(err)
+}
+fmt.Println(string(out))
+
+// Reading is strict: duplicate (and unknown) keys are rejected.
+_, err = mdq.ParseMesswert([]byte(`{"malo":"68283561554","malo":"68283561554"}`))
+var invalid *mdq.ValidationError
+fmt.Println(errors.As(err, &invalid))
+// Output:
+// 68283561554 2026-03-29T00:45:00Z 1.5 wahr
+// {"malo":"68283561554","timestamp":"2026-03-29T01:00:00Z","resolution":"PT15M","value":"2.5","status":"ersatzwert","herkunft":"mqa","profiltyp":"haushalt","richtung":"bezug"}
+// true
+```
+
+(with `import mdq "github.com/hochfrequenz/mdq-models"`). This snippet is the body of
+`ExampleParseMesswert` in [`example_test.go`](https://github.com/Hochfrequenz/mdq-models/blob/main/example_test.go); a test fails if the two drift apart.
+`Zaehlerstand` works the same way. Every type validates itself in `UnmarshalJSON` and refuses to
+marshal when invalid; `Validate()` checks values built in code.
+
+## Python
+
+```python
+from datetime import datetime, timedelta, timezone
+from decimal import Decimal
+
+from pydantic import ValidationError
+
+from mdq_models import Herkunft, Messwert, Profiltyp, Richtung, Status
+
+raw = (
+    '{"malo":"68283561554","timestamp":"2026-03-29T00:45:00Z","resolution":"PT15M",'
+    '"value":"1.5","status":"wahr","herkunft":"fremd","profiltyp":"haushalt","richtung":"bezug"}'
+)
+m = Messwert.model_validate_json(raw)  # rejects duplicate and unknown keys
+print(m.malo, m.timestamp.isoformat(), m.value, m.status.value)  # 68283561554 2026-03-29T00:45:00+00:00 1.5 wahr
+
+# Build a row in code. Trailing zeros are dropped: Decimal("2.50") is written as "2.5".
+built = Messwert(
+    malo="68283561554",
+    timestamp=datetime(2026, 3, 29, 3, 0, tzinfo=timezone(timedelta(hours=2))),  # written as UTC
+    resolution="PT15M",
+    value=Decimal("2.50"),
+    status=Status.ERSATZWERT,
+    herkunft=Herkunft.MQA,
+    profiltyp=Profiltyp.HAUSHALT,
+    richtung=Richtung.BEZUG,
+)
+print(built.model_dump_json())  # the same bytes the Go models write
+
+# Reading is strict: duplicate keys are rejected. Only Messwert.model_validate_json checks this by itself; for
+# TypeAdapter and nested models call check_json(raw) on the raw document first.
+try:
+    Messwert.model_validate_json('{"malo":"68283561554","malo":"68283561554"}')
+except ValidationError:
+    print("rejected")
+```
+
+Plain pydantic keeps the last of two duplicate keys; `mdq_models.check_json(raw)` is the explicit check for
+paths that bypass `model_validate_json`. Use `Messwert.model_validate_json` (or
+`Zaehlerstand.model_validate_json`) for raw JSON. All parse failures are
+`pydantic.ValidationError`.
+
+### Polars
+
+`mdq_models.polars` is the table form Python consumers compute with: seven columns (`malo`,
+`timestamp`, `value`, `status`, `herkunft`, `profiltyp`, `richtung`, **without** `resolution`, which is
+always `PT15M`), `value` as `Float64` and `timestamp` in `Europe/Berlin` (UTC is only the wire format).
+The schema is available as `CANONICAL_COLUMNS`, `CANONICAL_DTYPES` and `TIMESTAMP_DTYPE`.
+
+```python polars
+from mdq_models.polars import from_frame, to_frame
+
+frame = to_frame([m, built])  # seven columns, timestamps in Europe/Berlin
+print(frame["timestamp"][0])  # 2026-03-29 01:45:00+01:00
+assert from_frame(frame) == [m, built]  # lossless for |value| < 10^9
+```
+
+`Float64` keeps a decimal exactly only up to 15 significant digits, so the table form is bounded:
+`to_frame` raises `ValueError` for `|value| >= 10^9` and `from_frame` for a float of that size; neither
+rounds silently. `from_frame` converts each float through its shortest representation and quantizes to
+6 decimals. Both are strict about the table: unknown columns and wrong dtypes raise `ValueError`.
+Importing `mdq_models.polars` without the extra raises an `ImportError` that names it.
+
+The Python snippets above are run by [`unittests/test_readme.py`](https://github.com/Hochfrequenz/mdq-models/blob/main/unittests/test_readme.py), so they
+cannot rot.
+
+## Fixtures
+
+```
+testdata/
+  messwert/{valid,invalid}/        one JSON document per file (DST days, boundaries, every rejected rule, ...)
+  zaehlerstand/{valid,invalid}/
+  invalid_reasons.json             why each invalid fixture is rejected
+  malo_ids.json                    valid and invalid MaLo IDs, check digits
+  herkunft_status.json             all status x herkunft combinations
+  proto_enums.json                 proto enum constants, numbers and JSON values
+  proto_fields.json                proto messages, field labels, types and numbers
+  serialized.golden                the exact bytes both languages write for every valid fixture
+```
+
+[`testdata/README.md`](https://github.com/Hochfrequenz/mdq-models/blob/main/testdata/README.md) documents every file. Consumers in other languages should
+run the same fixtures.
+
+`serialized.golden` pins the output bytes (`<fixture>\t<JSON>` per line), so Go and Python output is
+identical: compact JSON, keys in contract order, timestamps in UTC with `Z`.
+Every invalid fixture has an entry in `testdata/invalid_reasons.json`, so a fixture cannot pass by being
+rejected for the wrong reason.
+
+## How CI keeps Go, Python and proto in step
+
+- **Same fixtures.** `fixtures_test.go` and `unittests/test_fixtures.py` read the same files: every valid
+  fixture must parse and write back the exact bytes of its `serialized.golden` line, every invalid one
+  must be rejected. Go and Python tests run on every pull request (Python 3.11-3.15, with and without the
+  `polars` extra).
+- **Golden file.** Only Go writes it (`go test -run Golden -update .`); Python compares against it.
+- **Proto drift tests.** `proto_contract_test.go` and `unittests/test_proto_contract.py` fail when a proto
+  field, its number or label, or an enum constant differs from `testdata/proto_fields.json` /
+  `proto_enums.json`, or when proto and models disagree on field names or JSON enum values.
+- **`buf`.** The Proto workflow runs `buf build`, `buf lint`, `buf format --diff --exit-code` and, on pull
+  requests, `buf breaking` against the base branch.
+- **Lint, format, types, spelling.** golangci-lint, ruff, mypy (strict) and codespell.
+- **Packaging.** The wheel is built and imported in a fresh environment, with and without the extra.
+
+## Adding a field
+
+A new field must reach every consumer at once, because reading rejects unknown keys. Do it in **one
+pull request**:
+
+1. Add the field to the `.proto` message (next free number; never reuse or renumber) and to
+   `testdata/proto_fields.json`.
+2. Add it to the Go struct (`Validate`, `MarshalJSON`, `UnmarshalJSON`, the key list) and to the Python
+   model, in contract key order.
+3. Add valid and invalid fixtures (each rule one fixture, plus an entry in `invalid_reasons.json`).
+4. Regenerate the golden file with `go test -run Golden -update .`, review the diff and check that
+   `uv run pytest` writes the same bytes.
+5. If it is a table column, extend `mdq_models.polars` and its tests.
+6. Update this README and `testdata/README.md`.
+
+## Versioning
+
+While the major version is 0, minor releases may contain breaking changes (announced in the release
+notes). From 1.0 on the JSON and proto contract of `v1` is frozen: a breaking change needs a new proto
+package version (`mdq.v2`) and, for Go, a new module path `github.com/hochfrequenz/mdq-models/v2`.
+Readers are strict on purpose: unknown and duplicate JSON keys are rejected, so a typo fails
+loudly. The price: **adding a JSON field is a breaking change** for every consumer still on an older
+version, even though `buf breaking` accepts the additive proto change. Consumers update together;
+from 1.0 on, a new field needs a new major version. Releases are tags
+(`vX.Y.Z`); the Python package takes its version from the same tags.
+
+## Development
+
+```bash
+go test ./...                      # Go
+golangci-lint run && golangci-lint fmt --diff
+uv sync --group dev --extra polars # Python (the extra is needed for the Polars module and mypy)
+uv run pytest
+uv run ruff check . && uv run ruff format --check .
+uv run mypy src unittests
+uv run codespell --ignore-words=domain-specific-terms.txt src unittests README.md doc.go
+buf build && buf lint && buf format --diff --exit-code
+```
+
+## License
+
+MIT

mdq_models-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+mdq_models/__init__.py,sha256=xCeSgPUlpAOIqZbxfGRAOSdjwDUXZMLwPyY0mXnoXvM,1345
+mdq_models/_base.py,sha256=8XCTjEAhr6inA_PodPRaWGwEqjW5agLlojD7Kvx9lac,5898
+mdq_models/_version.py,sha256=aOHawL1zuHMfBWKXqwUkXcW96oXLNCY-CXdHDqkz4g4,18
+mdq_models/enums.py,sha256=-342sbtY5jStda9arxQUB6330mhfMooPUYZKbPGZE-4,2296
+mdq_models/malo.py,sha256=_WX7b5oqpuXAkRwm3LpUTxNXqzASpFubjqO0xJzBv44,2730
+mdq_models/messwert.py,sha256=0JBxOfHcIntyDrAbzBlRgiS9NoaKLxL__VWDXzNcMEg,2490
+mdq_models/polars.py,sha256=qep6xEHImWo1wjiRORy4qxfuiKjTJEJ0hGlebuRVV6E,10418
+mdq_models/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mdq_models/scalars.py,sha256=6g5V69OGl90h2Y50vHuVdkgFGRG0wdjRoV9Upwq7r34,6425
+mdq_models/zaehlerstand.py,sha256=8uO2d_MDmLsa_05BmuhJrqCGXa-1G5Q0l_DXOo8WC9Q,699
+mdq_models-0.1.0.dist-info/METADATA,sha256=fhXWDin2mxgmhGLzCO80k5J-eagFth9juUrgSxSiyfQ,15748
+mdq_models-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+mdq_models-0.1.0.dist-info/licenses/LICENSE,sha256=AiXS9N7D_LipXnym-hsOrq7OJZ9sSJi6ycYQNNuvFxE,1095
+mdq_models-0.1.0.dist-info/RECORD,,

mdq_models-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

mdq_models-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hochfrequenz Unternehmensberatung GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.