Skip to content

oxml

oxml

Initializes oxml sub-package.

This including registering custom element classes corresponding to Open XML elements.

OxmlElement 

OxmlElement(
    nsptag_str: str,
    attrs: Dict[str, str] | None = None,
    nsdecls: Dict[str, str] | None = None,
) -> BaseOxmlElement | _Element

Return a 'loose' lxml element having the tag specified by nsptag_str.

The tag in nsptag_str must contain the standard namespace prefix, e.g. a:tbl. The resulting element is an instance of the custom element class for this tag name if one is defined. A dictionary of attribute values may be provided as attrs; they are set if present. All namespaces defined in the dict nsdecls are declared in the element using the key as the prefix and the value as the namespace name. If nsdecls is not provided, a single namespace declaration is added based on the prefix on nsptag_str.

Source code in src/docx/oxml/parser.py 
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
def OxmlElement(
    nsptag_str: str,
    attrs: Dict[str, str] | None = None,
    nsdecls: Dict[str, str] | None = None,
) -> BaseOxmlElement | etree._Element:  # pyright: ignore[reportPrivateUsage]
    """Return a 'loose' lxml element having the tag specified by `nsptag_str`.

    The tag in `nsptag_str` must contain the standard namespace prefix, e.g. `a:tbl`.
    The resulting element is an instance of the custom element class for this tag name
    if one is defined. A dictionary of attribute values may be provided as `attrs`; they
    are set if present. All namespaces defined in the dict `nsdecls` are declared in the
    element using the key as the prefix and the value as the namespace name. If
    `nsdecls` is not provided, a single namespace declaration is added based on the
    prefix on `nsptag_str`.
    """
    nsptag = NamespacePrefixedTag(nsptag_str)
    if nsdecls is None:
        nsdecls = nsptag.nsmap
    return oxml_parser.makeelement(nsptag.clark_name, attrib=attrs, nsmap=nsdecls)

parse_xml 

parse_xml(xml: str | bytes) -> 'BaseOxmlElement'

Root lxml element obtained by parsing XML character string xml.

The custom parser is used, so custom element classes are produced for elements in xml that have them.

Source code in src/docx/oxml/parser.py 
28
29
30
31
32
33
34
def parse_xml(xml: str | bytes) -> "BaseOxmlElement":
    """Root lxml element obtained by parsing XML character string `xml`.

    The custom parser is used, so custom element classes are produced for elements in
    `xml` that have them.
    """
    return cast("BaseOxmlElement", etree.fromstring(xml, oxml_parser))