lvxml 0.2.1__py3-none-any.whl

lvxml/_encode.py

@@ -0,0 +1,158 @@
+"""Render native Python values as LabVIEW Unflatten-From-XML text, driven by a schema."""
+
+from __future__ import annotations
+
+from ._dump import dump
+from ._errors import LVXMLError
+from ._node import Node
+from ._numbers import check_range, format_complex, format_float
+from ._schema import (
+    COMPLEX_TAGS,
+    FLOAT_TAGS,
+    INT_RANGES,
+    TEXT_TAGS,
+    Array,
+    Cluster,
+    LVEnum,
+    Schema,
+    Value,
+)
+
+
+def to_lv_xml(value: Value, schema: Schema, name: str = "") -> str:
+    """Render `value` as LabVIEW flattened XML matching `schema`, indented for reading."""
+    return dump(to_node(value, schema, name), newline="\n", indent="  ")
+
+
+def to_node(value: Value, schema: Schema, name: str = "") -> Node:
+    """Build the typed `Node` for `value` under `schema`, checking every type and range."""
+    try:
+        return _encode(value, schema, name, name or "value")
+    except RecursionError:
+        raise LVXMLError("the value is nested too deeply to write") from None
+
+
+def _encode(value: Value, schema: Schema, name: str, path: str) -> Node:
+    if isinstance(schema, Array):
+        return _encode_array(value, schema, name, path)
+    if isinstance(schema, Cluster):
+        return _encode_cluster(value, schema, name, path)
+    if not isinstance(schema, (str, LVEnum)):
+        kind = type(schema).__name__
+        raise TypeError(f"a schema is a tag string, Array, Cluster or LVEnum, not {kind}")
+    if isinstance(schema, LVEnum):
+        return Node(
+            schema.tag, name, val=str(_enum_index(value, schema, path)), choices=schema.choices
+        )
+    return Node(schema, name, val=_scalar_text(value, schema, path))
+
+
+def _kind(value: Value) -> str:
+    return type(value).__name__
+
+
+def _scalar_text(value: Value, tag: str, path: str) -> str:
+    try:
+        if tag in FLOAT_TAGS:
+            if isinstance(value, bool) or not isinstance(value, (int, float)):
+                raise LVXMLError(f"{tag} expects a number, got {_kind(value)}", path)
+            return format_float(float(value), tag)
+        if tag in COMPLEX_TAGS:
+            if isinstance(value, bool) or not isinstance(value, (int, float, complex)):
+                raise LVXMLError(f"{tag} expects a number, got {_kind(value)}", path)
+            return format_complex(complex(value), tag)
+        if tag in INT_RANGES:
+            if isinstance(value, bool) or not isinstance(value, int):
+                raise LVXMLError(f"{tag} expects an int, got {_kind(value)}", path)
+            check_range(value, tag)
+            return str(value)
+    except (ValueError, OverflowError) as exc:
+        if isinstance(exc, LVXMLError):
+            raise
+        raise LVXMLError(str(exc), path) from exc
+    if tag == "Boolean":
+        if not isinstance(value, bool):
+            raise LVXMLError(f"Boolean expects a bool, got {_kind(value)}", path)
+        return "1" if value else "0"
+    if tag in TEXT_TAGS:
+        if not isinstance(value, str):
+            raise LVXMLError(f"{tag} expects a str, got {_kind(value)}", path)
+        return value
+    raise LVXMLError(f"unknown or unsupported LabVIEW type tag {tag!r}", path)
+
+
+def _enum_index(value: Value, schema: LVEnum, path: str) -> int:
+    if isinstance(value, str):
+        if value not in schema.choices:
+            raise LVXMLError(f"{value!r} is not one of the choices {list(schema.choices)}", path)
+        return schema.choices.index(value)
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise LVXMLError(f"{schema.tag} expects a choice label or index, got {_kind(value)}", path)
+    if not 0 <= value < len(schema.choices):
+        raise LVXMLError(f"enum index {value} is outside 0..{len(schema.choices) - 1}", path)
+    return value
+
+
+def _encode_cluster(value: Value, schema: Cluster, name: str, path: str) -> Node:
+    if not isinstance(value, dict):
+        raise LVXMLError(f"Cluster expects a dict, got {_kind(value)}", path)
+    extra = set(value) - set(schema.fields)
+    if extra:
+        raise LVXMLError(f"cluster value has unknown fields {sorted(extra)}", path)
+    items: list[Node] = []
+    for field_name, field_schema in schema.fields.items():
+        if field_name not in value:
+            raise LVXMLError(f"missing cluster field {field_name!r}", path)
+        items.append(_encode(value[field_name], field_schema, field_name, f"{path}.{field_name}"))
+    return Node("Cluster", name, num_elts=len(items), items=tuple(items))
+
+
+def _encode_array(value: Value, schema: Array, name: str, path: str) -> Node:
+    dims: list[int] = []
+    flat = _flatten(value, schema.ndim, dims, path)
+    # An empty array still carries one default element, so the element type is visible.
+    if not flat:
+        flat = [_default(schema.element)]
+    items = tuple(_encode(item, schema.element, "", f"{path}[{i}]") for i, item in enumerate(flat))
+    return Node("Array", name, dims=tuple(dims), items=items)
+
+
+def _flatten(value: Value, ndim: int, dims: list[int], path: str) -> list[Value]:
+    """Flatten a nested list row-major, recording its shape and rejecting ragged rows."""
+    if not isinstance(value, list):
+        raise LVXMLError(f"Array expects a list, got {_kind(value)}", path)
+    dims.append(len(value))
+    if ndim == 1:
+        return list(value)
+    if not value:
+        dims.extend([0] * (ndim - 1))
+        return []
+    rows: list[list[Value]] = []
+    for index, row in enumerate(value):
+        row_dims: list[int] = []
+        rows.append(_flatten(row, ndim - 1, row_dims, f"{path}[{index}]"))
+        if index == 0:
+            dims.extend(row_dims)
+        elif row_dims != dims[len(dims) - len(row_dims) :]:
+            raise LVXMLError(f"ragged array: row {index} has shape {row_dims}", path)
+    return [item for row in rows for item in row]
+
+
+def _default(schema: Schema) -> Value:
+    if isinstance(schema, Array):
+        return []
+    if isinstance(schema, Cluster):
+        return {name: _default(sub) for name, sub in schema.fields.items()}
+    if isinstance(schema, LVEnum):
+        return schema.choices[0]
+    if schema in FLOAT_TAGS:
+        return 0.0
+    if schema in COMPLEX_TAGS:
+        return 0j
+    if schema in INT_RANGES:
+        return 0
+    if schema == "Boolean":
+        return False
+    if schema in TEXT_TAGS:
+        return ""
+    raise LVXMLError(f"unknown or unsupported LabVIEW type tag {schema!r}")

