xml.dom.minidom — Minimal DOM implementation

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

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

Note

If you need to parse untrusted or unauthenticated data, seeXML security.

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

fromxml.dom.minidomimportparse,parseStringdom1=parse('c:\\temp\\mydata.xml')# parse an XML file by namedatasource=open('c:\\temp\\mydata.xml')dom2=parse(datasource)# parse an open filedom3=parseString('<myxml>Some data<empty/> some more data</myxml>')

Theparse() function can take either a filename or an open file object.

xml.dom.minidom.parse(filename_or_file,parser=None,bufsize=None)

Return aDocument from the given input.filename_or_file may beeither a file name, or a file-like object.parser, if given, must be a SAX2parser object. This function will change the document handler of the parser andactivate namespace support; other parser configuration (like setting an entityresolver) must have been done in advance.

If you have XML in a string, you can use theparseString() functioninstead:

xml.dom.minidom.parseString(string,parser=None)

Return aDocument that represents thestring. This method creates anio.StringIO object for the string and passes that on toparse().

Both functions return aDocument object representing the content of thedocument.

What theparse() andparseString() functions do is connect an XMLparser with a “DOM builder” that can accept parse events from any SAX parser andconvert them into a DOM tree. The name of the functions are perhaps misleading,but are easy to grasp when learning the interfaces. The parsing of the documentwill be completed before these functions return; it’s simply that thesefunctions do not provide a parser implementation themselves.

You can also create aDocument by calling a method on a “DOMImplementation” object. You can get this object either by calling thegetDOMImplementation() function in thexml.dom package or thexml.dom.minidom module. Once you have aDocument, youcan add child nodes to it to populate the DOM:

fromxml.dom.minidomimportgetDOMImplementationimpl=getDOMImplementation()newdoc=impl.createDocument(None,"some_tag",None)top_element=newdoc.documentElementtext=newdoc.createTextNode('Some textual content.')top_element.appendChild(text)

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

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

When you are finished with a DOM tree, you may optionally call theunlink() method to encourage early cleanup of the now-unneededobjects.unlink() is anxml.dom.minidom-specificextension to the DOM API that renders the node and its descendantsessentially useless. Otherwise, Python’s garbage collector willeventually take care of the objects in the tree.

See also

Document Object Model (DOM) Level 1 Specification

The W3C recommendation for the DOM supported byxml.dom.minidom.

DOM Objects

The definition of the DOM API for Python is given as part of thexml.dommodule documentation. This section lists the differences between the API andxml.dom.minidom.

Node.unlink()

Break internal references within the DOM so that it will be garbage collected onversions of Python without cyclic GC. Even when cyclic GC is available, usingthis can make large amounts of memory available sooner, so calling this on DOMobjects as soon as they are no longer needed is good practice. This only needsto be called on theDocument object, but may be called on child nodesto discard children of that node.

You can avoid calling this method explicitly by using thewithstatement. The following code will automatically unlinkdom when thewith block is exited:

withxml.dom.minidom.parse(datasource)asdom:...# Work with dom.
Node.writexml(writer,indent='',addindent='',newl='',encoding=None,standalone=None)

Write XML to the writer object. The writer receives texts but not bytes as input,it should have awrite() method which matches that of the file objectinterface. Theindent parameter is the indentation of the current node.Theaddindent parameter is the incremental indentation to use for subnodesof the current one. Thenewl parameter specifies the string to use toterminate newlines.

For theDocument node, an additional keyword argumentencoding canbe used to specify the encoding field of the XML header.

Similarly, explicitly stating thestandalone argument causes thestandalone document declarations to be added to the prologue of the XMLdocument.If the value is set toTrue,standalone="yes" is added,otherwise it is set to"no".Not stating the argument will omit the declaration from the document.

Changed in version 3.8:Thewritexml() method now preserves the attribute order specifiedby the user.

Changed in version 3.9:Thestandalone parameter was added.

Node.toxml(encoding=None,standalone=None)

Return a string or byte string containing the XML represented bythe DOM node.

With an explicitencoding[1] argument, the result is a bytestring in the specified encoding.With noencoding argument, the result is a Unicode string, and theXML declaration in the resulting string does not specify anencoding. Encoding this string in an encoding other than UTF-8 islikely incorrect, since UTF-8 is the default encoding of XML.

