mdxml 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- mdxml/__init__.py +39 -0
- mdxml/__main__.py +5 -0
- mdxml/_cli.py +96 -0
- mdxml/_convert.py +151 -0
- mdxml/_dict.py +42 -0
- mdxml/_errors.py +39 -0
- mdxml/_grammar.py +259 -0
- mdxml/_header.py +92 -0
- mdxml/_lookup.py +54 -0
- mdxml/_protocols.py +135 -0
- mdxml/_read.py +75 -0
- mdxml/_reader.py +191 -0
- mdxml/_schema.py +131 -0
- mdxml/_source.py +192 -0
- mdxml/_variables.py +426 -0
- mdxml/fmi2/__init__.py +73 -0
- mdxml/fmi2/_annotations.py +34 -0
- mdxml/fmi2/_header.py +525 -0
- mdxml/fmi2/_model.py +73 -0
- mdxml/fmi2/_structure.py +100 -0
- mdxml/fmi2/_variables.py +323 -0
- mdxml/fmi3/__init__.py +125 -0
- mdxml/fmi3/_annotations.py +43 -0
- mdxml/fmi3/_header.py +635 -0
- mdxml/fmi3/_model.py +59 -0
- mdxml/fmi3/_structure.py +103 -0
- mdxml/fmi3/_variables.py +603 -0
- mdxml/py.typed +0 -0
- mdxml-0.1.0.dist-info/METADATA +202 -0
- mdxml-0.1.0.dist-info/RECORD +33 -0
- mdxml-0.1.0.dist-info/WHEEL +4 -0
- mdxml-0.1.0.dist-info/entry_points.txt +3 -0
- mdxml-0.1.0.dist-info/licenses/LICENSE +21 -0
mdxml/__init__.py
ADDED
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
"""Fast, zero-dependency, streaming parser for FMI modelDescription.xml files."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from mdxml import fmi2, fmi3
|
|
6
|
+
from mdxml._cli import main
|
|
7
|
+
from mdxml._dict import to_dict
|
|
8
|
+
from mdxml._errors import MdxmlError, ParseError, UnsafeInput, UnsupportedFmiVersion
|
|
9
|
+
from mdxml._header import AnyModelHeader, read_header
|
|
10
|
+
from mdxml._lookup import Named
|
|
11
|
+
from mdxml._protocols import InterfaceType, ModelHeader, ModelVariable
|
|
12
|
+
from mdxml._read import AnyModelDescription, read
|
|
13
|
+
from mdxml._reader import DEFAULT_MAX_XML_BYTES
|
|
14
|
+
from mdxml._source import Source
|
|
15
|
+
from mdxml._variables import AnyVariable, VariableIterator, iter_variables
|
|
16
|
+
|
|
17
|
+
__all__ = [
|
|
18
|
+
"DEFAULT_MAX_XML_BYTES",
|
|
19
|
+
"AnyModelDescription",
|
|
20
|
+
"AnyModelHeader",
|
|
21
|
+
"AnyVariable",
|
|
22
|
+
"InterfaceType",
|
|
23
|
+
"MdxmlError",
|
|
24
|
+
"ModelHeader",
|
|
25
|
+
"ModelVariable",
|
|
26
|
+
"Named",
|
|
27
|
+
"ParseError",
|
|
28
|
+
"Source",
|
|
29
|
+
"UnsafeInput",
|
|
30
|
+
"UnsupportedFmiVersion",
|
|
31
|
+
"VariableIterator",
|
|
32
|
+
"fmi2",
|
|
33
|
+
"fmi3",
|
|
34
|
+
"iter_variables",
|
|
35
|
+
"main",
|
|
36
|
+
"read",
|
|
37
|
+
"read_header",
|
|
38
|
+
"to_dict",
|
|
39
|
+
]
|
mdxml/__main__.py
ADDED
mdxml/_cli.py
ADDED
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
"""The ``mdxml`` command-line tool."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import argparse
|
|
6
|
+
import json
|
|
7
|
+
import sys
|
|
8
|
+
from collections.abc import Sequence
|
|
9
|
+
|
|
10
|
+
from mdxml._dict import to_dict
|
|
11
|
+
from mdxml._errors import MdxmlError
|
|
12
|
+
from mdxml._header import read_header
|
|
13
|
+
from mdxml._reader import DEFAULT_MAX_XML_BYTES
|
|
14
|
+
from mdxml._variables import iter_variables
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
def _add_source_arguments(parser: argparse.ArgumentParser) -> None:
|
|
18
|
+
parser.add_argument("path", help="a .fmu file, an unzipped FMU directory or a modelDescription.xml file")
|
|
19
|
+
parser.add_argument(
|
|
20
|
+
"--member", help="where the Model Description lives inside the FMU (default: modelDescription.xml)"
|
|
21
|
+
)
|
|
22
|
+
parser.add_argument(
|
|
23
|
+
"--strict",
|
|
24
|
+
action="store_true",
|
|
25
|
+
help="raise on anything the FMI XSD doesn't allow, instead of ignoring it",
|
|
26
|
+
)
|
|
27
|
+
parser.add_argument(
|
|
28
|
+
"--annotations",
|
|
29
|
+
action="store_true",
|
|
30
|
+
help="keep Tool Annotations as raw XML instead of skipping them",
|
|
31
|
+
)
|
|
32
|
+
parser.add_argument(
|
|
33
|
+
"--max-xml-bytes",
|
|
34
|
+
type=int,
|
|
35
|
+
default=DEFAULT_MAX_XML_BYTES,
|
|
36
|
+
help=f"refuse Model Descriptions larger than this many bytes (default: {DEFAULT_MAX_XML_BYTES})",
|
|
37
|
+
)
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
def _parser() -> argparse.ArgumentParser:
|
|
41
|
+
parser = argparse.ArgumentParser(prog="mdxml", description="Read FMI modelDescription.xml files.")
|
|
42
|
+
commands = parser.add_subparsers(dest="command", required=True)
|
|
43
|
+
|
|
44
|
+
header = commands.add_parser("header", help="print the Model Header as JSON")
|
|
45
|
+
_add_source_arguments(header)
|
|
46
|
+
|
|
47
|
+
variables = commands.add_parser("variables", help="print the Model Variables as JSON, one per line")
|
|
48
|
+
_add_source_arguments(variables)
|
|
49
|
+
variables.add_argument("--causality", action="append", help="only variables with this causality (repeatable)")
|
|
50
|
+
variables.add_argument("--variability", action="append", help="only variables with this variability (repeatable)")
|
|
51
|
+
variables.add_argument("--name-prefix", help="only variables whose name starts with this")
|
|
52
|
+
return parser
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
def _print_header(args: argparse.Namespace) -> None:
|
|
56
|
+
header = read_header(
|
|
57
|
+
args.path,
|
|
58
|
+
member=args.member,
|
|
59
|
+
strict=args.strict,
|
|
60
|
+
annotations=args.annotations,
|
|
61
|
+
max_xml_bytes=args.max_xml_bytes,
|
|
62
|
+
)
|
|
63
|
+
json.dump(to_dict(header), sys.stdout, indent=2, ensure_ascii=False, allow_nan=False)
|
|
64
|
+
sys.stdout.write("\n")
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
def _print_variables(args: argparse.Namespace) -> None:
|
|
68
|
+
variables = iter_variables(
|
|
69
|
+
args.path,
|
|
70
|
+
causality=args.causality,
|
|
71
|
+
variability=args.variability,
|
|
72
|
+
name_prefix=args.name_prefix,
|
|
73
|
+
member=args.member,
|
|
74
|
+
strict=args.strict,
|
|
75
|
+
annotations=args.annotations,
|
|
76
|
+
max_xml_bytes=args.max_xml_bytes,
|
|
77
|
+
)
|
|
78
|
+
with variables:
|
|
79
|
+
for variable in variables:
|
|
80
|
+
sys.stdout.write(json.dumps(to_dict(variable), ensure_ascii=False, allow_nan=False))
|
|
81
|
+
sys.stdout.write("\n")
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
def main(argv: Sequence[str] | None = None) -> int:
|
|
85
|
+
"""Run the command-line tool and return its exit code."""
|
|
86
|
+
args = _parser().parse_args(argv)
|
|
87
|
+
try:
|
|
88
|
+
if args.command == "header":
|
|
89
|
+
_print_header(args)
|
|
90
|
+
else:
|
|
91
|
+
_print_variables(args)
|
|
92
|
+
except (MdxmlError, OSError, ValueError, TypeError) as exc:
|
|
93
|
+
sys.stdout.flush()
|
|
94
|
+
print(f"mdxml: error: {exc}", file=sys.stderr)
|
|
95
|
+
return 1
|
|
96
|
+
return 0
|
mdxml/_convert.py
ADDED
|
@@ -0,0 +1,151 @@
|
|
|
1
|
+
"""Conversions from XSD attribute strings to Python values.
|
|
2
|
+
|
|
3
|
+
Every converter has the same shape, ``convert(text, *, strict) -> value``, and
|
|
4
|
+
raises :class:`ValueError` when ``text`` isn't a valid value. ``strict`` only
|
|
5
|
+
matters where lenient mode accepts more than the XSD does (ADR 0003).
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
import re
|
|
11
|
+
from datetime import datetime
|
|
12
|
+
from enum import Enum
|
|
13
|
+
from typing import Protocol, TypeVar
|
|
14
|
+
|
|
15
|
+
E = TypeVar("E", bound=Enum)
|
|
16
|
+
T = TypeVar("T")
|
|
17
|
+
T_co = TypeVar("T_co", covariant=True)
|
|
18
|
+
|
|
19
|
+
_TRUE = frozenset({"true", "1"})
|
|
20
|
+
_FALSE = frozenset({"false", "0"})
|
|
21
|
+
_UTC_SUFFIX = re.compile(r"[Zz]$")
|
|
22
|
+
# xs:double's lexical space; float() alone would also accept "1_000" and "infinity".
|
|
23
|
+
_DOUBLE = re.compile(r"[+-]?(\d+(\.\d*)?|\.\d+)([eE][+-]?\d+)?|[+-]?INF|NaN")
|
|
24
|
+
_INTEGER = re.compile(r"[+-]?\d+")
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
class Converter(Protocol[T_co]):
|
|
28
|
+
"""Turns an attribute's text into a Python value."""
|
|
29
|
+
|
|
30
|
+
def __call__(self, text: str, /, *, strict: bool) -> T_co: ...
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
def to_text(text: str, *, strict: bool) -> str:
|
|
34
|
+
"""``xs:string`` and ``xs:normalizedString``: kept exactly as written."""
|
|
35
|
+
return text
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
def to_bool(text: str, *, strict: bool) -> bool:
|
|
39
|
+
"""``xs:boolean``: ``true``/``false``/``1``/``0``. Lenient mode also ignores case (``True``, ``FALSE``)."""
|
|
40
|
+
value = text.strip()
|
|
41
|
+
if not strict:
|
|
42
|
+
value = value.lower()
|
|
43
|
+
if value in _TRUE:
|
|
44
|
+
return True
|
|
45
|
+
if value in _FALSE:
|
|
46
|
+
return False
|
|
47
|
+
raise ValueError(f"not an xs:boolean: {text!r}")
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
def to_int(text: str, *, strict: bool) -> int:
|
|
51
|
+
"""``xs:int`` and friends."""
|
|
52
|
+
value = text.strip()
|
|
53
|
+
if not _INTEGER.fullmatch(value):
|
|
54
|
+
raise ValueError(f"not an integer: {text!r}")
|
|
55
|
+
return int(value)
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
def to_unsigned_int(text: str, *, strict: bool) -> int:
|
|
59
|
+
"""``xs:unsignedInt`` and friends: an integer that must not be negative."""
|
|
60
|
+
value = to_int(text, strict=strict)
|
|
61
|
+
if value < 0:
|
|
62
|
+
raise ValueError(f"not an unsigned integer: {text!r}")
|
|
63
|
+
return value
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
class IntRange(Converter[int]):
|
|
67
|
+
"""An XSD integer type with bounds, e.g. ``xs:byte`` is ``IntRange(-128, 127)``."""
|
|
68
|
+
|
|
69
|
+
__slots__ = ("_high", "_low", "_name")
|
|
70
|
+
|
|
71
|
+
def __init__(self, name: str, low: int, high: int) -> None:
|
|
72
|
+
self._name = name
|
|
73
|
+
self._low = low
|
|
74
|
+
self._high = high
|
|
75
|
+
|
|
76
|
+
def __call__(self, text: str, /, *, strict: bool) -> int:
|
|
77
|
+
"""Convert ``text``, checking it's within the type's bounds."""
|
|
78
|
+
value = to_int(text, strict=strict)
|
|
79
|
+
if not self._low <= value <= self._high:
|
|
80
|
+
raise ValueError(f"{text!r} is out of range for {self._name} [{self._low}, {self._high}]")
|
|
81
|
+
return value
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
BYTE = IntRange("xs:byte", -(2**7), 2**7 - 1)
|
|
85
|
+
UNSIGNED_BYTE = IntRange("xs:unsignedByte", 0, 2**8 - 1)
|
|
86
|
+
SHORT = IntRange("xs:short", -(2**15), 2**15 - 1)
|
|
87
|
+
UNSIGNED_SHORT = IntRange("xs:unsignedShort", 0, 2**16 - 1)
|
|
88
|
+
INT = IntRange("xs:int", -(2**31), 2**31 - 1)
|
|
89
|
+
UNSIGNED_INT = IntRange("xs:unsignedInt", 0, 2**32 - 1)
|
|
90
|
+
LONG = IntRange("xs:long", -(2**63), 2**63 - 1)
|
|
91
|
+
UNSIGNED_LONG = IntRange("xs:unsignedLong", 0, 2**64 - 1)
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
def to_double(text: str, *, strict: bool) -> float:
|
|
95
|
+
"""``xs:double``, including ``INF``, ``-INF`` and ``NaN``."""
|
|
96
|
+
value = text.strip()
|
|
97
|
+
if not _DOUBLE.fullmatch(value):
|
|
98
|
+
raise ValueError(f"not an xs:double: {text!r}")
|
|
99
|
+
return float(value)
|
|
100
|
+
|
|
101
|
+
|
|
102
|
+
def to_datetime(text: str, *, strict: bool) -> datetime:
|
|
103
|
+
"""``xs:dateTime``. Accepts a trailing ``Z`` on every supported Python version."""
|
|
104
|
+
return datetime.fromisoformat(_UTC_SUFFIX.sub("+00:00", text.strip()))
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
def to_hex_binary(text: str, *, strict: bool) -> bytes:
|
|
108
|
+
"""``xs:hexBinary``: pairs of hex digits."""
|
|
109
|
+
return bytes.fromhex(text.strip())
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
class ListOf(Converter[tuple[T, ...]]):
|
|
113
|
+
"""An ``xs:list``: whitespace-separated items, each converted with ``item``."""
|
|
114
|
+
|
|
115
|
+
__slots__ = ("_item",)
|
|
116
|
+
|
|
117
|
+
def __init__(self, item: Converter[T]) -> None:
|
|
118
|
+
self._item = item
|
|
119
|
+
|
|
120
|
+
@property
|
|
121
|
+
def item(self) -> Converter[T]:
|
|
122
|
+
"""The converter for each item."""
|
|
123
|
+
return self._item
|
|
124
|
+
|
|
125
|
+
def __call__(self, text: str, /, *, strict: bool) -> tuple[T, ...]:
|
|
126
|
+
"""Convert every item; any invalid item makes the whole list invalid."""
|
|
127
|
+
return tuple(self._item(part, strict=strict) for part in text.split())
|
|
128
|
+
|
|
129
|
+
|
|
130
|
+
class EnumConverter(Converter[E | str]):
|
|
131
|
+
"""A fixed-choice attribute. In lenient mode, values outside the allowed set stay plain strings."""
|
|
132
|
+
|
|
133
|
+
__slots__ = ("_enum",)
|
|
134
|
+
|
|
135
|
+
def __init__(self, enum: type[E]) -> None:
|
|
136
|
+
self._enum = enum
|
|
137
|
+
|
|
138
|
+
@property
|
|
139
|
+
def enum(self) -> type[E]:
|
|
140
|
+
"""The enum values are converted to."""
|
|
141
|
+
return self._enum
|
|
142
|
+
|
|
143
|
+
def __call__(self, text: str, /, *, strict: bool) -> E | str:
|
|
144
|
+
"""Convert ``text`` to a member of the enum."""
|
|
145
|
+
try:
|
|
146
|
+
return self._enum(text.strip())
|
|
147
|
+
except ValueError:
|
|
148
|
+
if strict:
|
|
149
|
+
allowed = ", ".join(repr(member.value) for member in self._enum)
|
|
150
|
+
raise ValueError(f"{text!r} is not one of {allowed}") from None
|
|
151
|
+
return text
|
mdxml/_dict.py
ADDED
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
"""Turning parsed objects into data ``json.dumps`` can handle."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import dataclasses
|
|
6
|
+
import math
|
|
7
|
+
from datetime import datetime
|
|
8
|
+
from enum import Enum
|
|
9
|
+
from typing import Any
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
def to_dict(obj: Any) -> Any:
|
|
13
|
+
"""Convert a parsed mdxml object into plain JSON-ready data.
|
|
14
|
+
|
|
15
|
+
Dataclasses become dicts keyed by field name, with ``None`` fields and
|
|
16
|
+
private (``_``-prefixed) fields left out. Enums become their string value, tuples become lists, datetimes
|
|
17
|
+
become ISO 8601 strings, ``bytes`` become hex strings, and infinite or
|
|
18
|
+
NaN floats become the XSD spellings ``"INF"``, ``"-INF"`` and ``"NaN"``
|
|
19
|
+
(JSON has no such numbers).
|
|
20
|
+
"""
|
|
21
|
+
if dataclasses.is_dataclass(obj) and not isinstance(obj, type):
|
|
22
|
+
return {
|
|
23
|
+
field.name: to_dict(value)
|
|
24
|
+
for field in dataclasses.fields(obj)
|
|
25
|
+
if not field.name.startswith("_") and (value := getattr(obj, field.name)) is not None
|
|
26
|
+
}
|
|
27
|
+
if isinstance(obj, Enum):
|
|
28
|
+
return to_dict(obj.value)
|
|
29
|
+
if isinstance(obj, (tuple, list)):
|
|
30
|
+
return [to_dict(item) for item in obj] # pyright: ignore[reportUnknownVariableType]
|
|
31
|
+
return _scalar(obj)
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
def _scalar(obj: Any) -> Any:
|
|
35
|
+
"""Convert a value that isn't a container into JSON-ready data."""
|
|
36
|
+
if isinstance(obj, datetime):
|
|
37
|
+
return obj.isoformat()
|
|
38
|
+
if isinstance(obj, bytes):
|
|
39
|
+
return obj.hex()
|
|
40
|
+
if isinstance(obj, float) and not math.isfinite(obj):
|
|
41
|
+
return "NaN" if math.isnan(obj) else ("INF" if obj > 0 else "-INF")
|
|
42
|
+
return obj
|
mdxml/_errors.py
ADDED
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
"""Exceptions raised by mdxml."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
class MdxmlError(Exception):
|
|
7
|
+
"""Base class for every error mdxml raises on purpose."""
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
class ParseError(MdxmlError, ValueError):
|
|
11
|
+
"""The Model Description is malformed XML or holds a value that can't be read.
|
|
12
|
+
|
|
13
|
+
``line`` is 1-based and ``column`` is 1-based, pointing at where the
|
|
14
|
+
parser was when the problem was found. Both are ``None`` when unknown.
|
|
15
|
+
"""
|
|
16
|
+
|
|
17
|
+
def __init__(self, message: str, *, line: int | None = None, column: int | None = None) -> None:
|
|
18
|
+
self.message = message
|
|
19
|
+
self.line = line
|
|
20
|
+
self.column = column
|
|
21
|
+
location = f" (line {line}, column {column})" if line is not None and column is not None else ""
|
|
22
|
+
super().__init__(f"{message}{location}")
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
class UnsafeInput(MdxmlError):
|
|
26
|
+
"""The input looks hostile: a ``DOCTYPE`` or entity declaration, or XML larger than ``max_xml_bytes``.
|
|
27
|
+
|
|
28
|
+
Raised before the dangerous part is processed: entities are never expanded,
|
|
29
|
+
external resources are never fetched, and oversized XML is never fully read
|
|
30
|
+
or decompressed.
|
|
31
|
+
"""
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
class UnsupportedFmiVersion(MdxmlError):
|
|
35
|
+
"""The Model Description declares an FMI Version mdxml doesn't support."""
|
|
36
|
+
|
|
37
|
+
def __init__(self, fmi_version: str, reason: str = "mdxml supports FMI 2.0 and 3.0") -> None:
|
|
38
|
+
self.fmi_version = fmi_version
|
|
39
|
+
super().__init__(f"unsupported FMI version {fmi_version!r}: {reason}")
|
mdxml/_grammar.py
ADDED
|
@@ -0,0 +1,259 @@
|
|
|
1
|
+
"""Turning expat events into parsed objects with a per-version grammar.
|
|
2
|
+
|
|
3
|
+
A :class:`Grammar` says which child elements each element may contain and how
|
|
4
|
+
to build each one. :class:`TreeHandler` keeps a stack of open elements, builds
|
|
5
|
+
each element from its attributes and already-built children when it closes,
|
|
6
|
+
and stops when the root's ``stop_at`` child opens. Unknown elements are
|
|
7
|
+
skipped with their whole subtree, or raise with ``strict=True``.
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
from __future__ import annotations
|
|
11
|
+
|
|
12
|
+
import sys
|
|
13
|
+
from collections.abc import Callable, Mapping
|
|
14
|
+
from dataclasses import dataclass
|
|
15
|
+
from types import MappingProxyType
|
|
16
|
+
from typing import Generic, Protocol, TypeVar
|
|
17
|
+
|
|
18
|
+
from mdxml import _reader
|
|
19
|
+
from mdxml._errors import ParseError
|
|
20
|
+
from mdxml._schema import EMPTY, Frame, attributes
|
|
21
|
+
|
|
22
|
+
R = TypeVar("R")
|
|
23
|
+
R_co = TypeVar("R_co", covariant=True)
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
class Builder(Protocol[R_co]):
|
|
27
|
+
"""Builds one element's object from its frame (attributes and built children)."""
|
|
28
|
+
|
|
29
|
+
def __call__(self, frame: Frame, /, *, strict: bool) -> R_co: ...
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
class _Skip:
|
|
33
|
+
__slots__ = ()
|
|
34
|
+
|
|
35
|
+
def __repr__(self) -> str:
|
|
36
|
+
return "SKIP"
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
SKIP = _Skip()
|
|
40
|
+
"""Marks a known child element whose subtree is deliberately not parsed (e.g. annotations)."""
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
class RawBuilder(Protocol[R_co]):
|
|
44
|
+
"""Builds an element from its frame (attributes only) and its raw inner XML."""
|
|
45
|
+
|
|
46
|
+
def __call__(self, frame: Frame, xml: str, /, *, strict: bool) -> R_co: ...
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
class Raw:
|
|
50
|
+
"""Marks a child element kept as raw XML: its attributes are parsed, its content is not.
|
|
51
|
+
|
|
52
|
+
The content is the document's original bytes between the start and end tags,
|
|
53
|
+
decoded as UTF-8 (which FMI requires), so it can be parsed again later.
|
|
54
|
+
"""
|
|
55
|
+
|
|
56
|
+
__slots__ = ("build",)
|
|
57
|
+
|
|
58
|
+
def __init__(self, build: RawBuilder[object]) -> None:
|
|
59
|
+
self.build = build
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
ChildRule = Builder[object] | _Skip | Raw
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
_QUOTES = (ord('"'), ord("'"))
|
|
66
|
+
_TAG_END = ord(">")
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
def _start_tag_length(data: bytes) -> int:
|
|
70
|
+
"""Return the length of the start tag at the beginning of ``data``, up to and including its ``>``."""
|
|
71
|
+
quote = 0
|
|
72
|
+
for i, byte in enumerate(data):
|
|
73
|
+
if quote:
|
|
74
|
+
if byte == quote:
|
|
75
|
+
quote = 0
|
|
76
|
+
elif byte in _QUOTES:
|
|
77
|
+
quote = byte
|
|
78
|
+
elif byte == _TAG_END:
|
|
79
|
+
return i + 1
|
|
80
|
+
raise ParseError("start tag isn't complete") # pragma: no cover - expat reports a start tag only once it's whole
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
class Collect:
|
|
84
|
+
"""Builder for a list element: no attributes of its own, returns its children in document order.
|
|
85
|
+
|
|
86
|
+
With a ``tag``, only children with that tag; without one, all of them.
|
|
87
|
+
"""
|
|
88
|
+
|
|
89
|
+
__slots__ = ("_tag",)
|
|
90
|
+
|
|
91
|
+
def __init__(self, tag: str | None = None) -> None:
|
|
92
|
+
self._tag = tag
|
|
93
|
+
|
|
94
|
+
def __call__(self, frame: Frame, /, *, strict: bool) -> tuple[object, ...]:
|
|
95
|
+
"""Return the built children."""
|
|
96
|
+
attributes(frame, EMPTY, strict=strict)
|
|
97
|
+
if self._tag is None:
|
|
98
|
+
return tuple(obj for _, obj in frame.children)
|
|
99
|
+
return tuple(frame.all(self._tag))
|
|
100
|
+
|
|
101
|
+
|
|
102
|
+
@dataclass(frozen=True, slots=True)
|
|
103
|
+
class Grammar(Generic[R_co]):
|
|
104
|
+
"""The elements of one document part, e.g. the FMI 2 Model Header."""
|
|
105
|
+
|
|
106
|
+
root: str
|
|
107
|
+
stop_at: str
|
|
108
|
+
build_root: Builder[R_co]
|
|
109
|
+
children: Mapping[str, Mapping[str, ChildRule]]
|
|
110
|
+
|
|
111
|
+
def __post_init__(self) -> None:
|
|
112
|
+
frozen = {parent: MappingProxyType(dict(rules)) for parent, rules in self.children.items()}
|
|
113
|
+
object.__setattr__(self, "children", MappingProxyType(frozen))
|
|
114
|
+
|
|
115
|
+
|
|
116
|
+
class TreeHandler(Generic[R]):
|
|
117
|
+
"""Expat handler that builds the root object of a :class:`Grammar`."""
|
|
118
|
+
|
|
119
|
+
__slots__ = (
|
|
120
|
+
"_choose",
|
|
121
|
+
"_grammar",
|
|
122
|
+
"_position",
|
|
123
|
+
"_raw",
|
|
124
|
+
"_raw_depth",
|
|
125
|
+
"_skip_depth",
|
|
126
|
+
"_stack",
|
|
127
|
+
"_strict",
|
|
128
|
+
"result",
|
|
129
|
+
"stopped",
|
|
130
|
+
)
|
|
131
|
+
|
|
132
|
+
def __init__(
|
|
133
|
+
self,
|
|
134
|
+
choose_grammar: Callable[[Frame], Grammar[R]],
|
|
135
|
+
position: list[_reader.Position],
|
|
136
|
+
*,
|
|
137
|
+
strict: bool,
|
|
138
|
+
) -> None:
|
|
139
|
+
"""Create a handler; ``choose_grammar`` picks the grammar from the root frame (e.g. by FMI Version)."""
|
|
140
|
+
self._choose = choose_grammar
|
|
141
|
+
self._grammar: Grammar[R] | None = None
|
|
142
|
+
self._position = position
|
|
143
|
+
self._strict = strict
|
|
144
|
+
self._stack: list[Frame] = []
|
|
145
|
+
self._skip_depth = 0
|
|
146
|
+
self._raw: tuple[Frame, Raw, int, bool] | None = None
|
|
147
|
+
"""While a :class:`Raw` element is open: its frame, rule, content start and whether it's empty."""
|
|
148
|
+
self._raw_depth = 0
|
|
149
|
+
self.result: R | None = None
|
|
150
|
+
self.stopped = False
|
|
151
|
+
|
|
152
|
+
@property
|
|
153
|
+
def at_root_level(self) -> bool:
|
|
154
|
+
"""Return whether the next element to open would be a direct child of the root."""
|
|
155
|
+
return self._grammar is not None and not self._skip_depth and len(self._stack) == 1
|
|
156
|
+
|
|
157
|
+
def stop_here(self) -> R:
|
|
158
|
+
"""Build the root object from what has been read so far, as if ``stop_at`` had opened."""
|
|
159
|
+
self.stopped = True
|
|
160
|
+
return self.finish()
|
|
161
|
+
|
|
162
|
+
def reset(self) -> None:
|
|
163
|
+
"""Forget everything read so far, to build another root; the grammar is chosen again for it."""
|
|
164
|
+
self._grammar = None
|
|
165
|
+
self._stack.clear()
|
|
166
|
+
self._skip_depth = 0
|
|
167
|
+
if self._raw is not None:
|
|
168
|
+
self._position[0].release()
|
|
169
|
+
self._raw = None
|
|
170
|
+
self._raw_depth = 0
|
|
171
|
+
self.result = None
|
|
172
|
+
self.stopped = False
|
|
173
|
+
|
|
174
|
+
def start(self, name: str, attrs: dict[str, str]) -> None:
|
|
175
|
+
"""Open an element."""
|
|
176
|
+
if self._skip_depth:
|
|
177
|
+
self._skip_depth += 1
|
|
178
|
+
return
|
|
179
|
+
if self._raw_depth:
|
|
180
|
+
self._raw_depth += 1
|
|
181
|
+
return
|
|
182
|
+
pos = self._position[0]
|
|
183
|
+
frame = Frame(name, attrs, pos.line, pos.column)
|
|
184
|
+
if not self._stack:
|
|
185
|
+
if self._grammar is None:
|
|
186
|
+
self._grammar = self._choose(frame)
|
|
187
|
+
self._stack.append(frame)
|
|
188
|
+
return
|
|
189
|
+
assert self._grammar is not None # noqa: S101 - set when the root opened
|
|
190
|
+
parent = self._stack[-1]
|
|
191
|
+
if len(self._stack) == 1 and name == self._grammar.stop_at:
|
|
192
|
+
self.stopped = True
|
|
193
|
+
raise _reader.Stop
|
|
194
|
+
rule = self._grammar.children.get(parent.tag, {}).get(name)
|
|
195
|
+
if rule is None:
|
|
196
|
+
if self._strict:
|
|
197
|
+
raise frame.error(f"unknown element <{name}> in <{parent.tag}>")
|
|
198
|
+
self._skip_depth = 1
|
|
199
|
+
return
|
|
200
|
+
if isinstance(rule, _Skip):
|
|
201
|
+
self._skip_depth = 1
|
|
202
|
+
return
|
|
203
|
+
if isinstance(rule, Raw):
|
|
204
|
+
self._start_raw(frame, rule)
|
|
205
|
+
return
|
|
206
|
+
self._stack.append(frame)
|
|
207
|
+
|
|
208
|
+
def _start_raw(self, frame: Frame, rule: Raw) -> None:
|
|
209
|
+
pos = self._position[0]
|
|
210
|
+
start = pos.byte_index
|
|
211
|
+
pos.keep_from(start)
|
|
212
|
+
tag_length = _start_tag_length(pos.kept(start, sys.maxsize))
|
|
213
|
+
self_closing = pos.kept(start + tag_length - 2, start + tag_length) == b"/>"
|
|
214
|
+
self._raw = (frame, rule, start + tag_length, self_closing)
|
|
215
|
+
self._raw_depth = 1
|
|
216
|
+
|
|
217
|
+
def _end_raw(self) -> None:
|
|
218
|
+
assert self._raw is not None # noqa: S101 - only called while a Raw element is open
|
|
219
|
+
frame, rule, content_start, self_closing = self._raw
|
|
220
|
+
pos = self._position[0]
|
|
221
|
+
content = b"" if self_closing else pos.kept(content_start, pos.byte_index)
|
|
222
|
+
pos.release()
|
|
223
|
+
self._raw = None
|
|
224
|
+
try:
|
|
225
|
+
xml = content.decode("utf-8")
|
|
226
|
+
except UnicodeDecodeError as exc:
|
|
227
|
+
raise frame.error(f"<{frame.tag}> content isn't valid UTF-8: {exc}") from None
|
|
228
|
+
self._stack[-1].children.append((frame.tag, rule.build(frame, xml, strict=self._strict)))
|
|
229
|
+
|
|
230
|
+
def end(self, name: str) -> None:
|
|
231
|
+
"""Close an element and build its object."""
|
|
232
|
+
if self._skip_depth:
|
|
233
|
+
self._skip_depth -= 1
|
|
234
|
+
return
|
|
235
|
+
if self._raw_depth:
|
|
236
|
+
self._raw_depth -= 1
|
|
237
|
+
if not self._raw_depth:
|
|
238
|
+
self._end_raw()
|
|
239
|
+
return
|
|
240
|
+
assert self._grammar is not None # noqa: S101 - start() always sets it first
|
|
241
|
+
frame = self._stack.pop()
|
|
242
|
+
if not self._stack:
|
|
243
|
+
self.result = self._grammar.build_root(frame, strict=self._strict)
|
|
244
|
+
return
|
|
245
|
+
parent = self._stack[-1]
|
|
246
|
+
rule = self._grammar.children[parent.tag][frame.tag]
|
|
247
|
+
assert not isinstance(rule, _Skip | Raw) # noqa: S101 - skipped and raw elements never get a frame
|
|
248
|
+
parent.children.append((frame.tag, rule(frame, strict=self._strict)))
|
|
249
|
+
|
|
250
|
+
def finish(self) -> R:
|
|
251
|
+
"""Return the root object once parsing has stopped or the document has ended."""
|
|
252
|
+
if self.result is not None:
|
|
253
|
+
if self._strict and self._grammar is not None and not self.stopped:
|
|
254
|
+
raise ParseError(f"<{self._grammar.root}> has no <{self._grammar.stop_at}> element")
|
|
255
|
+
return self.result
|
|
256
|
+
if self._grammar is None or len(self._stack) != 1: # pragma: no cover - expat guarantees a closed root
|
|
257
|
+
raise ParseError("document ended without a complete root element")
|
|
258
|
+
self.result = self._grammar.build_root(self._stack[0], strict=self._strict)
|
|
259
|
+
return self.result
|