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 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
@@ -0,0 +1,5 @@
1
+ """Run the mdxml command-line tool: ``python -m mdxml``."""
2
+
3
+ from mdxml._cli import main
4
+
5
+ raise SystemExit(main())
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