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/_source.py ADDED
@@ -0,0 +1,192 @@
1
+ """Opening any supported input as a binary stream of Model Description XML.
2
+
3
+ Supported inputs:
4
+
5
+ - a path to a ``.fmu`` zip (any extension; detected by magic bytes),
6
+ - a path to an unzipped FMU directory,
7
+ - a path to a ``modelDescription.xml`` file,
8
+ - a binary file-like object holding a zip or raw XML,
9
+ - ``bytes``, ``bytearray`` or ``memoryview`` holding a zip or raw XML.
10
+
11
+ Zip entries are streamed straight out of the archive; nothing is extracted to disk.
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ import io
17
+ import os
18
+ import zipfile
19
+ import zlib
20
+ from collections.abc import Generator
21
+ from contextlib import contextmanager
22
+ from typing import IO, Protocol, Union, cast
23
+
24
+ from mdxml._errors import ParseError, UnsafeInput
25
+
26
+ MODEL_DESCRIPTION = "modelDescription.xml"
27
+
28
+ # Local file header, and end of central directory (an empty archive).
29
+ _ZIP_MAGIC = (b"PK\x03\x04", b"PK\x05\x06")
30
+ _MAGIC_LENGTH = 4
31
+
32
+
33
+ class Readable(Protocol):
34
+ """A binary stream: anything with ``read(size) -> bytes``.
35
+
36
+ Zipped input additionally needs ``seekable()``, ``seek()`` and ``tell()``.
37
+ """
38
+
39
+ def read(self, size: int = -1, /) -> bytes: ...
40
+
41
+
42
+ Source = Union[str, "os.PathLike[str]", bytes, bytearray, memoryview, Readable]
43
+ """Anything :func:`mdxml.read_header` and friends accept as input."""
44
+
45
+
46
+ class _Prefixed:
47
+ """A forward-only stream that replays bytes already read for sniffing, then continues."""
48
+
49
+ __slots__ = ("_prefix", "_rest")
50
+
51
+ def __init__(self, prefix: bytes, rest: Readable) -> None:
52
+ self._prefix = prefix
53
+ self._rest = rest
54
+
55
+ def read(self, size: int = -1, /) -> bytes:
56
+ if not self._prefix:
57
+ return self._rest.read(size)
58
+ if size < 0:
59
+ data, self._prefix = self._prefix + self._rest.read(), b""
60
+ return data
61
+ data, self._prefix = self._prefix[:size], self._prefix[size:]
62
+ return data
63
+
64
+
65
+ class _ZipEntry:
66
+ """A zip entry stream that reports corrupt archive data as :class:`ParseError`.
67
+
68
+ zipfile only notices some corruption (a bad CRC, a broken deflate stream, an
69
+ entry longer or shorter than its header claims) while reading, so the
70
+ translation has to happen here rather than when the entry is opened.
71
+ """
72
+
73
+ __slots__ = ("_entry", "_name", "_origin")
74
+
75
+ def __init__(self, entry: Readable, name: str, origin: str) -> None:
76
+ self._entry = entry
77
+ self._name = name
78
+ self._origin = origin
79
+
80
+ def read(self, size: int = -1, /) -> bytes:
81
+ try:
82
+ return self._entry.read(size)
83
+ except (zipfile.BadZipFile, zlib.error, EOFError) as exc:
84
+ raise ParseError(f"corrupt zip data in {self._name!r} in {self._origin}: {exc}") from None
85
+
86
+
87
+ def _is_zip(prefix: bytes) -> bool:
88
+ return prefix.startswith(_ZIP_MAGIC)
89
+
90
+
91
+ def _is_seekable(stream: Readable) -> bool:
92
+ seekable = getattr(stream, "seekable", None)
93
+ return bool(seekable()) if callable(seekable) else False
94
+
95
+
96
+ def _read_prefix(stream: Readable) -> bytes:
97
+ prefix: object = stream.read(_MAGIC_LENGTH)
98
+ if not isinstance(prefix, bytes): # pyright: ignore[reportUnnecessaryIsInstance] - text streams lie about their type
99
+ raise TypeError(
100
+ f"expected a binary stream, got one returning {type(prefix).__name__}; open the file in 'rb' mode"
101
+ )
102
+ return prefix
103
+
104
+
105
+ def _reject_member(member: str | None, origin: str) -> None:
106
+ if member is not None:
107
+ raise ValueError(f"member={member!r} only applies to zip archives and directories, but {origin} is raw XML")
108
+
109
+
110
+ @contextmanager
111
+ def _zip_member(
112
+ stream: IO[bytes], member: str | None, origin: str, max_xml_bytes: int
113
+ ) -> Generator[Readable, None, None]:
114
+ name = member if member is not None else MODEL_DESCRIPTION
115
+ try:
116
+ archive = zipfile.ZipFile(stream)
117
+ except zipfile.BadZipFile as exc:
118
+ raise ParseError(f"{origin} looks like a zip archive but can't be opened: {exc}") from None
119
+ with archive:
120
+ try:
121
+ info = archive.getinfo(name)
122
+ except KeyError:
123
+ raise FileNotFoundError(f"{name!r} not found in {origin}") from None
124
+ # Cheap early rejection. zipfile never yields more than file_size bytes for an entry,
125
+ # and the reader counts the bytes it actually gets, so a lying header can't get past either.
126
+ if info.file_size > max_xml_bytes:
127
+ raise UnsafeInput(
128
+ f"{name!r} in {origin} decompresses to {info.file_size} bytes, more than max_xml_bytes={max_xml_bytes}"
129
+ )
130
+ try:
131
+ entry = archive.open(info)
132
+ except (zipfile.BadZipFile, NotImplementedError, RuntimeError) as exc:
133
+ # Bad local header, unsupported compression method, or an encrypted entry.
134
+ raise ParseError(f"can't read {name!r} in {origin}: {exc}") from None
135
+ with entry:
136
+ yield _ZipEntry(entry, name, origin)
137
+
138
+
139
+ @contextmanager
140
+ def _open_stream(
141
+ stream: Readable, member: str | None, origin: str, max_xml_bytes: int
142
+ ) -> Generator[Readable, None, None]:
143
+ if _is_seekable(stream):
144
+ seekable = cast(IO[bytes], stream)
145
+ start = seekable.tell()
146
+ prefix = _read_prefix(stream)
147
+ seekable.seek(start)
148
+ if _is_zip(prefix):
149
+ with _zip_member(seekable, member, origin, max_xml_bytes) as entry:
150
+ yield entry
151
+ return
152
+ _reject_member(member, origin)
153
+ yield stream
154
+ return
155
+
156
+ prefix = _read_prefix(stream)
157
+ if _is_zip(prefix):
158
+ raise TypeError(
159
+ f"{origin} is a zip archive in a stream that can't be rewound; "
160
+ "zipped input needs a seekable stream (e.g. io.BytesIO or a regular file)"
161
+ )
162
+ _reject_member(member, origin)
163
+ yield _Prefixed(prefix, stream)
164
+
165
+
166
+ @contextmanager
167
+ def open_source(src: Source, member: str | None, max_xml_bytes: int) -> Generator[Readable, None, None]:
168
+ """Yield a binary stream of the Model Description XML in ``src``.
169
+
170
+ Only the Model Description is opened; no other archive member is read.
171
+ Streams passed in by the caller are never closed. Files mdxml opens itself are.
172
+ """
173
+ if isinstance(src, (bytes, bytearray, memoryview)):
174
+ with _open_stream(io.BytesIO(src), member, "the given bytes", max_xml_bytes) as stream:
175
+ yield stream
176
+ return
177
+
178
+ if isinstance(src, (str, os.PathLike)):
179
+ path = os.fspath(src)
180
+ if os.path.isdir(path):
181
+ path = os.path.join(path, member if member is not None else MODEL_DESCRIPTION)
182
+ if not os.path.isfile(path):
183
+ raise FileNotFoundError(f"{path!r} not found in FMU directory {os.fspath(src)!r}")
184
+ member = None
185
+ with open(path, "rb") as file, _open_stream(file, member, repr(path), max_xml_bytes) as stream:
186
+ yield stream
187
+ return
188
+
189
+ if not callable(getattr(src, "read", None)):
190
+ raise TypeError(f"can't read a Model Description from {type(src).__name__}")
191
+ with _open_stream(src, member, "the given stream", max_xml_bytes) as stream:
192
+ yield stream
mdxml/_variables.py ADDED
@@ -0,0 +1,426 @@
1
+ """Streaming Model Variables: one pass that builds the Model Header, then yields variables one at a time.
2
+
3
+ Expat pushes events while :func:`iter_variables` has to be pulled from, so the
4
+ iterator feeds expat one chunk at a time and hands out the variables that
5
+ chunk completed before reading the next one. Memory therefore stays bounded
6
+ by the chunk size, however many variables the FMU has. Parsing stops at
7
+ ``</ModelVariables>``; the Model Structure is never read.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import os
13
+ from collections import deque
14
+ from collections.abc import Callable, Generator, Iterable, Mapping
15
+ from contextlib import ExitStack
16
+ from enum import Enum
17
+ from types import TracebackType
18
+ from typing import Any
19
+
20
+ from mdxml import _reader
21
+ from mdxml._errors import ParseError
22
+ from mdxml._grammar import Grammar, TreeHandler
23
+ from mdxml._header import AnyModelHeader, header_grammar_chooser
24
+ from mdxml._schema import Frame
25
+ from mdxml._source import Source, open_source
26
+ from mdxml.fmi2 import _structure as fmi2_structure
27
+ from mdxml.fmi2 import _variables as fmi2_variables
28
+ from mdxml.fmi2._header import ModelHeader as Fmi2ModelHeader
29
+ from mdxml.fmi2._variables import Variable as Fmi2Variable
30
+ from mdxml.fmi3 import _annotations as fmi3_annotations
31
+ from mdxml.fmi3 import _structure as fmi3_structure
32
+ from mdxml.fmi3 import _variables as fmi3_variables
33
+ from mdxml.fmi3._variables import Variable as Fmi3Variable
34
+
35
+ AnyVariable = Fmi2Variable | Fmi3Variable
36
+ """A Model Variable of any supported FMI Version."""
37
+
38
+ FilterValues = Callable[[str, Mapping[str, str]], tuple[str, str]]
39
+ """Gives a variable's causality and variability from its element name and raw attributes."""
40
+
41
+ Selector = str | Iterable[str] | None
42
+ """A filter value: one value, several, or ``None`` for no filtering."""
43
+
44
+ MODEL_VARIABLES = "ModelVariables"
45
+ MODEL_STRUCTURE = "ModelStructure"
46
+ ANNOTATIONS = "Annotations"
47
+
48
+
49
+ def _selector(value: Selector) -> frozenset[str] | None:
50
+ if value is None:
51
+ return None
52
+ values = [value] if isinstance(value, str) else list(value)
53
+ # Enum members hash by name, not value, so compare on their string values.
54
+ return frozenset(str(v.value) if isinstance(v, Enum) else str(v) for v in values)
55
+
56
+
57
+ class VariableFilter:
58
+ """Decides from a variable's raw attributes whether to build it at all."""
59
+
60
+ __slots__ = ("_causality", "_name_prefix", "_variability")
61
+
62
+ def __init__(self, *, causality: Selector, variability: Selector, name_prefix: str | None) -> None:
63
+ self._causality = _selector(causality)
64
+ self._variability = _selector(variability)
65
+ self._name_prefix = name_prefix
66
+
67
+ @property
68
+ def active(self) -> bool:
69
+ return self._causality is not None or self._variability is not None or self._name_prefix is not None
70
+
71
+ def matches(self, element: str, attrs: dict[str, str], values: FilterValues) -> bool:
72
+ if self._name_prefix is not None and not attrs.get("name", "").startswith(self._name_prefix):
73
+ return False
74
+ if self._causality is None and self._variability is None:
75
+ return True
76
+ causality, variability = values(element, attrs)
77
+ if self._causality is not None and causality not in self._causality:
78
+ return False
79
+ return self._variability is None or variability in self._variability
80
+
81
+
82
+ class _VariablesHandler:
83
+ """Builds the Model Header, then each Model Variable as its element closes.
84
+
85
+ With ``read_structure`` (used by :func:`mdxml.read`) it keeps going after
86
+ ``</ModelVariables>`` and builds the root's remaining children it has a
87
+ grammar for: the Model Structure and, with ``annotations``, FMI 3's
88
+ model-level ``<Annotations>``.
89
+ """
90
+
91
+ __slots__ = (
92
+ "_after_grammars",
93
+ "_after_handler",
94
+ "_after_skipped",
95
+ "_after_variables",
96
+ "_annotations",
97
+ "_filter",
98
+ "_filter_values",
99
+ "_grammars",
100
+ "_header_handler",
101
+ "_in_after",
102
+ "_in_variable",
103
+ "_index",
104
+ "_position",
105
+ "_read_structure",
106
+ "_skip_depth",
107
+ "_strict",
108
+ "_variable_handler",
109
+ "after",
110
+ "done",
111
+ "header",
112
+ "pending",
113
+ )
114
+
115
+ def __init__(
116
+ self,
117
+ position: list[_reader.Position],
118
+ *,
119
+ strict: bool,
120
+ variable_filter: VariableFilter,
121
+ read_structure: bool = False,
122
+ annotations: bool = False,
123
+ ) -> None:
124
+ self._position = position
125
+ self._strict = strict
126
+ self._annotations = annotations
127
+ self._read_structure = read_structure
128
+ self._filter = variable_filter if variable_filter.active else None
129
+ self._header_handler = TreeHandler(header_grammar_chooser(annotations=annotations), position, strict=strict)
130
+ self._variable_handler: TreeHandler[Any] | None = None
131
+ self._grammars: Mapping[str, Grammar[Any]] = {}
132
+ self._filter_values: FilterValues = fmi2_variables.filter_values
133
+ self._in_variable = False
134
+ self._index = 0
135
+ self._skip_depth = 0
136
+ self._after_variables = False
137
+ self._after_handler: TreeHandler[Any] | None = None
138
+ self._after_grammars: Mapping[str, Grammar[Any]] = {}
139
+ self._after_skipped: frozenset[str] = frozenset()
140
+ self._in_after = False
141
+ self.after: dict[str, Any] = {}
142
+ """What was built after ``</ModelVariables>``, keyed by root child element name."""
143
+ self.header: AnyModelHeader | None = None
144
+ self.pending: deque[AnyVariable] = deque()
145
+ self.done = False
146
+
147
+ def start(self, name: str, attrs: dict[str, str]) -> None:
148
+ """Open an element."""
149
+ if self.header is None:
150
+ if name == MODEL_VARIABLES and self._header_handler.at_root_level:
151
+ self.header = self._header_handler.stop_here()
152
+ self._enter_model_variables(self.header)
153
+ else:
154
+ self._header_handler.start(name, attrs)
155
+ return
156
+ if self._skip_depth:
157
+ self._skip_depth += 1
158
+ return
159
+ if self._after_variables:
160
+ self._start_after_variables(name, attrs)
161
+ return
162
+ if self._in_variable:
163
+ assert self._variable_handler is not None # noqa: S101 - set on entering ModelVariables
164
+ self._variable_handler.start(name, attrs)
165
+ return
166
+ # A direct child of <ModelVariables>.
167
+ if name not in self._grammars:
168
+ if self._strict:
169
+ pos = self._position[0]
170
+ raise ParseError(f"unknown element <{name}> in <{MODEL_VARIABLES}>", line=pos.line, column=pos.column)
171
+ self._skip_depth = 1
172
+ return
173
+ self._index += 1
174
+ if self._filter is not None and not self._filter.matches(name, attrs, self._filter_values):
175
+ self._skip_depth = 1 # skipped variables are never turned into objects
176
+ return
177
+ assert self._variable_handler is not None # noqa: S101 - set on entering ModelVariables
178
+ self._in_variable = True
179
+ self._variable_handler.reset()
180
+ self._variable_handler.start(name, attrs)
181
+
182
+ def end(self, name: str) -> None:
183
+ """Close an element; a closing variable is built and queued."""
184
+ if self.header is None:
185
+ self._header_handler.end(name)
186
+ return
187
+ if self._skip_depth:
188
+ self._skip_depth -= 1
189
+ return
190
+ if self._after_variables:
191
+ self._end_after_variables(name)
192
+ return
193
+ if self._in_variable:
194
+ assert self._variable_handler is not None # noqa: S101
195
+ self._variable_handler.end(name)
196
+ if self._variable_handler.result is not None:
197
+ cls, fields = self._variable_handler.result
198
+ self.pending.append(cls(index=self._index, **fields))
199
+ self._in_variable = False
200
+ return
201
+ if self._read_structure:
202
+ self._after_variables = True # keep reading: the Model Structure comes next
203
+ return
204
+ # </ModelVariables>: nothing after it is needed.
205
+ self.done = True
206
+ raise _reader.Stop
207
+
208
+ def _start_after_variables(self, name: str, attrs: dict[str, str]) -> None:
209
+ """Open an element after ``</ModelVariables>``."""
210
+ if self._in_after:
211
+ assert self._after_handler is not None # noqa: S101 - set on entering ModelVariables
212
+ self._after_handler.start(name, attrs)
213
+ return
214
+ # A direct child of the root.
215
+ if name in self._after_grammars:
216
+ if name not in self.after:
217
+ assert self._after_handler is not None # noqa: S101
218
+ self._in_after = True
219
+ self._after_handler.reset()
220
+ self._after_handler.start(name, attrs)
221
+ return
222
+ if self._strict:
223
+ pos = self._position[0]
224
+ raise ParseError(f"more than one <{name}> element", line=pos.line, column=pos.column)
225
+ elif name not in self._after_skipped and self._strict:
226
+ pos = self._position[0]
227
+ raise ParseError(f"unexpected element <{name}> after <{MODEL_VARIABLES}>", line=pos.line, column=pos.column)
228
+ self._skip_depth = 1 # a known element not wanted here, or (lenient) a duplicate or unknown one
229
+
230
+ def _end_after_variables(self, name: str) -> None:
231
+ """Close an element after ``</ModelVariables>``; the root closing ends the document."""
232
+ if self._in_after:
233
+ assert self._after_handler is not None # noqa: S101
234
+ self._after_handler.end(name)
235
+ if self._after_handler.result is not None:
236
+ self.after[name] = self._after_handler.result
237
+ self._in_after = False
238
+ return
239
+ self.done = True
240
+ raise _reader.Stop
241
+
242
+ def finish(self) -> AnyModelHeader:
243
+ """Return the Model Header once the document has ended without ``<ModelVariables>``."""
244
+ if self.header is None:
245
+ self.header = self._header_handler.finish()
246
+ return self.header
247
+
248
+ def _enter_model_variables(self, header: AnyModelHeader) -> None:
249
+ after: dict[str, Grammar[Any]]
250
+ if isinstance(header, Fmi2ModelHeader):
251
+ self._grammars = (
252
+ fmi2_variables.VARIABLE_GRAMMARS_WITH_ANNOTATIONS
253
+ if self._annotations
254
+ else fmi2_variables.VARIABLE_GRAMMARS
255
+ )
256
+ self._filter_values = fmi2_variables.filter_values
257
+ after = {MODEL_STRUCTURE: fmi2_structure.STRUCTURE_GRAMMAR}
258
+ known_after = fmi2_structure.AFTER_MODEL_STRUCTURE
259
+ else:
260
+ self._grammars = (
261
+ fmi3_variables.VARIABLE_GRAMMARS_WITH_ANNOTATIONS
262
+ if self._annotations
263
+ else fmi3_variables.VARIABLE_GRAMMARS
264
+ )
265
+ self._filter_values = fmi3_variables.filter_values
266
+ after = {MODEL_STRUCTURE: fmi3_structure.STRUCTURE_GRAMMAR}
267
+ if self._annotations:
268
+ after[ANNOTATIONS] = fmi3_annotations.MODEL_ANNOTATIONS_GRAMMAR
269
+ known_after = fmi3_structure.AFTER_MODEL_STRUCTURE
270
+ self._variable_handler = TreeHandler(self._choose_variable_grammar, self._position, strict=self._strict)
271
+ if self._read_structure:
272
+ self._after_grammars = after
273
+ self._after_skipped = known_after - after.keys()
274
+ self._after_handler = TreeHandler(self._choose_after_grammar, self._position, strict=self._strict)
275
+
276
+ def _choose_variable_grammar(self, root: Frame) -> Grammar[Any]:
277
+ return self._grammars[root.tag]
278
+
279
+ def _choose_after_grammar(self, root: Frame) -> Grammar[Any]:
280
+ return self._after_grammars[root.tag]
281
+
282
+
283
+ class VariableIterator:
284
+ """Iterator over an FMU's Model Variables, read in a single streaming pass.
285
+
286
+ :attr:`header` gives the Model Header from the same pass. The source is
287
+ opened on first use and closed when iteration ends or fails; use the
288
+ iterator in a ``with`` block (or call :meth:`close`) to close it early.
289
+ """
290
+
291
+ __slots__ = ("_handler", "_max_xml_bytes", "_member", "_position", "_resources", "_src", "_steps", "_strict")
292
+
293
+ def __init__(
294
+ self,
295
+ src: Source,
296
+ *,
297
+ member: str | None,
298
+ strict: bool,
299
+ max_xml_bytes: int,
300
+ variable_filter: VariableFilter,
301
+ read_structure: bool = False,
302
+ annotations: bool = False,
303
+ ) -> None:
304
+ """Prepare the iterator; nothing is read until it's used."""
305
+ self._src = src
306
+ self._member = member
307
+ self._strict = strict
308
+ self._max_xml_bytes = max_xml_bytes
309
+ self._position: list[_reader.Position] = []
310
+ self._handler = _VariablesHandler(
311
+ self._position,
312
+ strict=strict,
313
+ variable_filter=variable_filter,
314
+ read_structure=read_structure,
315
+ annotations=annotations,
316
+ )
317
+ self._resources = ExitStack()
318
+ self._steps: Generator[None, None, None] | None = None
319
+
320
+ def __iter__(self) -> VariableIterator:
321
+ """Return the iterator itself."""
322
+ return self
323
+
324
+ def __next__(self) -> AnyVariable:
325
+ """Return the next Model Variable."""
326
+ pending = self._handler.pending
327
+ # The last chunk can both finish the document and queue variables, so only stop when
328
+ # there's nothing left to read *and* nothing queued.
329
+ while not pending:
330
+ if not self._advance() and not pending:
331
+ raise StopIteration
332
+ return pending.popleft()
333
+
334
+ @property
335
+ def header(self) -> AnyModelHeader:
336
+ """The Model Header, read (if it hasn't been yet) without consuming any variables."""
337
+ while self._handler.header is None and self._advance():
338
+ pass
339
+ return self._handler.finish()
340
+
341
+ @property
342
+ def model_structure(self) -> Any:
343
+ """The Model Structure, once iteration has finished (only when created by :func:`mdxml.read`)."""
344
+ return self._handler.after.get(MODEL_STRUCTURE)
345
+
346
+ @property
347
+ def model_annotations(self) -> Any:
348
+ """FMI 3's model-level annotations, once iteration has finished (only via :func:`mdxml.read`)."""
349
+ return self._handler.after.get(ANNOTATIONS)
350
+
351
+ def close(self) -> None:
352
+ """Stop reading and close the source."""
353
+ self._resources.close()
354
+ if self._steps is not None:
355
+ self._steps.close()
356
+
357
+ def __enter__(self) -> VariableIterator:
358
+ """Use the iterator as a context manager that closes the source on exit."""
359
+ return self
360
+
361
+ def __exit__(
362
+ self, exc_type: type[BaseException] | None, exc: BaseException | None, traceback: TracebackType | None
363
+ ) -> None:
364
+ """Close the source."""
365
+ self.close()
366
+
367
+ def _advance(self) -> bool:
368
+ """Parse one more chunk. Return ``False`` once there's nothing left to read."""
369
+ if self._handler.done:
370
+ self.close()
371
+ return False
372
+ try:
373
+ if self._steps is None:
374
+ stream = self._resources.enter_context(open_source(self._src, self._member, self._max_xml_bytes))
375
+ self._steps = _reader.feed(stream, self._handler, self._position, max_xml_bytes=self._max_xml_bytes)
376
+ next(self._steps)
377
+ except StopIteration:
378
+ self.close()
379
+ self._handler.finish()
380
+ return False
381
+ except BaseException:
382
+ self.close()
383
+ raise
384
+ return True
385
+
386
+
387
+ def iter_variables(
388
+ src: Source,
389
+ *,
390
+ causality: Selector = None,
391
+ variability: Selector = None,
392
+ name_prefix: str | None = None,
393
+ member: str | None = None,
394
+ strict: bool = False,
395
+ annotations: bool = False,
396
+ max_xml_bytes: int = _reader.DEFAULT_MAX_XML_BYTES,
397
+ ) -> VariableIterator:
398
+ """Stream an FMU's Model Variables one at a time, in file order.
399
+
400
+ ``src``, ``member``, ``strict`` and ``max_xml_bytes`` work as for
401
+ :func:`mdxml.read_header`. Memory use doesn't grow with the number of
402
+ variables, and nothing after ``</ModelVariables>`` is read.
403
+
404
+ ``causality`` and ``variability`` (one value or several) and
405
+ ``name_prefix`` keep only matching variables. They're checked against the
406
+ raw attributes before a variable is built, so skipped variables cost
407
+ almost nothing; Variable Indexes still count every variable.
408
+
409
+ With ``annotations=True``, each variable's ``annotations`` holds its Tool
410
+ Annotations as raw XML (and so does an FMI 2 header's
411
+ ``vendor_annotations``); otherwise they're skipped and left as ``None``.
412
+
413
+ The returned iterator's ``.header`` is the Model Header from the same pass.
414
+ """
415
+ _reader.check_max_xml_bytes(max_xml_bytes)
416
+ if isinstance(src, (str, os.PathLike)) and not os.path.exists(src):
417
+ raise FileNotFoundError(f"no such file or directory: {os.fspath(src)!r}")
418
+ variable_filter = VariableFilter(causality=causality, variability=variability, name_prefix=name_prefix)
419
+ return VariableIterator(
420
+ src,
421
+ member=member,
422
+ strict=strict,
423
+ max_xml_bytes=max_xml_bytes,
424
+ variable_filter=variable_filter,
425
+ annotations=annotations,
426
+ )
mdxml/fmi2/__init__.py ADDED
@@ -0,0 +1,73 @@
1
+ """FMI 2.0 Model Description types, mirroring the FMI 2.0 XSD."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from mdxml.fmi2._annotations import ToolAnnotation
6
+ from mdxml.fmi2._header import (
7
+ BaseUnit,
8
+ BooleanType,
9
+ Category,
10
+ CoSimulation,
11
+ DefaultExperiment,
12
+ DisplayUnit,
13
+ EnumerationType,
14
+ IntegerType,
15
+ Item,
16
+ ModelExchange,
17
+ ModelHeader,
18
+ RealType,
19
+ StringType,
20
+ TypeDefinition,
21
+ Unit,
22
+ VariableNamingConvention,
23
+ )
24
+ from mdxml.fmi2._model import ModelDescription
25
+ from mdxml.fmi2._structure import DependenciesKind, ModelStructure, Unknown
26
+ from mdxml.fmi2._variables import (
27
+ BooleanVariable,
28
+ Causality,
29
+ EnumerationVariable,
30
+ Initial,
31
+ IntegerVariable,
32
+ RealVariable,
33
+ ScalarVariable,
34
+ StringVariable,
35
+ Variability,
36
+ Variable,
37
+ default_initial,
38
+ )
39
+
40
+ __all__ = [
41
+ "BaseUnit",
42
+ "BooleanType",
43
+ "BooleanVariable",
44
+ "Category",
45
+ "Causality",
46
+ "CoSimulation",
47
+ "DefaultExperiment",
48
+ "DependenciesKind",
49
+ "DisplayUnit",
50
+ "EnumerationType",
51
+ "EnumerationVariable",
52
+ "Initial",
53
+ "IntegerType",
54
+ "IntegerVariable",
55
+ "Item",
56
+ "ModelDescription",
57
+ "ModelExchange",
58
+ "ModelHeader",
59
+ "ModelStructure",
60
+ "RealType",
61
+ "RealVariable",
62
+ "ScalarVariable",
63
+ "StringType",
64
+ "StringVariable",
65
+ "ToolAnnotation",
66
+ "TypeDefinition",
67
+ "Unit",
68
+ "Unknown",
69
+ "Variability",
70
+ "Variable",
71
+ "VariableNamingConvention",
72
+ "default_initial",
73
+ ]