Thestandalone argument behaves exactly as inwritexml().

Changed in version 3.8:Thetoxml() method now preserves the attribute order specifiedby the user.

Changed in version 3.9:Thestandalone parameter was added.

Node.toprettyxml(indent='\t',newl='\n',encoding=None,standalone=None)

Return a pretty-printed version of the document.indent specifies theindentation string and defaults to a tabulator;newl specifies the stringemitted at the end of each line and defaults to\n.

Theencoding argument behaves like the corresponding argument oftoxml().

Thestandalone argument behaves exactly as inwritexml().

Changed in version 3.8:Thetoprettyxml() method now preserves the attribute order specifiedby the user.

Changed in version 3.9:Thestandalone parameter was added.

DOM Example

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

importxml.dom.minidomdocument="""\<slideshow><title>Demo slideshow</title><slide><title>Slide title</title><point>This is a demo</point><point>Of a program for processing slides</point></slide><slide><title>Another demo slide</title><point>It is important</point><point>To have more than</point><point>one slide</point></slide></slideshow>"""dom=xml.dom.minidom.parseString(document)defgetText(nodelist):rc=[]fornodeinnodelist:ifnode.nodeType==node.TEXT_NODE:rc.append(node.data)return''.join(rc)defhandleSlideshow(slideshow):print("<html>")handleSlideshowTitle(slideshow.getElementsByTagName("title")[0])slides=slideshow.getElementsByTagName("slide")handleToc(slides)handleSlides(slides)print("</html>")defhandleSlides(slides):forslideinslides:handleSlide(slide)defhandleSlide(slide):handleSlideTitle(slide.getElementsByTagName("title")[0])handlePoints(slide.getElementsByTagName("point"))defhandleSlideshowTitle(title):print(f"<title>{getText(title.childNodes)}</title>")defhandleSlideTitle(title):print(f"<h2>{getText(title.childNodes)}</h2>")defhandlePoints(points):print("<ul>")forpointinpoints:handlePoint(point)print("</ul>")defhandlePoint(point):print(f"<li>{getText(point.childNodes)}</li>")defhandleToc(slides):forslideinslides:title=slide.getElementsByTagName("title")[0]print(f"<p>{getText(title.childNodes)}</p>")handleSlideshow(dom)

minidom and the DOM standard

Thexml.dom.minidom module is essentially a DOM 1.0-compatible DOM withsome DOM 2 features (primarily namespace features).

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

  • Interfaces are accessed through instance objects. Applications should notinstantiate the classes themselves; they should use the creator functionsavailable on theDocument object. Derived interfaces support alloperations (and attributes) from the base interfaces, plus any new operations.

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

  • IDL attributes map to instance attributes. For compatibility with the OMG IDLlanguage mapping for Python, an attributefoo can also be accessed throughaccessor methods_get_foo() and_set_foo().readonlyattributes must not be changed; this is not enforced at runtime.

  • The typesshortint,unsignedint,unsignedlonglong, andboolean all map to Python integer objects.

  • The typeDOMString maps to Python strings.xml.dom.minidom supportseither bytes or strings, but will normally produce strings.Values of typeDOMString may also beNone where allowed to have the IDLnull 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 inxml.dom.minidom.Instead,xml.dom.minidom uses standard Python exceptions such asTypeError andAttributeError.

  • NodeList objects are implemented using Python’s built-in list type.These objects provide the interface defined in the DOM specification, but withearlier versions of Python they do not support the official API. They are,however, much more “Pythonic” than the interface defined in the W3Crecommendations.

The following interfaces have no implementation inxml.dom.minidom:

  • DOMTimeStamp

  • EntityReference

Most of these reflect information in the XML document that is not of generalutility to most DOM users.

Footnotes

[1]

The encoding name included in the XML output should conform tothe appropriate standards. For example, “UTF-8” is valid, but“UTF8” is not valid in an XML document’s declaration, even thoughPython accepts it as an encoding name.Seehttps://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDeclandhttps://www.iana.org/assignments/character-sets/character-sets.xhtml.