`!xml.dom.minidom` --- Minimal DOM implementation

Source code: Lib/xml/dom/minidom.py

!xml.dom.minidom is a minimal implementation of the Document Object Model interface, with an API similar to that in other languages. It is intended to be simpler than the full DOM and also significantly smaller. Users who are not already proficient with the DOM should consider using the xml.etree.ElementTree module for their XML processing instead.

[!NOTE] If you need to parse untrusted or unauthenticated data, see xml-security.

DOM applications typically start by parsing some XML into a DOM. With !xml.dom.minidom, this is done through the parse functions:

from xml.dom.minidom import parse, parseString

dom1 = parse('c:\\temp\\mydata.xml')  # parse an XML file by name

datasource = open('c:\\temp\\mydata.xml')
dom2 = parse(datasource)  # parse an open file

dom3 = parseString('<myxml>Some data<empty/> some more data</myxml>')

The parse function can take either a filename or an open file object.

If you have XML in a string, you can use the parseString function instead:

Both functions return a Document object representing the content of the document.

What the parse and parseString functions do is connect an XML parser with a "DOM builder" that can accept parse events from any SAX parser and convert them into a DOM tree. The names of the functions are perhaps misleading, but are easy to grasp when learning the interfaces. The parsing of the document will be completed before these functions return; it's simply that these functions do not provide a parser implementation themselves.

You can also create a Document by calling a method on a "DOM Implementation" object. You can get this object either by calling the getDOMImplementation function in the xml.dom package or the !xml.dom.minidom module. Once you have a Document, you can add child nodes to it to populate the DOM:

from xml.dom.minidom import getDOMImplementation

impl = getDOMImplementation()

newdoc = impl.createDocument(None, "some_tag", None)
top_element = newdoc.documentElement
text = newdoc.createTextNode('Some textual content.')
top_element.appendChild(text)

Once you have a DOM document object, you can access the parts of your XML document through its properties and methods. These properties are defined in the DOM specification. The main property of the document object is the documentElement property. It gives you the main element in the XML document: the one that holds all others. Here is an example program:

dom3 = parseString("<myxml>Some data</myxml>")
assert dom3.documentElement.tagName == "myxml"

When you are finished with a DOM tree, you may optionally call the unlink method to encourage early cleanup of the now-unneeded objects. unlink is an !xml.dom.minidom-specific extension to the DOM API that renders the node and its descendants essentially useless. Otherwise, Python's garbage collector will eventually take care of the objects in the tree.

DOM Objects

The definition of the DOM API for Python is given as part of the xml.dom module documentation. This section lists the differences between the API and !xml.dom.minidom.

with xml.dom.minidom.parse(datasource) as dom:
    ... # Work with dom.

DOM Example

This example program is a fairly realistic example of a simple program. In this particular case, we do not take much advantage of the flexibility of the DOM.

minidom and the DOM standard

The !xml.dom.minidom module is essentially a DOM 1.0-compatible DOM with some DOM 2 features (primarily namespace features).

Usage of the DOM interface in Python is straight-forward. The following mapping rules apply:

• Interfaces are accessed through instance objects. Applications should not instantiate the classes themselves; they should use the creator functions available on the Document object. Derived interfaces support all operations (and attributes) from the base interfaces, plus any new operations.

• Operations are used as methods. Since the DOM uses only in parameters, the arguments are passed in normal order (from left to right). There are no optional arguments. void operations return None.

• IDL attributes map to instance attributes. For compatibility with the OMG IDL language mapping for Python, an attribute foo can also be accessed through accessor methods _get_foo and _set_foo. readonly attributes must not be changed; this is not enforced at runtime.

• The types short int, unsigned int, unsigned long long, and boolean all map to Python integer objects.

• The type DOMString maps to Python strings. !xml.dom.minidom supports either bytes or strings, but will normally produce strings. Values of type DOMString may also be None where allowed to have the IDL null value by the DOM specification from the W3C.

• const declarations map to variables in their respective scope (e.g. xml.dom.minidom.Node.PROCESSING_INSTRUCTION_NODE); they must not be changed.

• DOMException is currently not supported in !xml.dom.minidom. Instead, !xml.dom.minidom uses standard Python exceptions such as TypeError and AttributeError.

• Each of the ~xml.dom.NodeList and ~xml.dom.NamedNodeMap interfaces has two implementations, which provide additional methods and operations.

  ~xml.dom.Node.childNodes is a subclass of list, or, for nodes which cannot have children, a subclass of tuple. It supports iteration, concatenation, indexing and slicing.

  ~xml.dom.Node.attributes supports len(), the in operator, subscription by a name or by a (namespaceURI, localName) tuple, assignment and deletion, and the methods !get, !keys, !keysNS, !values, !items and !itemsNS. ~xml.dom.DocumentType.entities and ~xml.dom.DocumentType.notations are read-only and support only len() and subscription by a name.

• ~xml.dom.Document.strictErrorChecking is always False.

  3.16 Previously, ~xml.dom.Attr.specified was always False.

• The constraints of the DOM are now enforced, and the corresponding exceptions are raised.

  3.16 Previously, many invalid operations silently succeeded and produced an invalid document, but removing an absent attribute raised ~xml.dom.NotFoundErr.

  3.16 Namespaces are now validated in the factory methods and when setting ~xml.dom.Node.prefix of an attribute.

The following interfaces have no implementation in !xml.dom.minidom:

• DOMTimeStamp

This reflects information in the XML document that is not of general utility to most DOM users.

Footnotes

[^1]: The encoding name included in the XML output should conform to the appropriate standards. For example, "UTF-8" is valid, but "UTF8" is not valid in an XML document's declaration, even though Python accepts it as an encoding name. See https://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl and https://www.iana.org/assignments/character-sets/character-sets.xhtml.