lvxml/_errors.py

@@ -0,0 +1,16 @@
+"""The single error type raised for malformed or unsupported LabVIEW XML."""
+
+from __future__ import annotations
+
+
+class LVXMLError(ValueError):
+    """Raised when LabVIEW XML is malformed or falls outside the covered subset.
+
+    `path` locates the offending element, for example ``LVData/Cluster[pt]/DBL[x]``, and
+    is empty when the problem has no single location.
+    """
+
+    def __init__(self, message: str, path: str = "") -> None:
+        super().__init__(f"{path}: {message}" if path else message)
+        self.message = message
+        self.path = path

lvxml/_load.py

@@ -0,0 +1,59 @@
+"""Turn text or bytes into an XML element tree, keeping what a plain parse would lose."""
+
+from __future__ import annotations
+
+import re
+from xml.etree import ElementTree as ET
+
+from ._errors import LVXMLError
+
+_MARKUP = re.compile(r"(<[^>]*>)")
+_DECLARATION = re.compile(r"\A?\s*<\?xml\b[^>]*\?>")
+_ENCODING = re.compile(rb"\A\s*<\?xml\b[^>]*\bencoding\s*=\s*[\"']([A-Za-z0-9._-]+)[\"']")
+
+
+def decode(data: str | bytes) -> str:
+    """Return `data` as text, decoding bytes by their XML declaration (default UTF-8)."""
+    if isinstance(data, str):
+        return data
+    if not isinstance(data, (bytes, bytearray)):
+        raise TypeError(f"expected str or bytes, got {type(data).__name__}")
+    raw = bytes(data)
+    if raw.startswith(b"\xef\xbb\xbf"):
+        raw, declared = raw[3:], "utf-8"
+    else:
+        match = _ENCODING.match(raw)
+        declared = match.group(1).decode("ascii") if match else "utf-8"
+    try:
+        return raw.decode(declared)
+    except (LookupError, UnicodeDecodeError) as exc:
+        raise LVXMLError(f"cannot decode the input as {declared}: {exc}") from exc
+
+
+def load(text: str) -> ET.Element:
+    """Parse `text` into an element tree, refusing what LabVIEW XML never contains."""
+    if "<!DOCTYPE" in text:
+        raise LVXMLError("a DOCTYPE is not part of LabVIEW XML")
+    if "<![CDATA[" in text:
+        raise LVXMLError("CDATA sections are not supported; LabVIEW escapes text instead")
+    # The text is already decoded, so an encoding named in the declaration must not apply.
+    body = _DECLARATION.sub("", text, count=1)
+    try:
+        return ET.fromstring(_keep_carriage_returns(body))
+    except ET.ParseError as exc:
+        raise LVXMLError(f"invalid XML: {exc}") from exc
+
+
+def _keep_carriage_returns(text: str) -> str:
+    """Encode CRs inside the root element so the parser does not fold them into LFs."""
+    if "\r" not in text:
+        return text
+    parts = _MARKUP.split(text)
+    tags = [i for i in range(1, len(parts), 2) if not parts[i].startswith(("<?", "<!"))]
+    if not tags:
+        return text
+    first, last = tags[0], tags[-1]
+    return "".join(
+        part.replace("\r", "&#13;") if first < i < last and i % 2 == 0 else part
+        for i, part in enumerate(parts)
+    )

