lvxml 0.2.1__py3-none-any.whl

lvxml/__init__.py

@@ -0,0 +1,32 @@
+"""Codec between LabVIEW's Flatten/Unflatten XML schema and native Python values."""
+
+from __future__ import annotations
+
+from ._checks import validate
+from ._decode import from_lv_xml, from_lv_xml_all, to_value
+from ._dump import dump
+from ._encode import to_lv_xml, to_node
+from ._errors import LVXMLError
+from ._node import LVDATA_NAMESPACE, Document, Node
+from ._parse import parse
+from ._schema import Array, Cluster, LVEnum
+
+__version__ = "0.2.1"
+
+__all__ = [
+    "LVDATA_NAMESPACE",
+    "Array",
+    "Cluster",
+    "Document",
+    "LVEnum",
+    "LVXMLError",
+    "Node",
+    "dump",
+    "from_lv_xml",
+    "from_lv_xml_all",
+    "parse",
+    "to_lv_xml",
+    "to_node",
+    "to_value",
+    "validate",
+]

lvxml/__main__.py

@@ -0,0 +1,9 @@
+"""Allow ``python -m lvxml`` as an alternative to the ``lvxml`` command."""
+
+from __future__ import annotations
+
+import sys
+
+from ._cli import main
+
+sys.exit(main())

lvxml/_checks.py

