structwire 0.1.0__py3-none-any.whl

structwire/loaders.py

@@ -0,0 +1,234 @@
+"""Load layouts and catalogs from Python mappings or YAML files."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from .catalog import Catalog
+from .errors import SchemaError
+from .model import Field, Layout
+
+_LAYOUT_KEYS = {"name", "description", "size", "fields"}
+_FIELD_KEYS = {
+    "name",
+    "kind",
+    "type",
+    "length",
+    "offset",
+    "mask",
+    "bitmask",
+    "shift",
+    "bitshift",
+    "scale",
+    "bias",
+    "physical_offset",
+    "values",
+    "bits",
+    "byteorder",
+    "description",
+    "unit",
+}
+_CATALOG_KEYS = {"version", "codecs"}
+
+
+def _intish(value: Any) -> int:
+    if isinstance(value, bool):
+        raise ValueError("boolean is not an integer value here")
+    if isinstance(value, int):
+        return value
+    return int(str(value), 0)
+
+
+def _expect_keys(data: Mapping[str, Any], allowed: set[str], where: str) -> None:
+    if not isinstance(data, Mapping):
+        raise SchemaError(f"{where} must be a mapping")
+    unknown = sorted(str(key) for key in data if key not in allowed)
+    if unknown:
+        raise SchemaError(f"{where}: unknown key(s): {', '.join(unknown)}")
+
+
+def _enum_values(data: Mapping[Any, Any]) -> dict[int, str]:
+    values: dict[int, str] = {}
+    for key, label in data.items():
+        raw = _intish(key)
+        if raw in values:
+            raise SchemaError(f"Duplicate enum value after normalization: {raw}")
+        values[raw] = label
+    return values
+
+
+def _floatish(value: Any) -> float:
+    if isinstance(value, bool):
+        raise ValueError("boolean is not a scale or bias")
+    return float(value)
+
+
+def _alias_value(
+    data: Mapping[str, Any],
+    primary: str,
+    alias: str,
+    *,
+    default: Any = None,
+    where: str,
+) -> Any:
+    has_primary = primary in data
+    has_alias = alias in data
+    if has_primary and has_alias and data[primary] != data[alias]:
+        raise SchemaError(f"{where}: {primary!r} and compatibility alias {alias!r} disagree")
+    if has_primary:
+        return data[primary]
+    if has_alias:
+        return data[alias]
+    return default
+
+
+def layout_from_mapping(data: Mapping[str, Any], *, default_name: str = "") -> Layout:
+    """Build a :class:`Layout` from a plain mapping.
+
+    Accepts the aliases ``type``, ``bitmask``, ``bitshift`` and ``physical_offset``.
+    Unknown keys and conflicting aliases raise ``SchemaError``. Compile the
+    returned layout to validate overlaps and total size.
+    """
+    _expect_keys(data, _LAYOUT_KEYS, "layout")
+    raw_fields = data.get("fields")
+    if not isinstance(raw_fields, list):
+        raise SchemaError("Layout mapping must contain a 'fields' list")
+
+    fields: list[Field] = []
+    for index, raw in enumerate(raw_fields):
+        where = f"fields[{index}]"
+        if not isinstance(raw, Mapping):
+            raise SchemaError(f"{where} must be a mapping")
+        _expect_keys(raw, _FIELD_KEYS, where)
+
+        name = raw.get("name")
+        kind = _alias_value(raw, "kind", "type", where=where)
+        if not isinstance(name, str) or not name.strip():
+            raise SchemaError(f"{where}.name must be a non-empty string")
+        if not isinstance(kind, str) or not kind.strip():
+            raise SchemaError(f"{where}.kind/type must be a non-empty string")
+
+        mask_raw = _alias_value(raw, "mask", "bitmask", where=where)
+        shift_raw = _alias_value(raw, "shift", "bitshift", default=0, where=where)
+        bias_raw = _alias_value(raw, "bias", "physical_offset", default=0.0, where=where)
+        values_raw = raw.get("values", {})
+        bits_raw = raw.get("bits", {})
+        if not isinstance(values_raw, Mapping) or not isinstance(bits_raw, Mapping):
+            raise SchemaError(f"{where}: values/bits must be mappings")
+
+        try:
+            field = Field(
+                name=name,
+                kind=kind,
+                length=_intish(raw["length"]) if raw.get("length") is not None else None,
+                offset=_intish(raw["offset"]) if raw.get("offset") is not None else None,
+                mask=_intish(mask_raw) if mask_raw is not None else None,
+                shift=_intish(shift_raw),
+                scale=_floatish(raw.get("scale", 1.0)),
+                bias=_floatish(bias_raw),
+                values=_enum_values(values_raw),
+                bits={k: _intish(v) for k, v in bits_raw.items()},
+                byteorder=raw.get("byteorder", "big"),
+                description=raw.get("description", ""),
+                unit=raw.get("unit", ""),
+            )
+        except SchemaError:
+            raise
+        except (TypeError, ValueError, OverflowError) as exc:
+            raise SchemaError(f"{where}: invalid field value: {exc}") from exc
+        fields.append(field)
+
+    name = data.get("name", default_name)
+    if not isinstance(name, str):
+        raise SchemaError("Layout name must be a string")
+    name = name.strip()
+    if default_name and name != default_name:
+        raise SchemaError(f"Catalog key {default_name!r} conflicts with layout name {name!r}")
+    size_raw = data.get("size")
+    try:
+        size = _intish(size_raw) if size_raw is not None else None
+    except (TypeError, ValueError) as exc:
+        raise SchemaError(f"layout.size: invalid integer value {size_raw!r}") from exc
+    return Layout(
+        *fields,
+        name=name,
+        description=data.get("description", ""),
+        size=size,
+    )
+
+
+def catalog_from_mapping(data: Mapping[str, Any]) -> Catalog:
+    """Load and compile a catalog from a mapping.
+
+    ``codecs`` maps names to layout definitions. ``version`` defaults to 1,
+    the only supported schema version.
+    """
+    _expect_keys(data, _CATALOG_KEYS, "catalog")
+    version = data.get("version", 1)
+    try:
+        parsed_version = _intish(version)
+    except (TypeError, ValueError) as exc:
+        raise SchemaError("Catalog version must be an integer") from exc
+    if parsed_version != 1:
+        raise SchemaError(f"Unsupported catalog version: {parsed_version}")
+
+    raw_codecs = data.get("codecs")
+    if not isinstance(raw_codecs, Mapping) or not raw_codecs:
+        raise SchemaError("Catalog mapping must contain a non-empty 'codecs' mapping")
+
+    layouts: dict[str, Layout] = {}
+    for raw_name, raw_layout in raw_codecs.items():
+        if not isinstance(raw_name, str) or not raw_name.strip():
+            raise SchemaError("Catalog codec names must be non-empty strings")
+        name = raw_name.strip()
+        if name in layouts:
+            raise SchemaError(f"Duplicate codec name: {name!r}")
+        if not isinstance(raw_layout, Mapping):
+            raise SchemaError(f"codecs.{name} must be a mapping")
+        layouts[name] = layout_from_mapping(raw_layout, default_name=name)
+    return Catalog(layouts)
+
+
+def _yaml_load(path: str | Path) -> Mapping[str, Any]:
+    import yaml
+
+    class UniqueSafeLoader(yaml.SafeLoader):
+        def construct_mapping(self, node: yaml.MappingNode, deep: bool = False) -> dict[Any, Any]:
+            if not isinstance(node, yaml.MappingNode):
+                raise SchemaError("YAML mapping expected")
+            self.flatten_mapping(node)
+            result: dict[Any, Any] = {}
+            for key_node, value_node in node.value:
+                key = self.construct_object(key_node, deep=deep)
+                try:
+                    if key in result:
+                        raise SchemaError(
+                            f"Duplicate YAML key {key!r} at line {key_node.start_mark.line + 1}"
+                        )
+                    result[key] = self.construct_object(value_node, deep=deep)
+                except TypeError as exc:
+                    raise SchemaError("YAML mapping keys must be hashable") from exc
+            return result
+
+    with Path(path).open("r", encoding="utf-8") as handle:
+        try:
+            data = yaml.load(handle, Loader=UniqueSafeLoader)
+        except SchemaError:
+            raise
+        except (yaml.YAMLError, ValueError, KeyError) as exc:
+            raise SchemaError(f"Invalid YAML schema: {exc}") from exc
+    if not isinstance(data, Mapping):
+        raise SchemaError("YAML root must be a mapping")
+    return data
+
+
+def layout_from_yaml(path: str | Path) -> Layout:
+    """Load one layout from YAML."""
+    return layout_from_mapping(_yaml_load(path))
+
+
+def catalog_from_yaml(path: str | Path) -> Catalog:
+    """Load a named codec catalog from YAML."""
+    return catalog_from_mapping(_yaml_load(path))

structwire/model.py

@@ -0,0 +1,330 @@
+"""Immutable public schema model."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from math import isfinite
+from types import MappingProxyType
+from typing import TYPE_CHECKING, Any, Literal, cast
+
+from .errors import SchemaError
+
+if TYPE_CHECKING:
+    from .codec import Codec
+
+_INTEGER_KINDS: dict[str, tuple[int, bool, Literal["big", "little"]]] = {
+    "u8": (1, False, "big"),
+    "i8": (1, True, "big"),
+    "u16be": (2, False, "big"),
+    "u16le": (2, False, "little"),
+    "i16be": (2, True, "big"),
+    "i16le": (2, True, "little"),
+    "u24be": (3, False, "big"),
+    "u24le": (3, False, "little"),
+    "i24be": (3, True, "big"),
+    "i24le": (3, True, "little"),
+    "u32be": (4, False, "big"),
+    "u32le": (4, False, "little"),
+    "i32be": (4, True, "big"),
+    "i32le": (4, True, "little"),
+    "u64be": (8, False, "big"),
+    "u64le": (8, False, "little"),
+    "i64be": (8, True, "big"),
+    "i64le": (8, True, "little"),
+}
+
+_FLOAT_KINDS: dict[str, tuple[int, Literal["big", "little"]]] = {
+    "f32be": (4, "big"),
+    "f32le": (4, "little"),
+    "f64be": (8, "big"),
+    "f64le": (8, "little"),
+}
+
+_ALIASES = {
+    "uint8": "u8",
+    "int8": "i8",
+    "uint16_be": "u16be",
+    "uint16_le": "u16le",
+    "int16_be": "i16be",
+    "int16_le": "i16le",
+    "uint24_be": "u24be",
+    "uint24_le": "u24le",
+    "int24_be": "i24be",
+    "int24_le": "i24le",
+    "uint32_be": "u32be",
+    "uint32_le": "u32le",
+    "int32_be": "i32be",
+    "int32_le": "i32le",
+    "uint64_be": "u64be",
+    "uint64_le": "u64le",
+    "int64_be": "i64be",
+    "int64_le": "i64le",
+    "float32_be": "f32be",
+    "float32_le": "f32le",
+    "float64_be": "f64be",
+    "float64_le": "f64le",
+    "raw": "bytes",
+    "mac_address": "mac",
+}
+
+_SPECIAL_KINDS = {"bcd", "ascii", "bytes", "mac", "enum", "flags", "bool"}
+
+
+def _schema_integer(value: Any, where: str) -> int:
+    if not isinstance(value, int) or isinstance(value, bool):
+        raise SchemaError(f"{where} must be an integer")
+    return value
+
+
+def canonical_kind(kind: str) -> str:
+    """Return a stable kind name, accepting compatibility aliases."""
+    if not isinstance(kind, str):
+        raise SchemaError("Field kind must be a string")
+    key = kind.strip().lower().replace("-", "_")
+    canonical = _ALIASES.get(key, key)
+    if (
+        canonical not in _INTEGER_KINDS
+        and canonical not in _FLOAT_KINDS
+        and canonical not in _SPECIAL_KINDS
+    ):
+        raise SchemaError(f"Unsupported field kind: {kind!r}")
+    return canonical
+
+
+def integer_spec(kind: str) -> tuple[int, bool, Literal["big", "little"]] | None:
+    """Return ``(width, signed, byteorder)`` for an integer kind."""
+    return _INTEGER_KINDS.get(canonical_kind(kind))
+
+
+def float_spec(kind: str) -> tuple[int, Literal["big", "little"]] | None:
+    """Return ``(width, byteorder)`` for a floating-point kind."""
+    return _FLOAT_KINDS.get(canonical_kind(kind))
+
+
+def _logical_bits(width: int, mask: int | None, shift: int) -> int:
+    if mask is None:
+        return width * 8
+    return (mask >> shift).bit_length()
+
+
+@dataclass(frozen=True, slots=True)
+class Field:
+    """One field in a binary layout.
+
+    ``offset`` is a byte offset. When omitted, the field is placed after the
+    furthest byte occupied so far. ``mask`` and ``shift`` address sub-fields
+    within an integer-sized byte span.
+    """
+
+    name: str
+    kind: str
+    length: int | None = None
+    offset: int | None = None
+    mask: int | None = None
+    shift: int = 0
+    scale: float = 1.0
+    bias: float = 0.0
+    values: Mapping[int, str] = field(default_factory=dict)
+    bits: Mapping[str, int] = field(default_factory=dict)
+    byteorder: str = "big"
+    description: str = ""
+    unit: str = ""
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.name, str) or not self.name.strip():
+            raise SchemaError("Field name must be non-empty")
+        kind = canonical_kind(self.kind)
+        object.__setattr__(self, "kind", kind)
+        for attribute in ("offset", "length", "mask"):
+            value = getattr(self, attribute)
+            if value is not None:
+                _schema_integer(value, f"Field {self.name!r}: {attribute}")
+        _schema_integer(self.shift, f"Field {self.name!r}: shift")
+        if self.offset is not None and self.offset < 0:
+            raise SchemaError(f"Field {self.name!r}: offset must be non-negative")
+        if self.length is not None and self.length < 1:
+            raise SchemaError(f"Field {self.name!r}: length must be >= 1")
+        if self.shift < 0:
+            raise SchemaError(f"Field {self.name!r}: shift must be non-negative")
+        if self.shift and self.mask is None:
+            raise SchemaError(f"Field {self.name!r}: shift requires a mask")
+        for attribute in ("scale", "bias"):
+            value = getattr(self, attribute)
+            if isinstance(value, bool) or not isinstance(value, (int, float)):
+                raise SchemaError(f"Field {self.name!r}: {attribute} must be a finite number")
+            try:
+                finite = isfinite(value)
+            except OverflowError:
+                finite = False
+            if not finite:
+                raise SchemaError(f"Field {self.name!r}: scale and bias must be finite")
+        if self.scale == 0:
+            raise SchemaError(f"Field {self.name!r}: scale cannot be zero")
+        if self.byteorder not in ("big", "little"):
+            raise SchemaError(f"Field {self.name!r}: byteorder must be 'big' or 'little'")
+        for attribute in ("description", "unit"):
+            if not isinstance(getattr(self, attribute), str):
+                raise SchemaError(f"Field {self.name!r}: {attribute} must be a string")
+        if not isinstance(self.values, Mapping) or not isinstance(self.bits, Mapping):
+            raise SchemaError(f"Field {self.name!r}: values/bits must be mappings")
+        if self.values and kind != "enum":
+            raise SchemaError(f"Field {self.name!r}: values is only valid for enum fields")
+        if self.bits and kind != "flags":
+            raise SchemaError(f"Field {self.name!r}: bits is only valid for flags fields")
+        if any(not isinstance(label, str) for label in self.values.values()):
+            raise SchemaError(f"Field {self.name!r}: enum labels must be strings")
+        if any(not isinstance(name, str) or not name.strip() for name in self.bits):
+            raise SchemaError(f"Field {self.name!r}: flag names must be non-empty strings")
+
+        values = {
+            _schema_integer(k, f"Field {self.name!r}: enum key"): v for k, v in self.values.items()
+        }
+        bits = {
+            k: _schema_integer(v, f"Field {self.name!r}: flag mask") for k, v in self.bits.items()
+        }
+        if len(set(values.values())) != len(values):
+            raise SchemaError(f"Field {self.name!r}: enum labels must be unique for encoding")
+        object.__setattr__(self, "values", MappingProxyType(values))
+        object.__setattr__(self, "bits", MappingProxyType(bits))
+
+        if kind in {"ascii", "bytes"} and self.length is None:
+            raise SchemaError(f"Field {self.name!r}: {kind} requires length")
+        width = self.width
+        if (kind in _INTEGER_KINDS or kind in _FLOAT_KINDS) and self.length not in (None, width):
+            raise SchemaError(f"Field {self.name!r}: {kind} is exactly {width} byte(s)")
+        if self.mask is not None:
+            if self.mask <= 0 or self.mask.bit_length() > width * 8:
+                raise SchemaError(
+                    f"Field {self.name!r}: mask 0x{self.mask:X} does not fit {width} byte(s)"
+                )
+            shifted = self.mask >> self.shift
+            if shifted == 0 or shifted & (shifted + 1):
+                raise SchemaError(
+                    f"Field {self.name!r}: mask must become contiguous low bits after shift"
+                )
+            if shifted << self.shift != self.mask:
+                raise SchemaError(f"Field {self.name!r}: shift does not match mask")
+
+        if kind == "mac" and self.length not in {None, 6}:
+            raise SchemaError(f"Field {self.name!r}: mac fields are exactly 6 bytes")
+        if self.mask is not None and (
+            kind in _FLOAT_KINDS or kind in {"bcd", "ascii", "bytes", "mac"}
+        ):
+            raise SchemaError(f"Field {self.name!r}: mask is not valid for {kind}")
+        if kind in {"enum", "flags", "bool"} and not 1 <= width <= 8:
+            raise SchemaError(f"Field {self.name!r}: {kind} width must be between 1 and 8 bytes")
+        if kind in {"enum", "flags"}:
+            logical_bits = _logical_bits(width, self.mask, self.shift)
+            logical_max = (1 << logical_bits) - 1
+        if kind == "enum":
+            if not values:
+                raise SchemaError(f"Field {self.name!r}: enum requires values")
+            invalid = [raw for raw in values if raw < 0 or raw > logical_max]
+            if invalid:
+                raise SchemaError(
+                    f"Field {self.name!r}: enum value does not fit {logical_bits} bit(s)"
+                )
+        if kind == "flags":
+            if not bits:
+                raise SchemaError(f"Field {self.name!r}: flags requires bits")
+            invalid = [mask for mask in bits.values() if mask <= 0 or mask > logical_max]
+            if invalid:
+                raise SchemaError(
+                    f"Field {self.name!r}: flag mask 0x{invalid[0]:X} does not fit "
+                    f"{logical_bits} bit(s)"
+                )
+        if kind in {"ascii", "bytes", "mac", "flags", "enum", "bool"} and (
+            self.scale != 1.0 or self.bias != 0.0
+        ):
+            raise SchemaError(f"Field {self.name!r}: scale/bias is not valid for {kind}")
+
+    @property
+    def width(self) -> int:
+        """Field width in bytes."""
+        int_spec = _INTEGER_KINDS.get(self.kind)
+        if int_spec is not None:
+            return int_spec[0]
+        flt_spec = _FLOAT_KINDS.get(self.kind)
+        if flt_spec is not None:
+            return flt_spec[0]
+        if self.kind == "mac":
+            return 6
+        if self.kind == "bcd":
+            return self.length or 1
+        if self.kind in {"enum", "flags", "bool"}:
+            return self.length or 1
+        assert self.length is not None
+        return self.length
+
+    @property
+    def effective_byteorder(self) -> Literal["big", "little"]:
+        """Kind-defined numeric order, otherwise the supplied byteorder.
+
+        BCD, ASCII and bytes retain wire order regardless of this parameter.
+        """
+        spec = _INTEGER_KINDS.get(self.kind)
+        if spec is not None:
+            return spec[2]
+        flt = _FLOAT_KINDS.get(self.kind)
+        if flt is not None:
+            return flt[1]
+        return cast(Literal["big", "little"], self.byteorder)
+
+    @property
+    def signed(self) -> bool:
+        spec = _INTEGER_KINDS.get(self.kind)
+        return bool(spec and spec[1])
+
+
+@dataclass(frozen=True, slots=True)
+class Layout:
+    """Immutable declarative binary layout."""
+
+    fields: tuple[Field, ...]
+    name: str = ""
+    description: str = ""
+    size: int | None = None
+
+    def __init__(
+        self,
+        *fields: Field,
+        name: str = "",
+        description: str = "",
+        size: int | None = None,
+    ) -> None:
+        if size is not None:
+            _schema_integer(size, "Layout size")
+        if not isinstance(name, str):
+            raise SchemaError("Layout name must be a string")
+        if not isinstance(description, str):
+            raise SchemaError("Layout description must be a string")
+        if any(not isinstance(item, Field) for item in fields):
+            raise SchemaError("Layout fields must be Field objects")
+        object.__setattr__(self, "fields", tuple(fields))
+        object.__setattr__(self, "name", name)
+        object.__setattr__(self, "description", description)
+        object.__setattr__(self, "size", size)
+        if size is not None and size < 0:
+            raise SchemaError("Layout size must be non-negative")
+        if len({item.name for item in fields}) != len(fields):
+            raise SchemaError("Field names must be unique")
+
+    def compile(self) -> Codec:
+        """Compile this layout into a reusable codec."""
+        from .codec import Codec
+
+        return Codec(self)
+
+    def encode(self, values: Mapping[str, Any], *, require_all: bool = True) -> bytes:
+        """Compile and encode in one call."""
+        return self.compile().encode(values, require_all=require_all)
+
+    def decode(
+        self,
+        payload: bytes | bytearray | memoryview,
+        *,
+        strict: bool = True,
+    ) -> dict[str, Any]:
+        """Compile and decode in one call."""
+        return self.compile().decode(payload, strict=strict)