custom_xml

custom_xml

The custom XML data store parts, customXml/itemN.xml and its properties sidecar.

A .docx can carry arbitrary XML in the custom XML data store, and bind document content to it through w:dataBinding inside a w:sdt. This is how most document-generation pipelines that are not string substitution actually work: the data lives in the store, the content controls display it, and Word keeps the two in sync.

This is a different thing from the custom document properties in docProps/custom.xml (docx.opc.customprops), which are a flat list of named scalars.

CustomXmlPropertiesPart

CustomXmlPropertiesPart(
    partname: PackURI,
    content_type: str,
    element: BaseOxmlElement,
    package: Package,
)

Bases: XmlPart

A customXml/itemPropsN.xml part, the sidecar of a data store item.

Carries the GUID Word identifies the item by and the namespaces of the schemas it claims to conform to.

Source code in src/docx/opc/part.py

def __init__(
    self, partname: PackURI, content_type: str, element: BaseOxmlElement, package: Package
):
    super(XmlPart, self).__init__(partname, content_type, package=package)
    self._element = element

item_id property

item_id: str

The GUID Word identifies the store item by, e.g. "{EF278816-...}".

schema_refs property

schema_refs: tuple[str, ...]

The schema namespaces the store item claims, in document order.

new classmethod

new(
    package: OpcPackage,
    partname: PackURI,
    item_id: str,
    schema_refs: tuple[str, ...],
) -> CustomXmlPropertiesPart

A newly created properties part for a store item.

Source code in src/docx/opc/parts/custom_xml.py

@classmethod
def new(
    cls, package: OpcPackage, partname: PackURI, item_id: str, schema_refs: tuple[str, ...]
) -> CustomXmlPropertiesPart:
    """A newly created properties part for a store item."""
    return cls(
        partname,
        CT.OFC_CUSTOM_XML_PROPERTIES,
        CT_DatastoreItem.new(item_id, schema_refs),
        package,
    )

CustomXmlPart

CustomXmlPart(
    partname: PackURI,
    content_type: str,
    element: BaseOxmlElement,
    package: Package,
)

Bases: XmlPart

A customXml/itemN.xml part, one item of the custom XML data store.

The content is arbitrary caller-supplied XML, so it has no element classes of its own; element is a plain parsed tree and xml its serialization.

Source code in src/docx/opc/part.py

def __init__(
    self, partname: PackURI, content_type: str, element: BaseOxmlElement, package: Package
):
    super(XmlPart, self).__init__(partname, content_type, package=package)
    self._element = element

item_id property

item_id: str | None

The GUID this item is identified by, or None when it has no props part.

A store item without a properties part is out of spec but does occur; Word ignores such an item rather than repairing the document.

schema_refs property

schema_refs: tuple[str, ...]

The schema namespaces this item claims, empty when it has no props part.

xml property

xml: str

The item's XML as a string.

Serialized with lxml directly rather than through BaseOxmlElement.xml: the content is arbitrary caller-supplied XML, so its root arrives as a plain lxml.etree._Element with none of this library's element classes behind it.

new classmethod

new(
    package: OpcPackage,
    partname: PackURI,
    element: BaseOxmlElement,
) -> CustomXmlPart

A newly created store item part holding element.

Source code in src/docx/opc/parts/custom_xml.py

@classmethod
def new(cls, package: OpcPackage, partname: PackURI, element: BaseOxmlElement) -> CustomXmlPart:
    """A newly created store item part holding `element`."""
    return cls(partname, CT.XML, element, package)