Skip to content

parser

parser

XML parser for python-docx.

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))

register_element_cls 

register_element_cls(
    tag: str, cls: Type["BaseOxmlElement"]
)

Register an lxml custom element-class to use for tag.

A instance of cls to be constructed when the oxml parser encounters an element with matching tag. tag is a string of the form nspfx:tagroot, e.g. 'w:document'.

Source code in src/docx/oxml/parser.py 
37
38
39
40
41
42
43
44
45
46
def register_element_cls(tag: str, cls: Type["BaseOxmlElement"]):
    """Register an lxml custom element-class to use for `tag`.

    A instance of `cls` to be constructed when the oxml parser encounters an element
    with matching `tag`. `tag` is a string of the form `nspfx:tagroot`, e.g.
    `'w:document'`.
    """
    nspfx, tagroot = tag.split(":")
    namespace = element_class_lookup.get_namespace(nsmap[nspfx])
    namespace[tagroot] = cls

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)