lvxml/_node.py

@@ -0,0 +1,85 @@
+"""The lossless typed tree: one `Node` per LabVIEW element, wrapped in a `Document`."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# The namespace LabVIEW's XML file writer puts on <LVData>.
+LVDATA_NAMESPACE = "http://www.ni.com/LVData"
+
+
+@dataclass(frozen=True)
+class Node:
+    """One LabVIEW value element, keeping every piece of the XML.
+
+    `val` holds the raw ``<Val>`` text exactly as written (``None`` for containers),
+    `choices` an enum's ``<Choice>`` labels, `dims` an array's ``<Dimsize>`` values,
+    `num_elts` a cluster's ``<NumElts>``, and `items` the child value elements of an
+    array, cluster, variant, timestamp or waveform. `extra` keeps a ``Refnum``'s optional
+    ``RefKind``, ``RefType``, ``ActiveXType.GUID``, ``ActiveXType.Name`` and
+    ``DotNetType.Name`` fields in document order. A ``Version`` header inside
+    ``<LVData>`` is a node with tag ``"Version"`` and its text in `val`.
+    """
+
+    tag: str
+    name: str = ""
+    val: str | None = None
+    choices: tuple[str, ...] = ()
+    dims: tuple[int, ...] = ()
+    num_elts: int | None = None
+    items: tuple[Node, ...] = ()
+    extra: tuple[tuple[str, str], ...] = ()
+
+    def to_dict(self) -> dict[str, object]:
+        """Return a JSON-ready dict that `Node.from_dict` turns back into this node."""
+        from ._treejson import node_to_dict
+
+        return node_to_dict(self)
+
+    @staticmethod
+    def from_dict(data: object) -> Node:
+        """Build a node from the dict shape `to_dict` produces, checking every field."""
+        from ._treejson import node_from_dict
+
+        return node_from_dict(data, "")
+
+
+@dataclass(frozen=True)
+class Document:
+    """A parsed LabVIEW XML document.
+
+    `wrapped` is true for the ``<LVData>`` file form, whose `items` may include
+    ``Version`` nodes; otherwise the document is the bare output of Flatten To XML and
+    `items` holds exactly one node. `namespace` is the default XML namespace of the root
+    element, or ``None`` when it has none.
+    """
+
+    items: tuple[Node, ...]
+    wrapped: bool = True
+    namespace: str | None = LVDATA_NAMESPACE
+
+    @property
+    def version(self) -> str | None:
+        """The text of the first ``<Version>`` header, if there is one."""
+        for node in self.items:
+            if node.tag == "Version":
+                return node.val
+        return None
+
+    @property
+    def values(self) -> tuple[Node, ...]:
+        """The value nodes, leaving out ``Version`` headers."""
+        return tuple(node for node in self.items if node.tag != "Version")
+
+    def to_dict(self) -> dict[str, object]:
+        """Return a JSON-ready dict that `Document.from_dict` turns back into this one."""
+        from ._treejson import document_to_dict
+
+        return document_to_dict(self)
+
+    @staticmethod
+    def from_dict(data: object) -> Document:
+        """Build a document from the dict shape `to_dict` produces, checking every field."""
+        from ._treejson import document_from_dict
+
+        return document_from_dict(data)

lvxml/_numbers.py

@@ -0,0 +1,83 @@
+"""Scalar text in <Val>: parse it strictly and format it the way LabVIEW reads it back."""
+
+from __future__ import annotations
+
+import math
+import re
+import struct
+
+from ._schema import ENUM_RANGES, INT_RANGES
+
+# A period is the only decimal separator: LabVIEW does not localize this format.
+_FLOAT = re.compile(r"[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?")
+_NON_FINITE = {"nan": math.nan, "inf": math.inf, "+inf": math.inf, "-inf": -math.inf}
+_NON_FINITE.update({"infinity": math.inf, "+infinity": math.inf, "-infinity": -math.inf})
+_INT = re.compile(r"[+-]?\d+")
+# LabVIEW's run-time library formats a complex value as "<re> +<im> i".
+_COMPLEX = re.compile(r"\s*(\S+)\s*\+\s*(\S+)\s*i\s*")
+_TRUE = frozenset({"1", "true"})
+_FALSE = frozenset({"0", "false"})
+
+
+def parse_float(text: str) -> float:
+    """Parse a float with a period decimal point; NaN, Inf and Infinity in any case."""
+    stripped = text.strip()
+    if stripped.lower() in _NON_FINITE:
+        return _NON_FINITE[stripped.lower()]
+    if not stripped.isascii() or not _FLOAT.fullmatch(stripped):
+        hint = " (the decimal separator is always a period)" if "," in stripped else ""
+        raise ValueError(f"invalid float value {text!r}{hint}")
+    return float(stripped)
+
+
+def parse_complex(text: str) -> complex:
+    """Parse LabVIEW's ``re +im i`` complex text."""
+    match = _COMPLEX.fullmatch(text)
+    if match is None:
+        raise ValueError(f"invalid complex value {text!r}, expected '<re> +<im> i'")
+    return complex(parse_float(match.group(1)), parse_float(match.group(2)))
+
+
+def parse_int(text: str, tag: str) -> int:
+    """Parse a decimal integer and check it fits `tag`'s range (an integer or enum tag)."""
+    stripped = text.strip()
+    if not stripped.isascii() or not _INT.fullmatch(stripped):
+        raise ValueError(f"invalid integer value {text!r}")
+    value = int(stripped, 10)
+    check_range(value, tag)
+    return value
+
+
+def check_range(value: int, tag: str) -> None:
+    low, high = INT_RANGES[tag] if tag in INT_RANGES else ENUM_RANGES[tag]
+    if not low <= value <= high:
+        raise ValueError(f"{value} is out of range for {tag} ({low}..{high})")
+
+
+def parse_bool(text: str) -> bool:
+    """Parse a Boolean ``<Val>``: 1 or 0, also accepting true and false."""
+    lowered = text.strip().lower()
+    if lowered in _TRUE:
+        return True
+    if lowered in _FALSE:
+        return False
+    raise ValueError(f"invalid boolean value {text!r}")
+
+
+def format_float(value: float, tag: str) -> str:
+    """Format a float with a period decimal point; non-finite as NaN, Inf or -Inf."""
+    if math.isnan(value):
+        return "NaN"
+    if math.isinf(value):
+        return "Inf" if value > 0 else "-Inf"
+    if tag in {"SGL", "CSG"}:
+        try:
+            struct.pack("<f", value)
+        except OverflowError:
+            raise ValueError(f"{value!r} does not fit single precision {tag}") from None
+    return repr(float(value))
+
+
+def format_complex(value: complex, tag: str) -> str:
+    """Format a complex value as LabVIEW's ``re +im i``."""
+    return f"{format_float(value.real, tag)} +{format_float(value.imag, tag)} i"