@@ -0,0 +1,110 @@
+"""Consistency rules beyond the XSD's shape: counts that agree and values that parse."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Iterator
+
+from ._errors import LVXMLError
+from ._node import Document, Node
+from ._numbers import parse_bool, parse_complex, parse_float, parse_int
+from ._parse import parse
+from ._schema import COMPLEX_TAGS, ENUM_RANGES, FLOAT_TAGS, INT_RANGES
+
+# An empty array with leading non-zero sizes (such as 1000x0) decodes to nested empty lists;
+# more than this many is refused so a tiny input cannot demand unbounded memory.
+MAX_EMPTY_ROWS = 100_000
+
+
+def problems(node: Node) -> list[str]:
+    """Return what is wrong with `node` itself, not looking inside its items."""
+    found: list[str] = []
+    try:
+        _check_val(node)
+    except ValueError as exc:
+        found.append(str(exc))
+    if node.tag == "Array":
+        total = math.prod(node.dims)
+        count = len(node.items)
+        if total == 0 and count > 1:
+            found.append(f"array Dimsize {_dims(node)} is empty but holds {count} elements")
+        if total == 0 and _empty_rows(node.dims) > MAX_EMPTY_ROWS:
+            found.append(f"empty array Dimsize {_dims(node)} needs over {MAX_EMPTY_ROWS} lists")
+        elif total and count != total:
+            found.append(f"array Dimsize {_dims(node)} needs {total} elements, found {count}")
+        tags = {item.tag for item in node.items}
+        if len(tags) > 1:
+            found.append(f"array mixes element types {sorted(tags)}")
+    if node.tag == "Cluster" and node.num_elts != len(node.items):
+        found.append(f"cluster NumElts {node.num_elts} does not match {len(node.items)} elements")
+    return found
+
+
+def _empty_rows(dims: tuple[int, ...]) -> int:
+    rows, prefix = 0, 1
+    for dim in dims[:-1]:
+        if dim == 0:
+            break
+        prefix *= dim
+        rows += prefix
+        if rows > MAX_EMPTY_ROWS:
+            break
+    return rows
+
+
+def _dims(node: Node) -> str:
+    return "x".join(str(dim) for dim in node.dims)
+
+
+def _check_val(node: Node) -> None:
+    text = node.val if node.val is not None else ""
+    if node.tag in FLOAT_TAGS:
+        parse_float(text)
+    elif node.tag in COMPLEX_TAGS:
+        parse_complex(text)
+    elif node.tag in INT_RANGES:
+        parse_int(text, node.tag)
+    elif node.tag == "Boolean":
+        parse_bool(text)
+    elif node.tag in ENUM_RANGES:
+        index = parse_int(text, node.tag)
+        if index >= len(node.choices):
+            raise ValueError(f"enum index {index} is past its {len(node.choices)} choices")
+
+
+def child_path(parent: str, node: Node) -> str:
+    here = f"{parent}/{node.tag}" if parent else node.tag
+    return f"{here}[{node.name}]" if node.name else here
+
+
+def walk(node: Node, parent: str) -> Iterator[tuple[str, Node]]:
+    """Yield every node under and including `node` with its path, depth first."""
+    path = child_path(parent, node)
+    yield path, node
+    for item in node.items:
+        yield from walk(item, path)
+
+
+def validate(text: str | bytes) -> list[str]:
+    """Return every problem found in LabVIEW XML `text`; an empty list means it is valid.
+
+    A document that does not have the shape LVXMLSchema.xsd defines yields one problem,
+    since its structure cannot be trusted further. A well-shaped one is then checked
+    value by value: numbers that parse and fit their type, enum indexes inside the
+    choice list, and ``NumElts`` and ``Dimsize`` that match the elements present.
+    """
+    try:
+        document = parse(text)
+    except LVXMLError as exc:
+        return [str(exc)]
+    return document_problems(document)
+
+
+def document_problems(document: Document) -> list[str]:
+    """Return every value-level problem in an already parsed `document`."""
+    root = "LVData" if document.wrapped else ""
+    found: list[str] = []
+    for top in document.values:
+        for path, node in walk(top, root):
+            found.extend(f"{path}: {problem}" for problem in problems(node))
+    return found

lvxml/_cli.py

@@ -0,0 +1,167 @@
+"""The `lvxml` command: convert LabVIEW XML to and from JSON, and validate it."""
+
+from __future__ import annotations
+
+import argparse
+import codecs
+import json
+import math
+import sys
+from collections.abc import Sequence
+from typing import NoReturn
+
+from . import __version__
+from ._checks import document_problems, validate
+from ._decode import to_value
+from ._dump import dump
+from ._errors import LVXMLError
+from ._node import Document
+from ._numbers import format_float
+from ._parse import parse
+
+EXAMPLES = """\
+examples:
+  echo "<I32><Name>n</Name><Val>7</Val></I32>" | lvxml to-json --values -
+  lvxml to-json data.xml -o data.json      lossless tree, every name and raw value kept
+  lvxml to-json --values data.xml          plain values: numbers, strings, lists, dicts
+  lvxml to-xml data.json -o data.xml       tree JSON back to LabVIEW XML
+  lvxml validate data.xml other.xml        check shape and values, exit 1 on any problem
+
+A FILE of "-" reads standard input. Errors go to standard error with exit status 1.
+"""
+
+
+class _Parser(argparse.ArgumentParser):
+    def error(self, message: str) -> NoReturn:
+        self.print_usage(sys.stderr)
+        self.exit(1, f"{self.prog}: error: {message}\n")
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = _Parser(
+        prog="lvxml",
+        description="Read, write and check LabVIEW Flatten To XML data.",
+        epilog=EXAMPLES,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("--version", action="version", version=f"lvxml {__version__}")
+    commands = parser.add_subparsers(dest="command", required=True, metavar="COMMAND")
+    to_json = commands.add_parser("to-json", help="convert LabVIEW XML to JSON")
+    to_json.add_argument("file", metavar="FILE", help="LabVIEW XML file, or - for stdin")
+    to_json.add_argument("--values", action="store_true", help="emit plain values, not the tree")
+    to_xml = commands.add_parser("to-xml", help="convert tree JSON (from to-json) to LabVIEW XML")
+    to_xml.add_argument("file", metavar="FILE", help="tree JSON file, or - for stdin")
+    to_xml.add_argument(
+        "--newline", choices=["crlf", "lf"], default="crlf", help="line break (default: crlf)"
+    )
+    check = commands.add_parser("validate", help="check LabVIEW XML files")
+    check.add_argument("files", metavar="FILE", nargs="+", help="LabVIEW XML files")
+    for sub in (to_json, to_xml, check):
+        sub.add_argument(
+            "--encoding", default="utf-8", help="text encoding of files (default: utf-8)"
+        )
+    for sub in (to_json, to_xml):
+        sub.add_argument("-o", "--output", metavar="OUT", help="write here instead of stdout")
+    return parser
+
+
+def _read(path: str, encoding: str) -> str:
+    if path == "-":
+        data = sys.stdin.buffer.read()
+    else:
+        with open(path, "rb") as handle:
+            data = handle.read()
+    try:
+        return data.decode(encoding)
+    except UnicodeDecodeError as exc:
+        where = "stdin" if path == "-" else path
+        raise LVXMLError(f"{where} is not valid {encoding} ({exc.reason}); try --encoding") from exc
+
+
+def _write(text: str, output: str | None, encoding: str) -> None:
+    try:
+        data = text.encode(encoding)
+    except UnicodeEncodeError as exc:
+        bad = exc.object[exc.start : exc.end]
+        raise LVXMLError(f"{bad!r} cannot be written as {encoding}; try --encoding utf-8") from exc
+    if output is None:
+        sys.stdout.buffer.write(data)
+        sys.stdout.buffer.flush()
+    else:
+        with open(output, "wb") as handle:
+            handle.write(data)
+
+
+def _plain(value: object) -> object:
+    """Make a value strict JSON: complex as {"re", "im"}, NaN and Inf as strings."""
+    if isinstance(value, float) and not math.isfinite(value):
+        return format_float(value, "DBL")
+    if isinstance(value, complex):
+        return {"re": _plain(value.real), "im": _plain(value.imag)}
+    if isinstance(value, list):
+        return [_plain(item) for item in value]
+    if isinstance(value, dict):
+        return {key: _plain(item) for key, item in value.items()}
+    return value
+
+
+def _to_json(args: argparse.Namespace) -> int:
+    document = parse(_read(args.file, args.encoding))
+    if args.values:
+        found = document_problems(document)
+        if found:
+            raise LVXMLError(found[0])
+        data: object = [
+            {"name": node.name, "type": node.tag, "value": _plain(to_value(node))}
+            for node in document.values
+        ]
+    else:
+        data = document.to_dict()
+    text = json.dumps(data, indent=2, ensure_ascii=False, allow_nan=False) + "\n"
+    _write(text, args.output, "utf-8")
+    return 0
+
+
+def _to_xml(args: argparse.Namespace) -> int:
+    try:
+        data = json.loads(_read(args.file, args.encoding))
+    except json.JSONDecodeError as exc:
+        raise LVXMLError(f"invalid JSON: {exc}") from exc
+    newline = "\r\n" if args.newline == "crlf" else "\n"
+    _write(dump(Document.from_dict(data), newline=newline), args.output, args.encoding)
+    return 0
+
+
+def _validate(args: argparse.Namespace) -> int:
+    status = 0
+    for path in args.files:
+        try:
+            found = validate(_read(path, args.encoding))
+        except (LVXMLError, OSError) as exc:
+            found = [str(exc)]
+        for problem in found:
+            print(f"{path}: {problem}", file=sys.stderr)
+        if found:
+            status = 1
+        else:
+            print(f"{path}: OK")
+    return status
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the command line with `argv` (default: ``sys.argv[1:]``); return the exit status."""
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    try:
+        codecs.lookup(args.encoding)
+    except LookupError:
+        parser.error(f"unknown encoding {args.encoding!r}")
+    handlers = {"to-json": _to_json, "to-xml": _to_xml, "validate": _validate}
+    try:
+        return handlers[args.command](args)
+    except (LVXMLError, OSError) as exc:
+        print(f"lvxml: error: {exc}", file=sys.stderr)
+        return 1
+    except RecursionError:
+        print("lvxml: error: the input is nested too deeply", file=sys.stderr)
+        return 1

