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.
Warning
The xml.dom.minidom module is not secure againstmaliciously constructed data. If you need to parse untrusted orunauthenticated data see XML vulnerabilities.
DOM applications typically start by parsing some XML into a DOM. Withxml.dom.minidom, this is done through the parse functions:
from xml.dom.minidom import parse, 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>')
The parse() function can take either a filename or an open file object.
- xml.dom.minidom.parse(filename_or_file, parser=None, bufsize=None)¶
Return a
Documentfrom 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 the parseString() functioninstead:
- xml.dom.minidom.parseString(string, parser=None)¶
Return a
Documentthat represents the string. This method creates anio.StringIO object for the string and passes that on to parse().
Both functions return a Document object representing the content of thedocument.
What the parse() and parseString() 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 a Document by calling a method on a “DOMImplementation” object. You can get this object either by calling thegetDOMImplementation() function in the xml.dom package or thexml.dom.minidom module. Once you have a Document, youcan add child nodes to it to populate the DOM:
from xml.dom.minidom import getDOMImplementationimpl = 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>")assert dom3.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 an xml.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 by xml.dom.minidom.
DOM Objects¶
The definition of the DOM API for Python is given as part of the xml.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 the
Documentobject, but may be called on child nodesto discard children of that node.You can avoid calling this method explicitly by using the withstatement. The following code will automatically unlink dom when the
withblock is exited:with xml.dom.minidom.parse(datasource) as dom: ... # 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 a
write()method which matches that of the file objectinterface. The indent parameter is the indentation of the current node.The addindent parameter is the incremental indentation to use for subnodesof the current one. The newl parameter specifies the string to use toterminate newlines.For the
Documentnode, an additional keyword argument encoding canbe used to specify the encoding field of the XML header.Similarly, explicitly stating the standalone argument causes thestandalone document declarations to be added to the prologue of the XMLdocument.If the value is set to
True,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: The writexml() method now preserves the attribute order specifiedby the user.
Changed in version 3.9: The standalone parameter was added.
- Node.toxml(encoding=None, standalone=None)¶
Return a string or byte string containing the XML represented bythe DOM node.
With an explicit encoding [1] argument, the result is a bytestring in the specified encoding.With no encoding 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.
The standalone argument behaves exactly as in writexml().
Changed in version 3.8: The toxml() method now preserves the attribute order specifiedby the user.
Changed in version 3.9: The standalone 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.The encoding argument behaves like the corresponding argument oftoxml().
The standalone argument behaves exactly as in writexml().
Changed in version 3.8: The toprettyxml() method now preserves the attribute order specifiedby the user.
Changed in version 3.9: The standalone 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.
import xml.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)def getText(nodelist): rc = [] for node in nodelist: if node.nodeType == node.TEXT_NODE: rc.append(node.data) return ''.join(rc)def handleSlideshow(slideshow): print("<html>") handleSlideshowTitle(slideshow.getElementsByTagName("title")[0]) slides = slideshow.getElementsByTagName("slide") handleToc(slides) handleSlides(slides) print("</html>")def handleSlides(slides): for slide in slides: handleSlide(slide)def handleSlide(slide): handleSlideTitle(slide.getElementsByTagName("title")[0]) handlePoints(slide.getElementsByTagName("point"))def handleSlideshowTitle(title): print(f"<title>{getText(title.childNodes)}</title>")def handleSlideTitle(title): print(f"<h2>{getText(title.childNodes)}</h2>")def handlePoints(points): print("<ul>") for point in points: handlePoint(point) print("</ul>")def handlePoint(point): print(f"<li>{getText(point.childNodes)}</li>")def handleToc(slides): for slide in slides: title = slide.getElementsByTagName("title")[0] print(f"<p>{getText(title.childNodes)}</p>")handleSlideshow(dom)
minidom and the DOM standard¶
The xml.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 the
Documentobject. Derived interfaces support alloperations (and attributes) from the base interfaces, plus any new operations.Operations are used as methods. Since the DOM uses only inparameters, the arguments are passed in normal order (from left to right).There are no optional arguments.
voidoperations returnNone.IDL attributes map to instance attributes. For compatibility with the OMG IDLlanguage mapping for Python, an attribute
foocan also be accessed throughaccessor methods_get_foo()and_set_foo().readonlyattributes must not be changed; this is not enforced at runtime.The types
short int,unsigned int,unsigned long long, andbooleanall map to Python integer objects.The type
DOMStringmaps to Python strings. xml.dom.minidom supportseither bytes or strings, but will normally produce strings.Values of typeDOMStringmay also beNonewhere allowed to have the IDLnullvalue by the DOM specification from the W3C.constdeclarations map to variables in their respective scope (e.g.xml.dom.minidom.Node.PROCESSING_INSTRUCTION_NODE); they must not be changed.DOMExceptionis currently not supported in xml.dom.minidom.Instead, xml.dom.minidom uses standard Python exceptions such asTypeError and AttributeError.NodeListobjects 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 in xml.dom.minidom:
DOMTimeStampEntityReference
Most of these reflect information in the XML document that is not of generalutility to most DOM users.
Footnotes