lvxml/_parse.py

@@ -0,0 +1,168 @@
+"""Read LabVIEW XML text into the typed tree, enforcing the shape LVXMLSchema.xsd defines."""
+
+from __future__ import annotations
+
+from xml.etree import ElementTree as ET
+
+from ._errors import LVXMLError
+from ._load import decode, load
+from ._node import Document, Node
+from ._schema import (
+    ARRAY_ITEM_TAGS,
+    CLUSTERED_TAGS,
+    ENUM_RANGES,
+    SIMPLE_TAGS,
+    VALUE_TAGS,
+)
+
+# Deeper nesting than this is refused rather than exhausting the interpreter's stack.
+MAX_DEPTH = 100
+
+
+def parse(text: str | bytes) -> Document:
+    """Parse LabVIEW Flatten-To-XML, bare or inside ``<LVData>``, into a `Document`.
+
+    Bytes are decoded by the encoding their XML declaration names, or as UTF-8.
+    """
+    root = load(decode(text))
+    tag, namespace = _split(root.tag)
+    for element in root.iter():
+        if _split(element.tag)[1] != namespace:
+            where = _split(element.tag)[0]
+            raise LVXMLError(f"<{where}> is not in the root element's namespace {namespace!r}")
+    _no_attributes(root, tag)
+    if tag != "LVData":
+        return Document((_node(root, VALUE_TAGS, "", 1),), wrapped=False, namespace=namespace)
+    _no_text(root.text, "LVData")
+    items: list[Node] = []
+    for child in root:
+        _no_text(child.tail, "LVData")
+        if _split(child.tag)[0] == "Version":
+            items.append(Node("Version", val=_leaf(child, "LVData/Version")))
+        else:
+            items.append(_node(child, VALUE_TAGS, "LVData", 1))
+    return Document(tuple(items), wrapped=True, namespace=namespace)
+
+
+def _split(tag: str) -> tuple[str, str | None]:
+    if tag.startswith("{"):
+        namespace, local = tag[1:].split("}", 1)
+        return local, namespace
+    return tag, None
+
+
+def _no_attributes(element: ET.Element, path: str) -> None:
+    if element.attrib:
+        raise LVXMLError(f"unexpected attributes {sorted(element.attrib)}", path)
+
+
+def _no_text(text: str | None, path: str) -> None:
+    if text is not None and text.strip():
+        raise LVXMLError(f"unexpected text {text.strip()[:40]!r}", path)
+
+
+def _leaf(element: ET.Element, path: str) -> str:
+    _no_attributes(element, path)
+    if len(element):
+        raise LVXMLError("expected text only, found child elements", path)
+    return element.text or ""
+
+
+class _Children:
+    """Walk an element's children in order, as the schema's xsd:sequence requires."""
+
+    def __init__(self, element: ET.Element, path: str, depth: int = 0) -> None:
+        _no_text(element.text, path)
+        self.depth = depth
+        self.kids = list(element)
+        for kid in self.kids:
+            _no_text(kid.tail, path)
+        self.pos = 0
+        self.path = path
+
+    def peek(self) -> str | None:
+        return _split(self.kids[self.pos].tag)[0] if self.pos < len(self.kids) else None
+
+    def take(self, tag: str) -> str:
+        if self.peek() != tag:
+            found = f"<{self.peek()}>" if self.peek() else "the end of the element"
+            raise LVXMLError(f"expected <{tag}>, found {found}", self.path)
+        self.pos += 1
+        return _leaf(self.kids[self.pos - 1], f"{self.path}/{tag}")
+
+    def take_all(self, tag: str) -> list[str]:
+        values = [self.take(tag)]
+        while self.peek() == tag:
+            values.append(self.take(tag))
+        return values
+
+    def rest(self, allowed: frozenset[str]) -> tuple[Node, ...]:
+        nodes = tuple(_node(k, allowed, self.path, self.depth + 1) for k in self.kids[self.pos :])
+        self.pos = len(self.kids)
+        return nodes
+
+    def end(self) -> None:
+        if self.pos < len(self.kids):
+            raise LVXMLError(f"unexpected <{self.peek()}>", self.path)
+
+
+def _node(element: ET.Element, allowed: frozenset[str], parent: str, depth: int) -> Node:
+    tag = _split(element.tag)[0]
+    here = f"{parent}/{tag}" if parent else tag
+    if depth > MAX_DEPTH:
+        raise LVXMLError(f"nesting deeper than {MAX_DEPTH} levels is not supported", here)
+    if tag not in allowed:
+        where = f"inside <{parent.rsplit('/', 1)[-1]}>" if parent else "as a root element"
+        raise LVXMLError(f"<{tag}> is not allowed {where} by LVXMLSchema.xsd", here)
+    _no_attributes(element, here)
+    kids = _Children(element, here, depth)
+    name = kids.take("Name")
+    kids.path = f"{here}[{name}]" if name else here
+    node = _body(tag, name, kids)
+    kids.end()
+    return node
+
+
+def _body(tag: str, name: str, kids: _Children) -> Node:
+    if tag in SIMPLE_TAGS:
+        return Node(tag, name, val=kids.take("Val"))
+    if tag in ENUM_RANGES:
+        choices = tuple(kids.take_all("Choice"))
+        return Node(tag, name, val=kids.take("Val"), choices=choices)
+    if tag == "Refnum":
+        return Node(tag, name, val=kids.take("Val"), extra=_refnum_extra(kids))
+    if tag == "Array":
+        dims = tuple(_count(text, f"{kids.path}/Dimsize") for text in kids.take_all("Dimsize"))
+        return Node(tag, name, dims=dims, items=kids.rest(ARRAY_ITEM_TAGS))
+    if tag == "Cluster":
+        num_elts = _count(kids.take("NumElts"), f"{kids.path}/NumElts")
+        return Node(tag, name, num_elts=num_elts, items=kids.rest(VALUE_TAGS))
+    if tag in CLUSTERED_TAGS:
+        return Node(tag, name, items=kids.rest(frozenset({"Cluster"})))
+    return Node(tag, name, items=kids.rest(VALUE_TAGS))  # LvVariant
+
+
+def _refnum_extra(kids: _Children) -> tuple[tuple[str, str], ...]:
+    extra: list[tuple[str, str]] = []
+    if kids.peek() == "RefKind":
+        extra.append(("RefKind", kids.take("RefKind")))
+        if kids.peek() == "RefType":
+            extra.append(("RefType", kids.take("RefType")))
+    for group, fields in (("ActiveXType", ("GUID", "Name")), ("DotNetType", ("Name",))):
+        if kids.peek() != group:
+            continue
+        sub = _Children(kids.kids[kids.pos], f"{kids.path}/{group}")
+        _no_attributes(kids.kids[kids.pos], sub.path)
+        kids.pos += 1
+        for index, field in enumerate(fields):
+            if index == 0 or sub.peek() == field:
+                extra.append((f"{group}.{field}", sub.take(field)))
+        sub.end()
+    return tuple(extra)
+
+
+def _count(text: str, path: str) -> int:
+    stripped = text.strip()
+    if not stripped.isdigit() or not stripped.isascii():
+        raise LVXMLError(f"expected a non-negative integer, got {text!r}", path)
+    return int(stripped)

