mdxml 0.1.0__tar.gz
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-0.1.0/LICENSE +21 -0
- mdxml-0.1.0/PKG-INFO +202 -0
- mdxml-0.1.0/README.md +176 -0
- mdxml-0.1.0/pyproject.toml +148 -0
- mdxml-0.1.0/pyproject.toml.orig +108 -0
- mdxml-0.1.0/src/mdxml/__init__.py +39 -0
- mdxml-0.1.0/src/mdxml/__main__.py +5 -0
- mdxml-0.1.0/src/mdxml/_cli.py +96 -0
- mdxml-0.1.0/src/mdxml/_convert.py +151 -0
- mdxml-0.1.0/src/mdxml/_dict.py +42 -0
- mdxml-0.1.0/src/mdxml/_errors.py +39 -0
- mdxml-0.1.0/src/mdxml/_grammar.py +259 -0
- mdxml-0.1.0/src/mdxml/_header.py +92 -0
- mdxml-0.1.0/src/mdxml/_lookup.py +54 -0
- mdxml-0.1.0/src/mdxml/_protocols.py +135 -0
- mdxml-0.1.0/src/mdxml/_read.py +75 -0
- mdxml-0.1.0/src/mdxml/_reader.py +191 -0
- mdxml-0.1.0/src/mdxml/_schema.py +131 -0
- mdxml-0.1.0/src/mdxml/_source.py +192 -0
- mdxml-0.1.0/src/mdxml/_variables.py +426 -0
- mdxml-0.1.0/src/mdxml/fmi2/__init__.py +73 -0
- mdxml-0.1.0/src/mdxml/fmi2/_annotations.py +34 -0
- mdxml-0.1.0/src/mdxml/fmi2/_header.py +525 -0
- mdxml-0.1.0/src/mdxml/fmi2/_model.py +73 -0
- mdxml-0.1.0/src/mdxml/fmi2/_structure.py +100 -0
- mdxml-0.1.0/src/mdxml/fmi2/_variables.py +323 -0
- mdxml-0.1.0/src/mdxml/fmi3/__init__.py +125 -0
- mdxml-0.1.0/src/mdxml/fmi3/_annotations.py +43 -0
- mdxml-0.1.0/src/mdxml/fmi3/_header.py +635 -0
- mdxml-0.1.0/src/mdxml/fmi3/_model.py +59 -0
- mdxml-0.1.0/src/mdxml/fmi3/_structure.py +103 -0
- mdxml-0.1.0/src/mdxml/fmi3/_variables.py +603 -0
- mdxml-0.1.0/src/mdxml/py.typed +0 -0
mdxml-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 hyumo
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
mdxml-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: mdxml
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Fast, zero-dependency, streaming parser for FMI 2.0 and 3.0 modelDescription.xml files
|
|
5
|
+
Keywords: fmi,fmu,modelDescription,xml,parser,co-simulation
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
License-File: LICENSE
|
|
8
|
+
Classifier: Development Status :: 2 - Pre-Alpha
|
|
9
|
+
Classifier: Intended Audience :: Developers
|
|
10
|
+
Classifier: Intended Audience :: Science/Research
|
|
11
|
+
Classifier: Operating System :: OS Independent
|
|
12
|
+
Classifier: Programming Language :: Python :: 3
|
|
13
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
19
|
+
Classifier: Topic :: Scientific/Engineering
|
|
20
|
+
Classifier: Typing :: Typed
|
|
21
|
+
Requires-Python: >=3.10
|
|
22
|
+
Project-URL: Homepage, https://github.com/hyumo/mdxml
|
|
23
|
+
Project-URL: Issues, https://github.com/hyumo/mdxml/issues
|
|
24
|
+
Project-URL: Changelog, https://github.com/hyumo/mdxml/blob/master/CHANGELOG.md
|
|
25
|
+
Description-Content-Type: text/markdown
|
|
26
|
+
|
|
27
|
+
# mdxml
|
|
28
|
+
|
|
29
|
+
Fast, zero-dependency reader for the `modelDescription.xml` of FMI 2.0 and FMI 3.0 FMUs.
|
|
30
|
+
|
|
31
|
+
- **Read only what you need.** `read_header()` stops at `<ModelVariables>`, so it costs the same for 10 variables or 10 million. `iter_variables()` streams variables one at a time; `read()` loads everything.
|
|
32
|
+
- **Flat memory.** Streaming never holds the XML or more than one 64 KB chunk of it, however big the FMU is. That makes it safe to run on uploaded files in web backends, in parallel.
|
|
33
|
+
- **Safe on hostile input.** No `DOCTYPE`, no entities, no external resources, a size limit, and zip bombs are refused before they're decompressed.
|
|
34
|
+
- **Faithful, typed results.** Frozen dataclasses mirror the FMI XSDs field for field, with real Python types, the XSD's defaults and enums. They're fully type-hinted (`py.typed`).
|
|
35
|
+
- **Zero dependencies.** Pure standard library (`xml.parsers.expat`, `zipfile`). Python 3.10+ on any OS.
|
|
36
|
+
|
|
37
|
+
## Installation
|
|
38
|
+
|
|
39
|
+
```sh
|
|
40
|
+
pip install mdxml
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
## Usage
|
|
44
|
+
|
|
45
|
+
### The Model Header
|
|
46
|
+
|
|
47
|
+
```python
|
|
48
|
+
import mdxml
|
|
49
|
+
|
|
50
|
+
header = mdxml.read_header("BouncingBall.fmu")
|
|
51
|
+
print(header.model_name, header.fmi_version) # BouncingBall 3.0
|
|
52
|
+
print(header.co_simulation.model_identifier) # BouncingBall
|
|
53
|
+
print(header.unit_definitions["m/s"].base_unit) # look definitions up by name
|
|
54
|
+
print(header.default_experiment.stop_time) # 3.0
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
The Model Header is everything before `<ModelVariables>`: the root attributes, the interface types (Model Exchange, Co-Simulation, Scheduled Execution), units, type definitions, log categories and the default experiment. Parsing stops there, so the rest of the file is never read.
|
|
58
|
+
|
|
59
|
+
### Streaming Model Variables
|
|
60
|
+
|
|
61
|
+
```python
|
|
62
|
+
import mdxml
|
|
63
|
+
|
|
64
|
+
with mdxml.iter_variables("BouncingBall.fmu", causality="output") as variables:
|
|
65
|
+
print(variables.header.model_name) # the header comes from the same pass
|
|
66
|
+
for variable in variables:
|
|
67
|
+
print(variable.index, variable.name, variable.type_name, variable.start)
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
`causality=`, `variability=` (one value or several) and `name_prefix=` filter variables before they're built, so skipped variables cost almost nothing. Each variable keeps its Variable Index (its 1-based position in `ModelVariables`) even when others are filtered out. `effective_initial` gives the standard's default `initial` when the file doesn't set one.
|
|
71
|
+
|
|
72
|
+
### The whole Model Description
|
|
73
|
+
|
|
74
|
+
```python
|
|
75
|
+
import mdxml
|
|
76
|
+
|
|
77
|
+
md = mdxml.read("BouncingBall.fmu")
|
|
78
|
+
derivative = md.model_structure.continuous_state_derivatives[0]
|
|
79
|
+
print(md.variable_by_value_reference(derivative.value_reference).name) # der(h)
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
`read()` returns the header, every variable and the Model Structure from one pass. References are kept exactly as written; the `variable_by_name`, `variable_by_value_reference` and, for FMI 2, `variable_by_index` helpers look them up.
|
|
83
|
+
|
|
84
|
+
### Inputs
|
|
85
|
+
|
|
86
|
+
Every entry point accepts:
|
|
87
|
+
|
|
88
|
+
- a path to a `.fmu` file (recognised by its content, not its extension),
|
|
89
|
+
- a path to an unzipped FMU directory,
|
|
90
|
+
- a path to a `modelDescription.xml` file,
|
|
91
|
+
- a binary file-like object, such as an upload in a web framework (zipped input needs a seekable one),
|
|
92
|
+
- `bytes`.
|
|
93
|
+
|
|
94
|
+
```python
|
|
95
|
+
import io
|
|
96
|
+
|
|
97
|
+
import mdxml
|
|
98
|
+
|
|
99
|
+
with open("BouncingBall.fmu", "rb") as upload:
|
|
100
|
+
data = upload.read()
|
|
101
|
+
|
|
102
|
+
assert mdxml.read_header(io.BytesIO(data)) == mdxml.read_header(data)
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
Zips are read in place, and nothing is extracted to disk. Use `member=` for an FMU whose Model Description isn't at the standard `modelDescription.xml`.
|
|
106
|
+
|
|
107
|
+
### FMI 2 and FMI 3
|
|
108
|
+
|
|
109
|
+
Results are version-specific types (`mdxml.fmi2.*` or `mdxml.fmi3.*`) that mirror their XSD. Code that doesn't care about the version can use the shared Protocols, which both versions' classes satisfy:
|
|
110
|
+
|
|
111
|
+
```python
|
|
112
|
+
import mdxml
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
def describe(header: mdxml.ModelHeader, variable: mdxml.ModelVariable) -> str:
|
|
116
|
+
return f"{header.model_name} ({header.instantiation_token}): {variable.name} is a {variable.causality}"
|
|
117
|
+
|
|
118
|
+
|
|
119
|
+
variables = mdxml.iter_variables("BouncingBall.fmu")
|
|
120
|
+
print(describe(variables.header, next(variables)))
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
FMI 2's `guid` is also available as `instantiation_token`. To use version-specific fields, check the type first, e.g. `isinstance(header, mdxml.fmi2.ModelHeader)`.
|
|
124
|
+
|
|
125
|
+
### Lenient by default, strict when asked
|
|
126
|
+
|
|
127
|
+
Real-world FMUs often bend the schema a little, so by default unknown elements and attributes are ignored, booleans may be written in any case, unknown enum values stay plain strings, and optional values that can't be read keep their default. With `strict=True`, all of those raise `mdxml.ParseError` (with line and column), as do missing required attributes.
|
|
128
|
+
|
|
129
|
+
```python
|
|
130
|
+
import mdxml
|
|
131
|
+
|
|
132
|
+
mdxml.read("BouncingBall.fmu", strict=True)
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
### Annotations
|
|
136
|
+
|
|
137
|
+
Tool annotations are skipped by default at no cost. With `annotations=True`, they're kept as their exact raw XML (`fmi2.ToolAnnotation(name, xml)`, `fmi3.Annotation(type, xml)`) for you to parse:
|
|
138
|
+
|
|
139
|
+
```python
|
|
140
|
+
import mdxml
|
|
141
|
+
|
|
142
|
+
md = mdxml.read("BouncingBall.fmu", annotations=True)
|
|
143
|
+
print(md.annotations) # model-level annotations (FMI 3); () when there are none
|
|
144
|
+
print(md.variables[0].annotations)
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
### JSON
|
|
148
|
+
|
|
149
|
+
```python
|
|
150
|
+
import json
|
|
151
|
+
|
|
152
|
+
import mdxml
|
|
153
|
+
|
|
154
|
+
print(json.dumps(mdxml.to_dict(mdxml.read_header("BouncingBall.fmu")), indent=2))
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
`to_dict()` turns any result into JSON-ready data: enums become strings, `bytes` become hex, and infinities and NaN become `"INF"`, `"-INF"` and `"NaN"`.
|
|
158
|
+
|
|
159
|
+
### Concurrency
|
|
160
|
+
|
|
161
|
+
There's no shared state, and every result is immutable and picklable, so mdxml works from threads, process pools and free-threaded Python builds alike.
|
|
162
|
+
|
|
163
|
+
## Command line
|
|
164
|
+
|
|
165
|
+
```sh
|
|
166
|
+
mdxml header BouncingBall.fmu # the Model Header as JSON
|
|
167
|
+
mdxml variables BouncingBall.fmu --causality output # one JSON object per variable
|
|
168
|
+
mdxml variables model.fmu --name-prefix plant. --variability continuous --strict
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
Both commands take `--member`, `--strict`, `--annotations` and `--max-xml-bytes`. `python -m mdxml` works too.
|
|
172
|
+
|
|
173
|
+
## Safety defaults
|
|
174
|
+
|
|
175
|
+
These checks are always on, in lenient and strict mode alike:
|
|
176
|
+
|
|
177
|
+
- **No `DOCTYPE` or entity declarations.** They're refused at the first token, which blocks entity bombs (billion laughs) and external entities (XXE). Model Descriptions never need them.
|
|
178
|
+
- **A size limit.** `max_xml_bytes` defaults to 256 MB and can be changed per call. For zips it counts the *decompressed* size, and a zip entry claiming to be bigger is refused before it's opened.
|
|
179
|
+
- **Only the Model Description is read.** No other archive member is ever opened.
|
|
180
|
+
|
|
181
|
+
All three raise `mdxml.UnsafeInput`. Every error mdxml raises on purpose is an `mdxml.MdxmlError`.
|
|
182
|
+
|
|
183
|
+
## Performance
|
|
184
|
+
|
|
185
|
+
Against FMPy 0.3.32 on generated FMUs with a million variables (see [benchmarks/RESULTS.md](benchmarks/RESULTS.md)):
|
|
186
|
+
|
|
187
|
+
| 1M variables | `iter_variables` | `read` | FMPy `read_model_description` |
|
|
188
|
+
|---|---|---|---|
|
|
189
|
+
| FMI 2 | 8.1 s · < 1 MB | 10.2 s · 586 MB | 12.3 s · 3,177 MB (10.8 s without validation) |
|
|
190
|
+
| FMI 3 | 7.1 s · < 1 MB | 8.8 s · 555 MB | 11.1 s · 3,055 MB (9.4 s without validation) |
|
|
191
|
+
|
|
192
|
+
`read_header` takes about 0.5 ms at any size.
|
|
193
|
+
|
|
194
|
+
## Supported versions
|
|
195
|
+
|
|
196
|
+
- FMI 2.0 (schema v2.0.5) and FMI 3.0 (schema v3.0.2). FMI 1.0 raises `mdxml.UnsupportedFmiVersion`.
|
|
197
|
+
- Only `modelDescription.xml`. FMI 3's other XML files (build description, terminals and icons, layered-standard manifests) aren't read.
|
|
198
|
+
- Python 3.10 to 3.14 on Linux, macOS and Windows.
|
|
199
|
+
|
|
200
|
+
## License
|
|
201
|
+
|
|
202
|
+
MIT. The FMI XSDs in `schema/`, which are used only by the tests, are © Modelica Association Project "FMI" under the 2-Clause BSD license, and aren't part of the installed package.
|
mdxml-0.1.0/README.md
ADDED
|
@@ -0,0 +1,176 @@
|
|
|
1
|
+
# mdxml
|
|
2
|
+
|
|
3
|
+
Fast, zero-dependency reader for the `modelDescription.xml` of FMI 2.0 and FMI 3.0 FMUs.
|
|
4
|
+
|
|
5
|
+
- **Read only what you need.** `read_header()` stops at `<ModelVariables>`, so it costs the same for 10 variables or 10 million. `iter_variables()` streams variables one at a time; `read()` loads everything.
|
|
6
|
+
- **Flat memory.** Streaming never holds the XML or more than one 64 KB chunk of it, however big the FMU is. That makes it safe to run on uploaded files in web backends, in parallel.
|
|
7
|
+
- **Safe on hostile input.** No `DOCTYPE`, no entities, no external resources, a size limit, and zip bombs are refused before they're decompressed.
|
|
8
|
+
- **Faithful, typed results.** Frozen dataclasses mirror the FMI XSDs field for field, with real Python types, the XSD's defaults and enums. They're fully type-hinted (`py.typed`).
|
|
9
|
+
- **Zero dependencies.** Pure standard library (`xml.parsers.expat`, `zipfile`). Python 3.10+ on any OS.
|
|
10
|
+
|
|
11
|
+
## Installation
|
|
12
|
+
|
|
13
|
+
```sh
|
|
14
|
+
pip install mdxml
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## Usage
|
|
18
|
+
|
|
19
|
+
### The Model Header
|
|
20
|
+
|
|
21
|
+
```python
|
|
22
|
+
import mdxml
|
|
23
|
+
|
|
24
|
+
header = mdxml.read_header("BouncingBall.fmu")
|
|
25
|
+
print(header.model_name, header.fmi_version) # BouncingBall 3.0
|
|
26
|
+
print(header.co_simulation.model_identifier) # BouncingBall
|
|
27
|
+
print(header.unit_definitions["m/s"].base_unit) # look definitions up by name
|
|
28
|
+
print(header.default_experiment.stop_time) # 3.0
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
The Model Header is everything before `<ModelVariables>`: the root attributes, the interface types (Model Exchange, Co-Simulation, Scheduled Execution), units, type definitions, log categories and the default experiment. Parsing stops there, so the rest of the file is never read.
|
|
32
|
+
|
|
33
|
+
### Streaming Model Variables
|
|
34
|
+
|
|
35
|
+
```python
|
|
36
|
+
import mdxml
|
|
37
|
+
|
|
38
|
+
with mdxml.iter_variables("BouncingBall.fmu", causality="output") as variables:
|
|
39
|
+
print(variables.header.model_name) # the header comes from the same pass
|
|
40
|
+
for variable in variables:
|
|
41
|
+
print(variable.index, variable.name, variable.type_name, variable.start)
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
`causality=`, `variability=` (one value or several) and `name_prefix=` filter variables before they're built, so skipped variables cost almost nothing. Each variable keeps its Variable Index (its 1-based position in `ModelVariables`) even when others are filtered out. `effective_initial` gives the standard's default `initial` when the file doesn't set one.
|
|
45
|
+
|
|
46
|
+
### The whole Model Description
|
|
47
|
+
|
|
48
|
+
```python
|
|
49
|
+
import mdxml
|
|
50
|
+
|
|
51
|
+
md = mdxml.read("BouncingBall.fmu")
|
|
52
|
+
derivative = md.model_structure.continuous_state_derivatives[0]
|
|
53
|
+
print(md.variable_by_value_reference(derivative.value_reference).name) # der(h)
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
`read()` returns the header, every variable and the Model Structure from one pass. References are kept exactly as written; the `variable_by_name`, `variable_by_value_reference` and, for FMI 2, `variable_by_index` helpers look them up.
|
|
57
|
+
|
|
58
|
+
### Inputs
|
|
59
|
+
|
|
60
|
+
Every entry point accepts:
|
|
61
|
+
|
|
62
|
+
- a path to a `.fmu` file (recognised by its content, not its extension),
|
|
63
|
+
- a path to an unzipped FMU directory,
|
|
64
|
+
- a path to a `modelDescription.xml` file,
|
|
65
|
+
- a binary file-like object, such as an upload in a web framework (zipped input needs a seekable one),
|
|
66
|
+
- `bytes`.
|
|
67
|
+
|
|
68
|
+
```python
|
|
69
|
+
import io
|
|
70
|
+
|
|
71
|
+
import mdxml
|
|
72
|
+
|
|
73
|
+
with open("BouncingBall.fmu", "rb") as upload:
|
|
74
|
+
data = upload.read()
|
|
75
|
+
|
|
76
|
+
assert mdxml.read_header(io.BytesIO(data)) == mdxml.read_header(data)
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Zips are read in place, and nothing is extracted to disk. Use `member=` for an FMU whose Model Description isn't at the standard `modelDescription.xml`.
|
|
80
|
+
|
|
81
|
+
### FMI 2 and FMI 3
|
|
82
|
+
|
|
83
|
+
Results are version-specific types (`mdxml.fmi2.*` or `mdxml.fmi3.*`) that mirror their XSD. Code that doesn't care about the version can use the shared Protocols, which both versions' classes satisfy:
|
|
84
|
+
|
|
85
|
+
```python
|
|
86
|
+
import mdxml
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
def describe(header: mdxml.ModelHeader, variable: mdxml.ModelVariable) -> str:
|
|
90
|
+
return f"{header.model_name} ({header.instantiation_token}): {variable.name} is a {variable.causality}"
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
variables = mdxml.iter_variables("BouncingBall.fmu")
|
|
94
|
+
print(describe(variables.header, next(variables)))
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
FMI 2's `guid` is also available as `instantiation_token`. To use version-specific fields, check the type first, e.g. `isinstance(header, mdxml.fmi2.ModelHeader)`.
|
|
98
|
+
|
|
99
|
+
### Lenient by default, strict when asked
|
|
100
|
+
|
|
101
|
+
Real-world FMUs often bend the schema a little, so by default unknown elements and attributes are ignored, booleans may be written in any case, unknown enum values stay plain strings, and optional values that can't be read keep their default. With `strict=True`, all of those raise `mdxml.ParseError` (with line and column), as do missing required attributes.
|
|
102
|
+
|
|
103
|
+
```python
|
|
104
|
+
import mdxml
|
|
105
|
+
|
|
106
|
+
mdxml.read("BouncingBall.fmu", strict=True)
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
### Annotations
|
|
110
|
+
|
|
111
|
+
Tool annotations are skipped by default at no cost. With `annotations=True`, they're kept as their exact raw XML (`fmi2.ToolAnnotation(name, xml)`, `fmi3.Annotation(type, xml)`) for you to parse:
|
|
112
|
+
|
|
113
|
+
```python
|
|
114
|
+
import mdxml
|
|
115
|
+
|
|
116
|
+
md = mdxml.read("BouncingBall.fmu", annotations=True)
|
|
117
|
+
print(md.annotations) # model-level annotations (FMI 3); () when there are none
|
|
118
|
+
print(md.variables[0].annotations)
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
### JSON
|
|
122
|
+
|
|
123
|
+
```python
|
|
124
|
+
import json
|
|
125
|
+
|
|
126
|
+
import mdxml
|
|
127
|
+
|
|
128
|
+
print(json.dumps(mdxml.to_dict(mdxml.read_header("BouncingBall.fmu")), indent=2))
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
`to_dict()` turns any result into JSON-ready data: enums become strings, `bytes` become hex, and infinities and NaN become `"INF"`, `"-INF"` and `"NaN"`.
|
|
132
|
+
|
|
133
|
+
### Concurrency
|
|
134
|
+
|
|
135
|
+
There's no shared state, and every result is immutable and picklable, so mdxml works from threads, process pools and free-threaded Python builds alike.
|
|
136
|
+
|
|
137
|
+
## Command line
|
|
138
|
+
|
|
139
|
+
```sh
|
|
140
|
+
mdxml header BouncingBall.fmu # the Model Header as JSON
|
|
141
|
+
mdxml variables BouncingBall.fmu --causality output # one JSON object per variable
|
|
142
|
+
mdxml variables model.fmu --name-prefix plant. --variability continuous --strict
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
Both commands take `--member`, `--strict`, `--annotations` and `--max-xml-bytes`. `python -m mdxml` works too.
|
|
146
|
+
|
|
147
|
+
## Safety defaults
|
|
148
|
+
|
|
149
|
+
These checks are always on, in lenient and strict mode alike:
|
|
150
|
+
|
|
151
|
+
- **No `DOCTYPE` or entity declarations.** They're refused at the first token, which blocks entity bombs (billion laughs) and external entities (XXE). Model Descriptions never need them.
|
|
152
|
+
- **A size limit.** `max_xml_bytes` defaults to 256 MB and can be changed per call. For zips it counts the *decompressed* size, and a zip entry claiming to be bigger is refused before it's opened.
|
|
153
|
+
- **Only the Model Description is read.** No other archive member is ever opened.
|
|
154
|
+
|
|
155
|
+
All three raise `mdxml.UnsafeInput`. Every error mdxml raises on purpose is an `mdxml.MdxmlError`.
|
|
156
|
+
|
|
157
|
+
## Performance
|
|
158
|
+
|
|
159
|
+
Against FMPy 0.3.32 on generated FMUs with a million variables (see [benchmarks/RESULTS.md](benchmarks/RESULTS.md)):
|
|
160
|
+
|
|
161
|
+
| 1M variables | `iter_variables` | `read` | FMPy `read_model_description` |
|
|
162
|
+
|---|---|---|---|
|
|
163
|
+
| FMI 2 | 8.1 s · < 1 MB | 10.2 s · 586 MB | 12.3 s · 3,177 MB (10.8 s without validation) |
|
|
164
|
+
| FMI 3 | 7.1 s · < 1 MB | 8.8 s · 555 MB | 11.1 s · 3,055 MB (9.4 s without validation) |
|
|
165
|
+
|
|
166
|
+
`read_header` takes about 0.5 ms at any size.
|
|
167
|
+
|
|
168
|
+
## Supported versions
|
|
169
|
+
|
|
170
|
+
- FMI 2.0 (schema v2.0.5) and FMI 3.0 (schema v3.0.2). FMI 1.0 raises `mdxml.UnsupportedFmiVersion`.
|
|
171
|
+
- Only `modelDescription.xml`. FMI 3's other XML files (build description, terminals and icons, layered-standard manifests) aren't read.
|
|
172
|
+
- Python 3.10 to 3.14 on Linux, macOS and Windows.
|
|
173
|
+
|
|
174
|
+
## License
|
|
175
|
+
|
|
176
|
+
MIT. The FMI XSDs in `schema/`, which are used only by the tests, are © Modelica Association Project "FMI" under the 2-Clause BSD license, and aren't part of the installed package.
|
|
@@ -0,0 +1,148 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "mdxml"
|
|
3
|
+
version = "0.1.0"
|
|
4
|
+
description = "Fast, zero-dependency, streaming parser for FMI 2.0 and 3.0 modelDescription.xml files"
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
license = "MIT"
|
|
7
|
+
license-files = ["LICENSE"]
|
|
8
|
+
requires-python = ">=3.10"
|
|
9
|
+
dependencies = []
|
|
10
|
+
keywords = [
|
|
11
|
+
"fmi",
|
|
12
|
+
"fmu",
|
|
13
|
+
"modelDescription",
|
|
14
|
+
"xml",
|
|
15
|
+
"parser",
|
|
16
|
+
"co-simulation",
|
|
17
|
+
]
|
|
18
|
+
classifiers = [
|
|
19
|
+
"Development Status :: 2 - Pre-Alpha",
|
|
20
|
+
"Intended Audience :: Developers",
|
|
21
|
+
"Intended Audience :: Science/Research",
|
|
22
|
+
"Operating System :: OS Independent",
|
|
23
|
+
"Programming Language :: Python :: 3",
|
|
24
|
+
"Programming Language :: Python :: 3 :: Only",
|
|
25
|
+
"Programming Language :: Python :: 3.10",
|
|
26
|
+
"Programming Language :: Python :: 3.11",
|
|
27
|
+
"Programming Language :: Python :: 3.12",
|
|
28
|
+
"Programming Language :: Python :: 3.13",
|
|
29
|
+
"Programming Language :: Python :: 3.14",
|
|
30
|
+
"Topic :: Scientific/Engineering",
|
|
31
|
+
"Typing :: Typed",
|
|
32
|
+
]
|
|
33
|
+
|
|
34
|
+
[project.urls]
|
|
35
|
+
Homepage = "https://github.com/hyumo/mdxml"
|
|
36
|
+
Issues = "https://github.com/hyumo/mdxml/issues"
|
|
37
|
+
Changelog = "https://github.com/hyumo/mdxml/blob/master/CHANGELOG.md"
|
|
38
|
+
|
|
39
|
+
[project.scripts]
|
|
40
|
+
mdxml = "mdxml:main"
|
|
41
|
+
|
|
42
|
+
[dependency-groups]
|
|
43
|
+
bench = ["fmpy>=0.3.32"]
|
|
44
|
+
dev = [
|
|
45
|
+
"pytest>=8",
|
|
46
|
+
"mypy>=1.13",
|
|
47
|
+
"pyright>=1.1.390",
|
|
48
|
+
"ruff>=0.17.5",
|
|
49
|
+
]
|
|
50
|
+
|
|
51
|
+
[build-system]
|
|
52
|
+
requires = ["uv_build>=0.13.6,<0.14.0"]
|
|
53
|
+
build-backend = "uv_build"
|
|
54
|
+
|
|
55
|
+
[tool.pytest.ini_options]
|
|
56
|
+
testpaths = ["tests"]
|
|
57
|
+
addopts = [
|
|
58
|
+
"-ra",
|
|
59
|
+
"--strict-markers",
|
|
60
|
+
"--strict-config",
|
|
61
|
+
"-m",
|
|
62
|
+
"not slow",
|
|
63
|
+
]
|
|
64
|
+
xfail_strict = true
|
|
65
|
+
markers = ["slow: streams a million variables under tracemalloc; run with `pytest -m slow`"]
|
|
66
|
+
|
|
67
|
+
[tool.mypy]
|
|
68
|
+
strict = true
|
|
69
|
+
python_version = "3.10"
|
|
70
|
+
files = [
|
|
71
|
+
"src",
|
|
72
|
+
"tests",
|
|
73
|
+
"scripts",
|
|
74
|
+
"benchmarks",
|
|
75
|
+
]
|
|
76
|
+
|
|
77
|
+
[[tool.mypy.overrides]]
|
|
78
|
+
module = [
|
|
79
|
+
"fmpy",
|
|
80
|
+
"fmpy.*",
|
|
81
|
+
]
|
|
82
|
+
ignore_missing_imports = true
|
|
83
|
+
|
|
84
|
+
[tool.pyright]
|
|
85
|
+
include = [
|
|
86
|
+
"src",
|
|
87
|
+
"tests",
|
|
88
|
+
"scripts",
|
|
89
|
+
"benchmarks",
|
|
90
|
+
]
|
|
91
|
+
extraPaths = ["tests"]
|
|
92
|
+
reportMissingTypeStubs = false
|
|
93
|
+
typeCheckingMode = "strict"
|
|
94
|
+
pythonVersion = "3.10"
|
|
95
|
+
|
|
96
|
+
[tool.ruff]
|
|
97
|
+
line-length = 120
|
|
98
|
+
|
|
99
|
+
[tool.ruff.lint]
|
|
100
|
+
select = [
|
|
101
|
+
"E",
|
|
102
|
+
"W",
|
|
103
|
+
"F",
|
|
104
|
+
"I",
|
|
105
|
+
"B",
|
|
106
|
+
"UP",
|
|
107
|
+
"SIM",
|
|
108
|
+
"C4",
|
|
109
|
+
"PIE",
|
|
110
|
+
"RET",
|
|
111
|
+
"PERF",
|
|
112
|
+
"RUF",
|
|
113
|
+
"PT",
|
|
114
|
+
"ERA",
|
|
115
|
+
"PL",
|
|
116
|
+
"D",
|
|
117
|
+
"S",
|
|
118
|
+
"FBT",
|
|
119
|
+
]
|
|
120
|
+
|
|
121
|
+
[tool.ruff.lint.per-file-ignores]
|
|
122
|
+
"tests/**" = [
|
|
123
|
+
"D",
|
|
124
|
+
"S",
|
|
125
|
+
"FBT",
|
|
126
|
+
"PLR2004",
|
|
127
|
+
"PLC0415",
|
|
128
|
+
]
|
|
129
|
+
"scripts/**" = [
|
|
130
|
+
"D",
|
|
131
|
+
"S",
|
|
132
|
+
"FBT",
|
|
133
|
+
"PLR2004",
|
|
134
|
+
"PLC0415",
|
|
135
|
+
]
|
|
136
|
+
"benchmarks/**" = [
|
|
137
|
+
"D",
|
|
138
|
+
"S",
|
|
139
|
+
"FBT",
|
|
140
|
+
"PLR2004",
|
|
141
|
+
"PLC0415",
|
|
142
|
+
]
|
|
143
|
+
|
|
144
|
+
[tool.ruff.lint.pydocstyle]
|
|
145
|
+
convention = "pep257"
|
|
146
|
+
|
|
147
|
+
[tool.ruff.lint.pylint]
|
|
148
|
+
max-args = 8
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "mdxml"
|
|
3
|
+
version = "0.1.0"
|
|
4
|
+
description = "Fast, zero-dependency, streaming parser for FMI 2.0 and 3.0 modelDescription.xml files"
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
license = "MIT"
|
|
7
|
+
license-files = ["LICENSE"]
|
|
8
|
+
requires-python = ">=3.10"
|
|
9
|
+
dependencies = []
|
|
10
|
+
keywords = ["fmi", "fmu", "modelDescription", "xml", "parser", "co-simulation"]
|
|
11
|
+
classifiers = [
|
|
12
|
+
"Development Status :: 2 - Pre-Alpha",
|
|
13
|
+
"Intended Audience :: Developers",
|
|
14
|
+
"Intended Audience :: Science/Research",
|
|
15
|
+
"Operating System :: OS Independent",
|
|
16
|
+
"Programming Language :: Python :: 3",
|
|
17
|
+
"Programming Language :: Python :: 3 :: Only",
|
|
18
|
+
"Programming Language :: Python :: 3.10",
|
|
19
|
+
"Programming Language :: Python :: 3.11",
|
|
20
|
+
"Programming Language :: Python :: 3.12",
|
|
21
|
+
"Programming Language :: Python :: 3.13",
|
|
22
|
+
"Programming Language :: Python :: 3.14",
|
|
23
|
+
"Topic :: Scientific/Engineering",
|
|
24
|
+
"Typing :: Typed",
|
|
25
|
+
]
|
|
26
|
+
|
|
27
|
+
[project.urls]
|
|
28
|
+
Homepage = "https://github.com/hyumo/mdxml"
|
|
29
|
+
Issues = "https://github.com/hyumo/mdxml/issues"
|
|
30
|
+
Changelog = "https://github.com/hyumo/mdxml/blob/master/CHANGELOG.md"
|
|
31
|
+
|
|
32
|
+
[project.scripts]
|
|
33
|
+
mdxml = "mdxml:main"
|
|
34
|
+
|
|
35
|
+
[dependency-groups]
|
|
36
|
+
bench = [
|
|
37
|
+
"fmpy>=0.3.32",
|
|
38
|
+
]
|
|
39
|
+
dev = [
|
|
40
|
+
"pytest>=8",
|
|
41
|
+
"mypy>=1.13",
|
|
42
|
+
"pyright>=1.1.390",
|
|
43
|
+
"ruff>=0.17.5",
|
|
44
|
+
]
|
|
45
|
+
|
|
46
|
+
[build-system]
|
|
47
|
+
requires = ["uv_build>=0.13.6,<0.14.0"]
|
|
48
|
+
build-backend = "uv_build"
|
|
49
|
+
|
|
50
|
+
[tool.pytest.ini_options]
|
|
51
|
+
testpaths = ["tests"]
|
|
52
|
+
addopts = ["-ra", "--strict-markers", "--strict-config", "-m", "not slow"]
|
|
53
|
+
xfail_strict = true
|
|
54
|
+
markers = ["slow: streams a million variables under tracemalloc; run with `pytest -m slow`"]
|
|
55
|
+
|
|
56
|
+
[tool.mypy]
|
|
57
|
+
strict = true
|
|
58
|
+
python_version = "3.10"
|
|
59
|
+
files = ["src", "tests", "scripts", "benchmarks"]
|
|
60
|
+
|
|
61
|
+
[[tool.mypy.overrides]]
|
|
62
|
+
module = ["fmpy", "fmpy.*"]
|
|
63
|
+
ignore_missing_imports = true
|
|
64
|
+
|
|
65
|
+
[tool.pyright]
|
|
66
|
+
include = ["src", "tests", "scripts", "benchmarks"]
|
|
67
|
+
extraPaths = ["tests"]
|
|
68
|
+
reportMissingTypeStubs = false
|
|
69
|
+
typeCheckingMode = "strict"
|
|
70
|
+
pythonVersion = "3.10"
|
|
71
|
+
|
|
72
|
+
[tool.ruff]
|
|
73
|
+
line-length = 120
|
|
74
|
+
|
|
75
|
+
[tool.ruff.lint]
|
|
76
|
+
select = [
|
|
77
|
+
"E", "W", # pycodestyle
|
|
78
|
+
"F", # Pyflakes
|
|
79
|
+
"I", # import sorting
|
|
80
|
+
"B", # bugbear
|
|
81
|
+
"UP", # pyupgrade
|
|
82
|
+
"SIM", # simplifications
|
|
83
|
+
"C4", # comprehensions
|
|
84
|
+
"PIE", # misc cleanups
|
|
85
|
+
"RET", # return statements
|
|
86
|
+
"PERF", # performance
|
|
87
|
+
"RUF", # ruff-specific
|
|
88
|
+
"PT", # pytest style
|
|
89
|
+
"ERA", # commented-out code
|
|
90
|
+
"PL", # pylint
|
|
91
|
+
"D", # docstrings (src only, see per-file-ignores)
|
|
92
|
+
"S", # bandit security (src only)
|
|
93
|
+
"FBT", # boolean positional arguments (src only)
|
|
94
|
+
]
|
|
95
|
+
# Deliberately not selected: ANN and TC (strict mypy/pyright cover typing), PTH (os.path is used on
|
|
96
|
+
# purpose for str paths), EM/TRY003 (f-string error messages are fine), ARG (protocol methods take
|
|
97
|
+
# arguments they don't use), N818 (UnsupportedFmiVersion and UnsafeInput are deliberate names).
|
|
98
|
+
|
|
99
|
+
[tool.ruff.lint.per-file-ignores]
|
|
100
|
+
"tests/**" = ["D", "S", "FBT", "PLR2004", "PLC0415"]
|
|
101
|
+
"scripts/**" = ["D", "S", "FBT", "PLR2004", "PLC0415"]
|
|
102
|
+
"benchmarks/**" = ["D", "S", "FBT", "PLR2004", "PLC0415"]
|
|
103
|
+
|
|
104
|
+
[tool.ruff.lint.pydocstyle]
|
|
105
|
+
convention = "pep257"
|
|
106
|
+
|
|
107
|
+
[tool.ruff.lint.pylint]
|
|
108
|
+
max-args = 8
|
|
@@ -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
|
+
]
|