lvxml/_decode.py

@@ -0,0 +1,109 @@
+"""Turn LabVIEW Flatten-To-XML text, or a parsed tree, into native Python values."""
+
+from __future__ import annotations
+
+from ._checks import child_path, problems
+from ._errors import LVXMLError
+from ._node import Node
+from ._numbers import parse_bool, parse_complex, parse_float, parse_int
+from ._parse import parse
+from ._schema import COMPLEX_TAGS, ENUM_RANGES, FLOAT_TAGS, INT_RANGES, Value
+from ._treejson import check_shape
+
+
+def from_lv_xml(text: str | bytes) -> Value:
+    """Parse LabVIEW flattened XML into the Python value of its first value element.
+
+    Inside an ``<LVData>`` file wrapper the ``<Version>`` header is skipped; use
+    `from_lv_xml_all` when the file holds several values.
+    """
+    document = parse(text)
+    if not document.values:
+        raise LVXMLError("<LVData> holds no value")
+    root = "LVData" if document.wrapped else ""
+    return _value(document.values[0], root)
+
+
+def from_lv_xml_all(text: str | bytes) -> list[Value]:
+    """Parse LabVIEW flattened XML into the Python values of every value element, in order."""
+    document = parse(text)
+    root = "LVData" if document.wrapped else ""
+    return [_value(node, root) for node in document.values]
+
+
+def to_value(node: Node) -> Value:
+    """Convert one typed `Node` into its Python value.
+
+    Integers become ``int``, ``SGL``/``DBL``/``EXT`` ``float``, ``CSG``/``CDB``/``CXT``
+    ``complex``, ``Boolean`` ``bool``; ``String``, ``Path``, ``DAQChannel`` and a
+    ``Refnum``'s ``<Val>`` stay ``str``; an enum becomes its selected choice label. An
+    ``Array`` becomes a list, nested once per dimension, and a ``Cluster`` a dict keyed by
+    field name. ``LvVariant``, ``Timestamp``, ``WDT``, ``DynamicData``, ``DigitalData``
+    and the waveform elements become the list of their items' values.
+    """
+    check_shape(node, "")
+    try:
+        return _value(node, "")
+    except RecursionError:
+        raise LVXMLError("the tree is nested too deeply to convert") from None
+
+
+def _value(node: Node, parent: str) -> Value:
+    path = child_path(parent, node)
+    found = problems(node)
+    if found:
+        raise LVXMLError(found[0], path)
+    tag, text = node.tag, node.val if node.val is not None else ""
+    if tag in FLOAT_TAGS:
+        return parse_float(text)
+    if tag in COMPLEX_TAGS:
+        return parse_complex(text)
+    if tag in INT_RANGES:
+        return parse_int(text, tag)
+    if tag == "Boolean":
+        return parse_bool(text)
+    if tag in ENUM_RANGES:
+        return node.choices[parse_int(text, tag)]
+    if tag == "Array":
+        return _array(node, path)
+    if tag == "Cluster":
+        return _cluster(node, path)
+    if node.items or node.val is None:
+        return [_value(item, path) for item in node.items]
+    return text
+
+
+def _cluster(node: Node, path: str) -> dict[str, Value]:
+    fields: dict[str, Value] = {}
+    for item in node.items:
+        if item.name in fields:
+            raise LVXMLError(
+                f"duplicate field name {item.name!r} cannot map to a dict; "
+                "use lvxml.parse for positional access",
+                path,
+            )
+        fields[item.name] = _value(item, path)
+    return fields
+
+
+def _array(node: Node, path: str) -> list[Value]:
+    dims = node.dims
+    if 0 in dims:
+        for item in node.items:
+            _value(item, path)  # the default element must still be a valid value
+        return _empty(dims)
+    flat = [_value(item, path) for item in node.items]
+    return _reshape(flat, dims)
+
+
+def _empty(dims: tuple[int, ...]) -> list[Value]:
+    if dims[0] == 0 or len(dims) == 1:
+        return []
+    return [_empty(dims[1:]) for _ in range(dims[0])]
+
+
+def _reshape(flat: list[Value], dims: tuple[int, ...]) -> list[Value]:
+    if len(dims) == 1:
+        return flat
+    step = len(flat) // dims[0]
+    return [_reshape(flat[i * step : (i + 1) * step], dims[1:]) for i in range(dims[0])]

