sdmxlib 0.8.0__py3-none-any.whl

sdmxlib/formats/sdmx_ml21/writer.py

@@ -0,0 +1,709 @@
+"""SDMX-ML 2.1 writer: domain model → lxml → bytes.
+
+Serialises a StructureMessage (or any subset of its artefacts) to a
+valid SDMX-ML 2.1 Structure message.
+
+Example:
+    from sdmxlib.formats.sdmx_ml21.writer import write
+
+    xml_bytes = write(msg)
+"""
+
+from typing import Any
+
+from lxml import etree
+
+from sdmxlib.model.category import Categorisation, Category, CategoryScheme
+from sdmxlib.model.codelist import Code, Codelist
+from sdmxlib.model.concept import Concept, ConceptScheme
+from sdmxlib.model.constraint import ConstraintAttachment, ContentConstraint, CubeRegion
+from sdmxlib.model.dataflow import Dataflow
+from sdmxlib.model.datastructure import (
+    AttachmentLevel,
+    Attribute,
+    DataStructure,
+    Dimension,
+    Group,
+    Measure,
+    TimeDimension,
+)
+from sdmxlib.model.hierarchy import HierarchicalCode, Hierarchy
+from sdmxlib.model.istring import InternationalString
+from sdmxlib.model.mapping import (
+    CategorySchemeMap,
+    CodelistMap,
+    ConceptSchemeMap,
+    DataflowMap,
+    DataStructureMap,
+    StructureSet,
+)
+from sdmxlib.model.message import StructureMessage
+from sdmxlib.model.organisation import Agency, AgencyScheme, DataProvider, DataProviderScheme
+from sdmxlib.model.provision import ProvisionAgreement
+from sdmxlib.model.ref import AnyRef, Ref
+from sdmxlib.model.representation import Facet
+from sdmxlib.model.urn import SdmxUrn
+
+from .namespaces import COM, MES, STR
+
+# ── Namespace helpers ─────────────────────────────────────────────────────────
+
+_NSMAP: dict[Any, str] = {
+    "mes": MES,
+    "str": STR,
+    "com": COM,
+    "xsi": "http://www.w3.org/2001/XMLSchema-instance",
+}
+
+_XML_LANG = "{http://www.w3.org/XML/1998/namespace}lang"
+
+
+def _m(tag: str) -> str:
+    return f"{{{MES}}}{tag}"
+
+
+def _s(tag: str) -> str:
+    return f"{{{STR}}}{tag}"
+
+
+def _c(tag: str) -> str:
+    return f"{{{COM}}}{tag}"
+
+
+# ── Common writers ────────────────────────────────────────────────────────────
+
+
+def _write_istring(
+    parent: etree._Element, istring: InternationalString | dict[str, str], child_tag: str = "Name"
+) -> None:
+    """Append com:Name (or com:Description) children for each language."""
+    for lang in istring:
+        el = etree.SubElement(parent, _c(child_tag))
+        el.set(_XML_LANG, lang)
+        el.text = istring[lang]  # type: ignore[index]
+
+
+def _write_maintainable_attrs(el: etree._Element, obj: Any) -> None:
+    """Set id, agencyID, version, isFinal on a maintainable element."""
+    el.set("id", obj.id)
+    el.set("agencyID", obj.agency_id)
+    el.set("version", obj.version)
+    if getattr(obj, "is_final", False):
+        el.set("isFinal", "true")
+    if getattr(obj, "valid_from", None) is not None:
+        el.set("validFrom", obj.valid_from.isoformat())
+    if getattr(obj, "valid_to", None) is not None:
+        el.set("validTo", obj.valid_to.isoformat())
+
+
+def _urn_to_ref_el(urn: SdmxUrn[Any]) -> etree._Element:
+    """Build a <Ref> element from an SdmxUrn."""
+    ref = etree.Element("Ref")
+    ref.set("agencyID", urn.agency)
+    ref.set("id", urn.id)
+    if urn.version != "latest":
+        ref.set("version", urn.version)
+    if urn.item_id is not None:
+        ref.set("maintainableParentID", urn.id)
+        ref.set("id", urn.item_id)
+        ref.set("maintainableParentVersion", urn.version if urn.version != "latest" else "1.0")
+    ref.set("class", urn.artefact_class)
+    ref.set("package", urn.package)
+    return ref
+
+
+def _write_ref(parent: etree._Element, ref: AnyRef) -> None:
+    """Append a <Ref> child carrying the reference URN."""
+    parent.append(_urn_to_ref_el(ref.urn))
+
+
+def _write_text_format(parent: etree._Element, tf: Facet) -> None:  # noqa: C901
+    """Append a str:TextFormat element."""
+    el = etree.SubElement(parent, _s("TextFormat"))
+    if tf.type is not None:
+        el.set("textType", tf.type)
+    if tf.max_length is not None:
+        el.set("maxLength", str(tf.max_length))
+    if tf.min_length is not None:
+        el.set("minLength", str(tf.min_length))
+    if tf.max_value is not None:
+        el.set("maxValue", str(tf.max_value))
+    if tf.min_value is not None:
+        el.set("minValue", str(tf.min_value))
+    if tf.decimals is not None:
+        el.set("decimals", str(tf.decimals))
+    if tf.pattern is not None:
+        el.set("pattern", tf.pattern)
+    if tf.start_value is not None:
+        el.set("startValue", str(tf.start_value))
+    if tf.end_value is not None:
+        el.set("endValue", str(tf.end_value))
+    if tf.is_sequence is not None:
+        el.set("isSequence", "true" if tf.is_sequence else "false")
+    if tf.is_multi_lingual is not None:
+        el.set("isMultiLingual", "true" if tf.is_multi_lingual else "false")
+
+
+def _write_representation(
+    parent: etree._Element,
+    representation: AnyRef | Facet | None,
+    tag: str = "LocalRepresentation",
+) -> None:
+    """Append a str:LocalRepresentation (or str:CoreRepresentation) element."""
+    if representation is None:
+        return
+    rep_el = etree.SubElement(parent, _s(tag))
+    match representation:
+        case Facet():
+            _write_text_format(rep_el, representation)
+        case Ref():
+            enum_el = etree.SubElement(rep_el, _s("Enumeration"))
+            enum_el.append(_urn_to_ref_el(representation.urn))
+
+
+def _write_concept_identity(parent: etree._Element, ref: AnyRef) -> None:
+    """Append a str:ConceptIdentity with a <Ref> child."""
+    ci = etree.SubElement(parent, _s("ConceptIdentity"))
+    _write_ref(ci, ref)
+
+
+# ── Codelists ─────────────────────────────────────────────────────────────────
+
+
+def _write_code(parent: etree._Element, code: Code) -> None:
+    el = etree.SubElement(parent, _s("Code"))
+    el.set("id", code.id)
+    _write_istring(el, code.name)
+    if code.description:
+        _write_istring(el, code.description, "Description")
+    if code.parent_id is not None:
+        parent_el = etree.SubElement(el, _s("Parent"))
+        ref = etree.SubElement(parent_el, "Ref")
+        ref.set("id", code.parent_id)
+
+
+def _write_agency(parent: etree._Element, agency: Agency) -> None:
+    el = etree.SubElement(parent, _s("Agency"))
+    el.set("id", agency.id)
+    if agency.name:
+        _write_istring(el, agency.name)
+    if agency.description:
+        _write_istring(el, agency.description, "Description")
+
+
+def _write_agency_scheme(parent: etree._Element, scheme: AgencyScheme) -> None:
+    el = etree.SubElement(parent, _s("AgencyScheme"))
+    _write_maintainable_attrs(el, scheme)
+    if scheme.name:
+        _write_istring(el, scheme.name)
+    if scheme.description:
+        _write_istring(el, scheme.description, "Description")
+    for agency in scheme.agencies:
+        _write_agency(el, agency)
+
+
+def _write_data_provider(parent: etree._Element, provider: DataProvider) -> None:
+    el = etree.SubElement(parent, _s("DataProvider"))
+    el.set("id", provider.id)
+    if provider.name:
+        _write_istring(el, provider.name)
+    if provider.description:
+        _write_istring(el, provider.description, "Description")
+
+
+def _write_data_provider_scheme(parent: etree._Element, scheme: DataProviderScheme) -> None:
+    el = etree.SubElement(parent, _s("DataProviderScheme"))
+    _write_maintainable_attrs(el, scheme)
+    if scheme.name:
+        _write_istring(el, scheme.name)
+    if scheme.description:
+        _write_istring(el, scheme.description, "Description")
+    for provider in scheme.providers:
+        _write_data_provider(el, provider)
+
+
+def _write_codelist(parent: etree._Element, cl: Codelist) -> None:
+    el = etree.SubElement(parent, _s("Codelist"))
+    _write_maintainable_attrs(el, cl)
+    _write_istring(el, cl.name)
+    if cl.description:
+        _write_istring(el, cl.description, "Description")
+    for code in cl.codes:
+        _write_code(el, code)
+
+
+# ── ConceptSchemes ────────────────────────────────────────────────────────────
+
+
+def _write_concept(parent: etree._Element, concept: Concept) -> None:
+    el = etree.SubElement(parent, _s("Concept"))
+    el.set("id", concept.id)
+    _write_istring(el, concept.name)
+    if concept.description:
+        _write_istring(el, concept.description, "Description")
+    if concept.core_representation is not None:
+        _write_representation(el, concept.core_representation, tag="CoreRepresentation")
+
+
+def _write_concept_scheme(parent: etree._Element, cs: ConceptScheme) -> None:
+    el = etree.SubElement(parent, _s("ConceptScheme"))
+    _write_maintainable_attrs(el, cs)
+    _write_istring(el, cs.name)
+    if cs.description:
+        _write_istring(el, cs.description, "Description")
+    for concept in cs.concepts:
+        _write_concept(el, concept)
+
+
+# ── DataStructures ────────────────────────────────────────────────────────────
+
+
+def _write_dimension(parent: etree._Element, dim: Dimension, position: int) -> None:
+    el = etree.SubElement(parent, _s("Dimension"))
+    el.set("id", dim.id)
+    el.set("position", str(position))
+    if isinstance(dim.concept, Ref):
+        _write_concept_identity(el, dim.concept)
+    if isinstance(dim.representation, (Ref, Facet)):
+        _write_representation(el, dim.representation)
+
+
+def _write_time_dimension(parent: etree._Element, td: TimeDimension) -> None:
+    el = etree.SubElement(parent, _s("TimeDimension"))
+    el.set("id", td.id)
+    if isinstance(td.concept, Ref):
+        _write_concept_identity(el, td.concept)
+    if td.representation is not None:
+        local_rep = etree.SubElement(el, _s("LocalRepresentation"))
+        _write_text_format(local_rep, td.representation)
+
+
+def _write_attribute_relationship(parent: etree._Element, attr: Attribute) -> None:
+    ar = etree.SubElement(parent, _s("AttributeRelationship"))
+    match attr.attachment:
+        case AttachmentLevel.OBSERVATION:
+            pm = etree.SubElement(ar, _s("PrimaryMeasure"))
+            ref = etree.SubElement(pm, "Ref")
+            ref.set("id", attr.related_measure or "OBS_VALUE")
+        case AttachmentLevel.SERIES:
+            for dim_id in attr.related_dimensions or []:
+                dim_el = etree.SubElement(ar, _s("Dimension"))
+                ref = etree.SubElement(dim_el, "Ref")
+                ref.set("id", dim_id)
+        case AttachmentLevel.GROUP:
+            etree.SubElement(ar, _s("Group"))
+        case _:
+            etree.SubElement(ar, _s("None"))
+
+
+def _write_attribute(parent: etree._Element, attr: Attribute) -> None:
+    el = etree.SubElement(parent, _s("Attribute"))
+    el.set("id", attr.id)
+    if attr.usage is not None:
+        el.set("assignmentStatus", attr.usage)
+    if isinstance(attr.concept, Ref):
+        _write_concept_identity(el, attr.concept)
+    if isinstance(attr.representation, (Ref, Facet)):
+        _write_representation(el, attr.representation)
+    _write_attribute_relationship(el, attr)
+
+
+def _write_measure(parent: etree._Element, measure: Measure) -> None:
+    el = etree.SubElement(parent, _s("PrimaryMeasure"))
+    el.set("id", measure.id)
+    if isinstance(measure.concept, Ref):
+        _write_concept_identity(el, measure.concept)
+    if isinstance(measure.representation, (Ref, Facet)):
+        _write_representation(el, measure.representation)
+
+
+def _write_group(parent: etree._Element, group: Group) -> None:
+    el = etree.SubElement(parent, _s("Group"))
+    el.set("id", group.id)
+    for dim_id in group.dimension_ids:
+        gd = etree.SubElement(el, _s("GroupDimension"))
+        dr = etree.SubElement(gd, _s("DimensionReference"))
+        ref = etree.SubElement(dr, "Ref")
+        ref.set("id", dim_id)
+
+
+def _write_data_structure(parent: etree._Element, dsd: DataStructure) -> None:
+    el = etree.SubElement(parent, _s("DataStructure"))
+    _write_maintainable_attrs(el, dsd)
+    _write_istring(el, dsd.name)
+    if dsd.description:
+        _write_istring(el, dsd.description, "Description")
+
+    components = etree.SubElement(el, _s("DataStructureComponents"))
+
+    dim_list = etree.SubElement(components, _s("DimensionList"))
+    dim_list.set("id", "DimensionDescriptor")
+    for i, dim in enumerate(dsd.dimensions, start=1):
+        _write_dimension(dim_list, dim, i)
+    if dsd.time_dimension is not None:
+        _write_time_dimension(dim_list, dsd.time_dimension)
+
+    if dsd.groups:
+        for group in dsd.groups:
+            _write_group(components, group)
+
+    if dsd.attributes:
+        attr_list = etree.SubElement(components, _s("AttributeList"))
+        attr_list.set("id", "AttributeDescriptor")
+        for attr in dsd.attributes:
+            _write_attribute(attr_list, attr)
+
+    if dsd.measures:
+        measure_list = etree.SubElement(components, _s("MeasureList"))
+        measure_list.set("id", "MeasureDescriptor")
+        for measure in dsd.measures:
+            _write_measure(measure_list, measure)
+
+
+# ── Dataflows ─────────────────────────────────────────────────────────────────
+
+
+def _write_dataflow(parent: etree._Element, df: Dataflow) -> None:
+    el = etree.SubElement(parent, _s("Dataflow"))
+    _write_maintainable_attrs(el, df)
+    _write_istring(el, df.name)
+    if df.description:
+        _write_istring(el, df.description, "Description")
+    if isinstance(df.structure, Ref):
+        struct_el = etree.SubElement(el, _s("Structure"))
+        _write_ref(struct_el, df.structure)
+
+
+# ── CategorySchemes & Categorisations ─────────────────────────────────────────
+
+
+def _write_category(parent: etree._Element, cat: Category) -> None:
+    el = etree.SubElement(parent, _s("Category"))
+    el.set("id", cat.id)
+    _write_istring(el, cat.name)
+    if cat.description:
+        _write_istring(el, cat.description, "Description")
+    for child in cat.categories:
+        _write_category(el, child)
+
+
+def _write_category_scheme(parent: etree._Element, cs: CategoryScheme) -> None:
+    el = etree.SubElement(parent, _s("CategoryScheme"))
+    _write_maintainable_attrs(el, cs)
+    _write_istring(el, cs.name)
+    if cs.description:
+        _write_istring(el, cs.description, "Description")
+    for cat in cs.categories:
+        _write_category(el, cat)
+
+
+def _write_categorisation(parent: etree._Element, cat: Categorisation) -> None:
+    el = etree.SubElement(parent, _s("Categorisation"))
+    _write_maintainable_attrs(el, cat)
+    _write_istring(el, cat.name)
+    if cat.description:
+        _write_istring(el, cat.description, "Description")
+    if cat.source is not None:
+        source_el = etree.SubElement(el, _s("Source"))
+        _write_ref(source_el, cat.source)
+    if cat.target is not None:
+        target_el = etree.SubElement(el, _s("Target"))
+        _write_ref(target_el, cat.target)
+
+
+# ── ProvisionAgreements ───────────────────────────────────────────────────────
+
+
+def _write_provision_agreement(parent: etree._Element, pa: ProvisionAgreement) -> None:
+    el = etree.SubElement(parent, _s("ProvisionAgreement"))
+    _write_maintainable_attrs(el, pa)
+    _write_istring(el, pa.name)
+    if pa.description:
+        _write_istring(el, pa.description, "Description")
+    if pa.dataflow is not None:
+        su_el = etree.SubElement(el, _s("StructureUsage"))
+        _write_ref(su_el, pa.dataflow)
+    if pa.data_provider is not None:
+        dp_el = etree.SubElement(el, _s("DataProvider"))
+        _write_ref(dp_el, pa.data_provider)
+
+
+# ── Constraints ───────────────────────────────────────────────────────────────
+
+
+def _write_cube_region(parent: etree._Element, region: CubeRegion) -> None:
+    el = etree.SubElement(parent, _s("CubeRegion"))
+    el.set("include", "true" if region.include else "false")
+    for kv in region.keys:
+        kv_el = etree.SubElement(el, _c("KeyValue"))
+        kv_el.set("id", kv.dimension_id)
+        for value in sorted(kv.values):
+            v_el = etree.SubElement(kv_el, _c("Value"))
+            v_el.text = value
+
+
+def _write_constraint_attachment(parent: etree._Element, attachment: ConstraintAttachment) -> None:
+    att_el = etree.SubElement(parent, _s("ConstraintAttachment"))
+    if attachment.dataflow is not None:
+        df_el = etree.SubElement(att_el, _s("Dataflow"))
+        _write_ref(df_el, attachment.dataflow)
+    elif attachment.data_structure is not None:
+        ds_el = etree.SubElement(att_el, _s("DataStructure"))
+        _write_ref(ds_el, attachment.data_structure)
+    elif attachment.provision_agreement is not None:
+        pa_el = etree.SubElement(att_el, _s("ProvisionAgreement"))
+        _write_ref(pa_el, attachment.provision_agreement)
+
+
+def _write_content_constraint(parent: etree._Element, cc: ContentConstraint) -> None:
+    el = etree.SubElement(parent, _s("ContentConstraint"))
+    _write_maintainable_attrs(el, cc)
+    el.set("type", cc.constraint_type)
+    _write_istring(el, cc.name)
+    if cc.description:
+        _write_istring(el, cc.description, "Description")
+    _write_constraint_attachment(el, cc.attachment)
+    for region in cc.regions:
+        _write_cube_region(el, region)
+    if cc.reference_period is not None:
+        rp_el = etree.SubElement(el, _s("ReferencePeriod"))
+        rp_el.set("startTime", cc.reference_period.start_period.isoformat())
+        rp_el.set("endTime", cc.reference_period.end_period.isoformat())
+    if cc.release_calendar is not None:
+        rc_el = etree.SubElement(el, _s("ReleaseCalendar"))
+        etree.SubElement(rc_el, _s("Periodicity")).text = cc.release_calendar.periodicity
+        etree.SubElement(rc_el, _s("Offset")).text = cc.release_calendar.offset
+        etree.SubElement(rc_el, _s("Tolerance")).text = cc.release_calendar.tolerance
+
+
+# ── StructureSets ─────────────────────────────────────────────────────────────
+
+
+def _write_codelist_map(parent: etree._Element, cm: CodelistMap) -> None:
+    el = etree.SubElement(parent, _s("CodelistMap"))
+    el.set("id", cm.id)
+    _write_istring(el, cm.name)
+    if cm.description:
+        _write_istring(el, cm.description, "Description")
+    if cm.source is not None:
+        src_el = etree.SubElement(el, _s("Source"))
+        _write_ref(src_el, cm.source)
+    if cm.target is not None:
+        tgt_el = etree.SubElement(el, _s("Target"))
+        _write_ref(tgt_el, cm.target)
+    for code_map in cm.maps:
+        m_el = etree.SubElement(el, _s("CodeMap"))
+        src_el = etree.SubElement(m_el, _s("Source"))
+        etree.SubElement(src_el, "Ref").set("id", code_map.source_id)
+        tgt_el = etree.SubElement(m_el, _s("Target"))
+        etree.SubElement(tgt_el, "Ref").set("id", code_map.target_id)
+
+
+def _write_concept_scheme_map(parent: etree._Element, csm: ConceptSchemeMap) -> None:
+    el = etree.SubElement(parent, _s("ConceptSchemeMap"))
+    el.set("id", csm.id)
+    _write_istring(el, csm.name)
+    if csm.description:
+        _write_istring(el, csm.description, "Description")
+    if csm.source is not None:
+        src_el = etree.SubElement(el, _s("Source"))
+        _write_ref(src_el, csm.source)
+    if csm.target is not None:
+        tgt_el = etree.SubElement(el, _s("Target"))
+        _write_ref(tgt_el, csm.target)
+    for concept_map in csm.maps:
+        m_el = etree.SubElement(el, _s("ConceptMap"))
+        src_el = etree.SubElement(m_el, _s("Source"))
+        etree.SubElement(src_el, "Ref").set("id", concept_map.source_id)
+        tgt_el = etree.SubElement(m_el, _s("Target"))
+        etree.SubElement(tgt_el, "Ref").set("id", concept_map.target_id)
+
+
+def _write_category_scheme_map(parent: etree._Element, csm: CategorySchemeMap) -> None:
+    el = etree.SubElement(parent, _s("CategorySchemeMap"))
+    el.set("id", csm.id)
+    _write_istring(el, csm.name)
+    if csm.description:
+        _write_istring(el, csm.description, "Description")
+    if csm.source is not None:
+        src_el = etree.SubElement(el, _s("Source"))
+        _write_ref(src_el, csm.source)
+    if csm.target is not None:
+        tgt_el = etree.SubElement(el, _s("Target"))
+        _write_ref(tgt_el, csm.target)
+    for category_map in csm.maps:
+        m_el = etree.SubElement(el, _s("CategoryMap"))
+        src_el = etree.SubElement(m_el, _s("Source"))
+        etree.SubElement(src_el, "Ref").set("id", category_map.source_id)
+        tgt_el = etree.SubElement(m_el, _s("Target"))
+        etree.SubElement(tgt_el, "Ref").set("id", category_map.target_id)
+
+
+def _write_data_structure_map(parent: etree._Element, dsm: DataStructureMap) -> None:
+    el = etree.SubElement(parent, _s("DataStructureMap"))
+    el.set("id", dsm.id)
+    _write_istring(el, dsm.name)
+    if dsm.description:
+        _write_istring(el, dsm.description, "Description")
+    if dsm.source is not None:
+        src_el = etree.SubElement(el, _s("Source"))
+        _write_ref(src_el, dsm.source)
+    if dsm.target is not None:
+        tgt_el = etree.SubElement(el, _s("Target"))
+        _write_ref(tgt_el, dsm.target)
+    for comp_map in dsm.maps:
+        m_el = etree.SubElement(el, _s("ComponentMap"))
+        src_el = etree.SubElement(m_el, _s("Source"))
+        etree.SubElement(src_el, "Ref").set("id", comp_map.source_id)
+        tgt_el = etree.SubElement(m_el, _s("Target"))
+        etree.SubElement(tgt_el, "Ref").set("id", comp_map.target_id)
+
+
+def _write_dataflow_map(parent: etree._Element, dfm: DataflowMap) -> None:
+    el = etree.SubElement(parent, _s("DataflowMap"))
+    el.set("id", dfm.id)
+    _write_istring(el, dfm.name)
+    if dfm.description:
+        _write_istring(el, dfm.description, "Description")
+    if dfm.source is not None:
+        src_el = etree.SubElement(el, _s("Source"))
+        _write_ref(src_el, dfm.source)
+    if dfm.target is not None:
+        tgt_el = etree.SubElement(el, _s("Target"))
+        _write_ref(tgt_el, dfm.target)
+
+
+def _write_structure_set(parent: etree._Element, ss: StructureSet) -> None:
+    el = etree.SubElement(parent, _s("StructureSet"))
+    _write_maintainable_attrs(el, ss)
+    _write_istring(el, ss.name)
+    if ss.description:
+        _write_istring(el, ss.description, "Description")
+    for cm in ss.codelist_maps:
+        _write_codelist_map(el, cm)
+    for csm in ss.concept_scheme_maps:
+        _write_concept_scheme_map(el, csm)
+    for csm in ss.category_scheme_maps:
+        _write_category_scheme_map(el, csm)
+    for dsm in ss.data_structure_maps:
+        _write_data_structure_map(el, dsm)
+    for dfm in ss.dataflow_maps:
+        _write_dataflow_map(el, dfm)
+
+
+# ── Hierarchies ───────────────────────────────────────────────────────────────
+
+
+def _write_hierarchical_code(parent: etree._Element, hc: HierarchicalCode) -> None:
+    el = etree.SubElement(parent, _s("HierarchicalCode"))
+    el.set("id", hc.id)
+    _write_istring(el, hc.name)
+    if hc.description:
+        _write_istring(el, hc.description, "Description")
+    if hc.code is not None and isinstance(hc.code, Ref):
+        code_id_el = etree.SubElement(el, _s("CodeID"))
+        _write_ref(code_id_el, hc.code)
+    for child in hc.children:
+        _write_hierarchical_code(el, child)
+
+
+def _write_hierarchy(parent: etree._Element, h: Hierarchy) -> None:
+    hcl_el = etree.SubElement(parent, _s("HierarchicalCodelist"))
+    _write_maintainable_attrs(hcl_el, h)
+    _write_istring(hcl_el, h.name)
+    if h.description:
+        _write_istring(hcl_el, h.description, "Description")
+    hier_el = etree.SubElement(hcl_el, _s("Hierarchy"))
+    hier_el.set("id", h.id)
+    _write_istring(hier_el, h.name)
+    if h.description:
+        _write_istring(hier_el, h.description, "Description")
+    for hc in h.tree:
+        _write_hierarchical_code(hier_el, hc)
+
+
+# ── Entry point ───────────────────────────────────────────────────────────────
+
+
+def write(msg: StructureMessage, *, pretty_print: bool = False) -> bytes:  # noqa: C901, PLR0912
+    """Serialise a StructureMessage to SDMX-ML 2.1 XML bytes.
+
+    Example:
+        from sdmxlib.formats.sdmx_ml21.writer import write
+
+        xml_bytes = write(msg)
+        xml_bytes = write(msg, pretty_print=True)  # indented output
+    """
+    root = etree.Element(_m("Structure"), nsmap=_NSMAP)
+    root.set(
+        "{http://www.w3.org/2001/XMLSchema-instance}schemaLocation",
+        f"{MES} SDMXMessage.xsd",
+    )
+
+    header = etree.SubElement(root, _m("Header"))
+    etree.SubElement(header, _m("ID")).text = "SDMX_MSG"
+    etree.SubElement(header, _m("Test")).text = "false"
+    etree.SubElement(header, _m("Prepared")).text = "2000-01-01T00:00:00"
+    sender = etree.SubElement(header, _m("Sender"))
+    sender.set("id", "sdmxlib")
+
+    structures = etree.SubElement(root, _m("Structures"))
+
+    if msg.agency_schemes or msg.data_provider_schemes:
+        container = etree.SubElement(structures, _s("OrganisationSchemes"))
+        for scheme in msg.agency_schemes:
+            _write_agency_scheme(container, scheme)
+        for scheme in msg.data_provider_schemes:
+            _write_data_provider_scheme(container, scheme)
+
+    if msg.codelists:
+        container = etree.SubElement(structures, _s("Codelists"))
+        for cl in msg.codelists:
+            _write_codelist(container, cl)
+
+    if msg.concept_schemes:
+        container = etree.SubElement(structures, _s("Concepts"))
+        for cs in msg.concept_schemes:
+            _write_concept_scheme(container, cs)
+
+    if msg.category_schemes:
+        container = etree.SubElement(structures, _s("CategorySchemes"))
+        for cs in msg.category_schemes:
+            _write_category_scheme(container, cs)
+
+    if msg.data_structures:
+        container = etree.SubElement(structures, _s("DataStructures"))
+        for dsd in msg.data_structures:
+            _write_data_structure(container, dsd)
+
+    if msg.dataflows:
+        container = etree.SubElement(structures, _s("Dataflows"))
+        for df in msg.dataflows:
+            _write_dataflow(container, df)
+
+    if msg.categorisations:
+        container = etree.SubElement(structures, _s("Categorisations"))
+        for cat in msg.categorisations:
+            _write_categorisation(container, cat)
+
+    if msg.provision_agreements:
+        container = etree.SubElement(structures, _s("ProvisionAgreements"))
+        for pa in msg.provision_agreements:
+            _write_provision_agreement(container, pa)
+
+    if msg.constraints:
+        container = etree.SubElement(structures, _s("Constraints"))
+        for cc in msg.constraints:
+            _write_content_constraint(container, cc)
+
+    if msg.structure_sets:
+        container = etree.SubElement(structures, _s("StructureSets"))
+        for ss in msg.structure_sets:
+            _write_structure_set(container, ss)
+
+    if msg.hierarchies:
+        container = etree.SubElement(structures, _s("HierarchicalCodelists"))
+        for h in msg.hierarchies:
+            _write_hierarchy(container, h)
+
+    return etree.tostring(root, xml_declaration=True, encoding="UTF-8", pretty_print=pretty_print)