lvxml/_schema.py

@@ -0,0 +1,114 @@
+"""LabVIEW type tags from LVXMLSchema.xsd and the schema that pins Python values to them."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+FLOAT_TAGS: frozenset[str] = frozenset({"SGL", "DBL", "EXT"})
+COMPLEX_TAGS: frozenset[str] = frozenset({"CSG", "CDB", "CXT"})
+
+INT_RANGES: dict[str, tuple[int, int]] = {
+    "I8": (-(2**7), 2**7 - 1),
+    "I16": (-(2**15), 2**15 - 1),
+    "I32": (-(2**31), 2**31 - 1),
+    "I64": (-(2**63), 2**63 - 1),
+    "U8": (0, 2**8 - 1),
+    "U16": (0, 2**16 - 1),
+    "U32": (0, 2**32 - 1),
+    "U64": (0, 2**64 - 1),
+}
+
+# Enum tags carry their value as an index into the <Choice> list, sized like U8/U16/U32.
+ENUM_RANGES: dict[str, tuple[int, int]] = {
+    "EB": INT_RANGES["U8"],
+    "EW": INT_RANGES["U16"],
+    "EL": INT_RANGES["U32"],
+}
+
+# Types whose payload is free text in <Val>.
+TEXT_TAGS: frozenset[str] = frozenset({"String", "Path", "DAQChannel"})
+
+# Types built on the schema's LVDataType: exactly <Name> then <Val>.
+SIMPLE_TAGS: frozenset[str] = (
+    FLOAT_TAGS | COMPLEX_TAGS | frozenset(INT_RANGES) | TEXT_TAGS | {"Boolean"}
+)
+
+_WAVEFORM_BASES: tuple[str, ...] = ("DBL", "I16", "SGL", "EXT", "I8", "I32", "I64")
+_WAVEFORM_BASES += ("U8", "U16", "U32", "U64", "CSG", "CDB", "CXT")
+
+# Types the schema defines as <Name> followed by any number of <Cluster> elements.
+CLUSTERED_TAGS: frozenset[str] = frozenset(
+    {"WDT", "DynamicData", "Timestamp", "DigitalData", "DigitalWaveform"}
+    | {f"{base}Waveform" for base in _WAVEFORM_BASES}
+)
+
+# Every value element allowed inside <LVData>, <Cluster> and <LvVariant>.
+VALUE_TAGS: frozenset[str] = (
+    SIMPLE_TAGS
+    | frozenset(ENUM_RANGES)
+    | CLUSTERED_TAGS
+    | {"Refnum", "Cluster", "Array", "LvVariant"}
+)
+
+# The schema does not allow an <Array> directly inside an <Array>.
+ARRAY_ITEM_TAGS: frozenset[str] = VALUE_TAGS - {"Array"}
+
+# Tags `to_lv_xml` accepts as a plain string schema.
+SCALAR_TAGS: frozenset[str] = SIMPLE_TAGS
+
+
+@dataclass(frozen=True)
+class Array:
+    """A LabVIEW array of homogeneous `element` values with `ndim` dimensions.
+
+    A one-dimensional array maps to a list, a two-dimensional one to a list of equal
+    length lists, and so on, in LabVIEW's row-major order.
+    """
+
+    element: Schema
+    ndim: int = 1
+
+    def __post_init__(self) -> None:
+        if isinstance(self.ndim, bool) or not isinstance(self.ndim, int) or self.ndim < 1:
+            raise ValueError(f"Array ndim must be a positive int, got {self.ndim!r}")
+        if isinstance(self.element, Array):
+            raise ValueError("an Array element cannot be an Array; wrap it in a Cluster")
+
+
+@dataclass(frozen=True)
+class Cluster:
+    """A LabVIEW cluster: named fields kept in declaration order."""
+
+    fields: dict[str, Schema]
+
+
+@dataclass(frozen=True)
+class LVEnum:
+    """A LabVIEW enum: its ordered `choices` and the `EB`, `EW` or `EL` storage tag.
+
+    Values are written as the index of a choice; a Python value may be the choice label
+    or its integer index. `EW` (16-bit) is LabVIEW's default enum representation.
+    """
+
+    choices: tuple[str, ...]
+    tag: str = "EW"
+
+    def __post_init__(self) -> None:
+        if isinstance(self.choices, str) or not all(isinstance(c, str) for c in self.choices):
+            raise TypeError("LVEnum choices must be a sequence of str labels, not one str")
+        object.__setattr__(self, "choices", tuple(self.choices))
+        if self.tag not in ENUM_RANGES:
+            raise ValueError(f"LVEnum tag must be EB, EW or EL, got {self.tag!r}")
+        if not self.choices:
+            raise ValueError("LVEnum needs at least one choice")
+        if len(set(self.choices)) != len(self.choices):
+            raise ValueError("LVEnum choices must be unique")
+        if len(self.choices) > ENUM_RANGES[self.tag][1] + 1:
+            raise ValueError(f"too many choices for {self.tag}")
+
+
+# A scalar tag such as "DBL", or a compound container.
+Schema = str | Array | Cluster | LVEnum
+
+# Any value this codec maps to Python. bool precedes int because bool is an int subclass.
+Value = bool | int | float | complex | str | list["Value"] | dict[str, "Value"]