Package API¶
Functions and supporting models. Every class and function defined in these modules is listed, generated from the code.
Loading, saving and validation¶
load_model(filepath, use_cache=True)
¶
Source code in dsbxml\utils.py
22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 | |
clear_model_cache()
¶
Source code in dsbxml\utils.py
42 43 | |
save_model(model, filepath)
¶
Source code in dsbxml\utils.py
46 47 48 49 50 51 52 53 54 55 56 57 58 59 | |
validate_against_xsd(source)
¶
Check a model, an XML file path or XML bytes against DesignBuilder.xsd.
Returns the schema's error messages; an empty list means the XML is valid. A loaded model is serialised first, so this also tells whether saving it would produce a file DesignBuilder's schema accepts.
Source code in dsbxml\utils.py
69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 | |
Comparing models¶
Semantic diff between two loaded models.
Reports added/removed buildings, zones, surfaces, and openings, changed attributes (old -> new), and HVAC topology changes. Handle/index fields on ObjectIDs (handle, buildingHandle, buildingBlockHandle, zoneHandle, surfaceIndex, openingIndex) are ignored throughout — DesignBuilder renumbers these on every save, so they're noise, not a semantic change.
ModelDiff
dataclass
¶
Source code in dsbxml\diffing.py
54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 | |
added = field(default_factory=dict)
class-attribute
instance-attribute
¶
removed = field(default_factory=dict)
class-attribute
instance-attribute
¶
attribute_changes = field(default_factory=list)
class-attribute
instance-attribute
¶
has_changes
property
¶
__init__(added=dict(), removed=dict(), attribute_changes=list())
¶
summary()
¶
Source code in dsbxml\diffing.py
64 65 66 67 68 69 70 71 72 | |
diff_models(model_a, model_b)
¶
Compare two dsbXML models, ignoring handle/index renumbering.
Source code in dsbxml\diffing.py
137 138 139 140 141 | |
Errors¶
Validation error formatting with model context (building/zone/surface).
Pydantic's default ValidationError shows the field path as raw indices
(site.buildings.building.0...zones.zone.3...surfaces.surface.2.area),
which doesn't say which building or zone that is without cross-referencing
the source file by hand. ModelValidationError re-walks the original XML tree
along that same path and adds the building title / zone handle / surface
index actually found there.
ModelValidationError
¶
Bases: ValueError
Wraps a pydantic ValidationError, adding model context to each error.
Falls back to pydantic's own field path when the source XML tree isn't available, or an error's path leaves the mapped building/zone/surface hierarchy (e.g. HVAC fields).
Source code in dsbxml\errors.py
103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 | |
original = original
instance-attribute
¶
errors = original.errors()
instance-attribute
¶
__init__(original, root=None)
¶
Source code in dsbxml\errors.py
111 112 113 114 | |
Identifiers and handles¶
ObjectIDs
¶
Bases: BaseModel
Source code in dsbxml\id.py
30 31 32 33 34 35 36 37 38 39 40 | |
handle = attr(default_factory=generate_site_handle)
class-attribute
instance-attribute
¶
buildingHandle = attr(default=(-1))
class-attribute
instance-attribute
¶
buildingBlockHandle = attr(default=(-1))
class-attribute
instance-attribute
¶
zoneHandle = attr(default=(-1))
class-attribute
instance-attribute
¶
surfaceIndex = attr(default=(-1))
class-attribute
instance-attribute
¶
openingIndex = attr(default=(-1))
class-attribute
instance-attribute
¶
model_config = ConfigDict(populate_by_name=True)
class-attribute
instance-attribute
¶
current_site_handle()
¶
Source code in dsbxml\id.py
13 14 | |
generate_site_handle()
¶
Source code in dsbxml\id.py
17 18 19 20 21 | |
set_site_counter(value)
¶
Source code in dsbxml\id.py
24 25 26 27 | |
Attributes¶
NameAttribute
¶
KeyAttribute
¶
NameAttributes
¶
KeyAttributes
¶
HVACAttributeList
¶
Bases: BaseModel
Source code in dsbxml\attributes.py
26 27 28 29 30 | |
ZoneComponentAttributeList
¶
Bases: BaseModel
Source code in dsbxml\attributes.py
33 34 35 36 | |
hvac_attribute_list = element(tag='HVACAttributeList', default_factory=list)
class-attribute
instance-attribute
¶
Geometry¶
Point3D
¶
Bases: BaseModel
Source code in dsbxml\geometry.py
13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 | |
value = '0;0;0'
class-attribute
instance-attribute
¶
x
property
¶
y
property
¶
z
property
¶
coords
property
¶
is_zero
property
¶
True when all coordinates are zero — the sentinel for 'no position'.
__setattr__(name, value)
¶
Source code in dsbxml\geometry.py
51 52 53 54 55 56 57 58 59 60 61 62 63 | |
Vertices
¶
Bases: BaseModel
Source code in dsbxml\geometry.py
66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 | |
point_3d = element(tag='Point3D', default_factory=list)
class-attribute
instance-attribute
¶
__iter__()
¶
Source code in dsbxml\geometry.py
69 70 | |
__getitem__(index)
¶
Source code in dsbxml\geometry.py
72 73 | |
__setitem__(index, value)
¶
Source code in dsbxml\geometry.py
75 76 77 78 79 80 81 82 | |
HandlePoint
¶
Bases: BaseModel
Source code in dsbxml\geometry.py
85 86 87 88 89 | |
WrappedPoint3D
¶
Bases: BaseModel
A Point3D nested one level deeper under its own
Most single-coordinate fields in the DesignBuilder XML (Origin,
Coordinate, Begin, End, ControlPoint, ...) are not the coordinate text
themselves but a wrapper element containing a single
Source code in dsbxml\geometry.py
92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 | |
Range
¶
Line
¶
Bases: BaseModel
Source code in dsbxml\geometry.py
133 134 135 136 137 138 | |
ImageRectangle
¶
Bases: BaseModel
Source code in dsbxml\geometry.py
141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 | |
object_ids = element(tag='ObjectIDs')
class-attribute
instance-attribute
¶
imageTextureIndex = element(tag='ImageTextureIndex')
class-attribute
instance-attribute
¶
maskTextureIndex = element(tag='MaskTextureIndex')
class-attribute
instance-attribute
¶
selectedImageTextureIndex = element(tag='SelectedImageTextureIndex')
class-attribute
instance-attribute
¶
inactiveImageTextureIndex = element(tag='InactiveImageTextureIndex')
class-attribute
instance-attribute
¶
textured = element(tag='Textured')
class-attribute
instance-attribute
¶
masked = element(tag='Masked')
class-attribute
instance-attribute
¶
selectedImage = element(tag='SelectedImage')
class-attribute
instance-attribute
¶
inactiveImage = element(tag='InactiveImage')
class-attribute
instance-attribute
¶
color = element(tag='Color')
class-attribute
instance-attribute
¶
active = element(tag='Active')
class-attribute
instance-attribute
¶
vertices = element(tag='Vertices')
class-attribute
instance-attribute
¶
range = element(tag='Range', default=None)
class-attribute
instance-attribute
¶
SegmentList
¶
Bases: BaseModel
Source code in dsbxml\geometry.py
159 160 161 | |
line_array = element(tag='LineArray', default=None)
class-attribute
instance-attribute
¶
Tables¶
Table
¶
Bases: BaseModel
Source code in dsbxml\tables.py
8 9 10 11 12 13 | |
name = attr()
class-attribute
instance-attribute
¶
numberOfFields = attr()
class-attribute
instance-attribute
¶
category = element(tag='Category', default_factory=list)
class-attribute
instance-attribute
¶
field_name = element(tag='FieldName', default_factory=list)
class-attribute
instance-attribute
¶
row = element(tag='Row', default_factory=list)
class-attribute
instance-attribute
¶
Tables
¶
Bases: BaseModel
Source code in dsbxml\tables.py
16 17 18 19 20 21 22 23 | |
table = element(tag='Table', default_factory=list)
class-attribute
instance-attribute
¶
get_table_by_name(name)
¶
Source code in dsbxml\tables.py
19 20 21 22 23 | |
Base model¶
XSDFloat = Annotated[float, PlainSerializer(_format_decimal, return_type=str, when_used='json')]
module-attribute
¶
BaseModel
¶
Bases: BaseXmlModel
Base XML model with unordered element search.
UNORDERED: pydantic-xml's default ORDERED mode consumes elements sequentially, so any field that scans past a later-appearing tag makes it invisible to subsequent fields. UNORDERED finds every element by tag name regardless of position — required because DesignBuilder XML places the same tags in different orders across component types.
Source code in dsbxml\base.py
28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 | |
model_config = ConfigDict(populate_by_name=True, validate_assignment=True, str_strip_whitespace=True, slots=True)
class-attribute
instance-attribute
¶
from_xml_tree(root, *args, **kwargs)
classmethod
¶
Source code in dsbxml\base.py
54 55 56 57 | |
to_xml_tree(**kwargs)
¶
Serialise without unset optional values.
pydantic-xml writes an unset optional attribute as name="" and an
unset optional primitive element as an empty tag, both invalid
against the schema. Empty strings and empty containers are not None
and are still written.
Source code in dsbxml\base.py
59 60 61 62 63 64 65 66 67 68 69 | |
to_xml(**kwargs)
¶
Serialise to XML text; see to_xml_tree for the unset-value handling.
Source code in dsbxml\base.py
71 72 73 74 | |