lvxml/_dump.py

@@ -0,0 +1,106 @@
+"""Write the typed tree back as text, in the layout LabVIEW's own XML writer uses."""
+
+from __future__ import annotations
+
+import re
+
+from ._errors import LVXMLError
+from ._node import Document, Node
+from ._treejson import check_shape
+
+# The declaration LabVIEW's XML file writer emits before <LVData>.
+DECLARATION = "<?xml version='1.0' standalone='yes' ?>"
+
+# Characters XML 1.0 cannot carry at all, even escaped.
+_ILLEGAL = re.compile("[\x00-\x08\x0b\x0c\x0e-\x1f\ud800-\udfff\ufffe\uffff]")
+
+
+def dump(
+    tree: Document | Node,
+    *,
+    newline: str = "\r\n",
+    indent: str = "",
+    declaration: bool | None = None,
+) -> str:
+    """Serialize a `Document` or a single `Node` as LabVIEW XML.
+
+    The defaults reproduce the layout of a file LabVIEW 2026 wrote: one element per line,
+    CRLF line breaks, no indentation, empty elements written as ``<Name></Name>`` and no
+    line break after the last element. Only ``&``, ``<`` and ``>`` are escaped.
+    `declaration` defaults to true for an ``<LVData>`` document and false otherwise. A
+    `Node` is written bare, as Flatten To XML outputs it.
+    """
+    document = tree if isinstance(tree, Document) else Document((tree,), False, None)
+    if not document.wrapped and len(document.items) != 1:
+        raise LVXMLError("a bare document holds exactly one value; set wrapped=True")
+    root = "LVData" if document.wrapped else ""
+    for node in document.items:
+        if node.tag == "Version" and document.wrapped:
+            if node != Node("Version", val=node.val) or node.val is None:
+                raise LVXMLError("a Version node only takes a val", root)
+        else:
+            try:
+                check_shape(node, root)
+            except RecursionError:
+                raise LVXMLError("the tree is nested too deeply to write", root) from None
+    lines: list[str] = []
+    if declaration if declaration is not None else document.wrapped:
+        lines.append(DECLARATION)
+    xmlns = f' xmlns="{_escape(document.namespace, attr=True)}"' if document.namespace else ""
+    if document.wrapped:
+        lines.append(f"<LVData{xmlns}>")
+        for node in document.items:
+            _write(node, lines, indent, 1 if indent else 0, "")
+        lines.append("</LVData>")
+    else:
+        _write(document.items[0], lines, indent, 0, xmlns)
+    return newline.join(lines)
+
+
+def _escape(text: str, attr: bool = False) -> str:
+    bad = _ILLEGAL.search(text)
+    if bad:
+        raise LVXMLError(f"character U+{ord(bad.group()):04X} cannot be written in XML")
+    text = text.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+    return text.replace('"', "&quot;") if attr else text
+
+
+def _leaf(tag: str, text: str, pad: str) -> str:
+    return f"{pad}<{tag}>{_escape(text)}</{tag}>"
+
+
+def _write(node: Node, lines: list[str], indent: str, depth: int, xmlns: str) -> None:
+    pad = indent * depth
+    inner = indent * (depth + 1)
+    if node.tag == "Version":
+        lines.append(_leaf("Version", node.val or "", pad))
+        return
+    lines.append(f"{pad}<{node.tag}{xmlns}>")
+    lines.append(_leaf("Name", node.name, inner))
+    lines.extend(_leaf("Choice", choice, inner) for choice in node.choices)
+    if node.val is not None:
+        lines.append(_leaf("Val", node.val, inner))
+    _write_extra(node.extra, lines, inner, indent)
+    lines.extend(_leaf("Dimsize", str(dim), inner) for dim in node.dims)
+    if node.num_elts is not None:
+        lines.append(_leaf("NumElts", str(node.num_elts), inner))
+    for item in node.items:
+        _write(item, lines, indent, depth + 1, "")
+    lines.append(f"{pad}</{node.tag}>")
+
+
+def _write_extra(
+    extra: tuple[tuple[str, str], ...], lines: list[str], pad: str, indent: str
+) -> None:
+    open_group = ""
+    for key, text in extra:
+        group, _, field = key.rpartition(".")
+        if group != open_group:
+            if open_group:
+                lines.append(f"{pad}</{open_group}>")
+            if group:
+                lines.append(f"{pad}<{group}>")
+            open_group = group
+        lines.append(_leaf(field, text, pad + indent if group else pad))
+    if open_group:
+        lines.append(f"{pad}</{open_group}>")