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.

警告

The xml.dom.minidom module is not secure againstmaliciously constructed data. If you need to parse untrusted orunauthenticated data see XML 漏洞.

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

  1. from xml.dom.minidom import parse, parseString
  2.  
  3. dom1 = parse('c:\\temp\\mydata.xml')  # parse an XML file by name
  4.  
  5. datasource = open('c:\\temp\\mydata.xml')
  6. dom2 = parse(datasource)  # parse an open file
  7.  
  8. dom3 = 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 Document 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 the parseString() functioninstead:

  • xml.dom.minidom.parseString(string, parser=None)
  • Return a Document that 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:

  1. from xml.dom.minidom import getDOMImplementation
  2.  
  3. impl = getDOMImplementation()
  4.  
  5. newdoc = impl.createDocument(None, "some_tag", None)
  6. top_element = newdoc.documentElement
  7. text = newdoc.createTextNode('Some textual content.')
  8. 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:

  1. dom3 = parseString("<myxml>Some data</myxml>")
  2. 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 descendants areessentially useless. Otherwise, Python's garbage collector willeventually 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.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 Document object, 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 thewith block is exited:

  1. with xml.dom.minidom.parse(datasource) as dom:
  2.     ... # Work with dom.
  • Node.writexml(writer, indent="", addindent="", newl="")
  • 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 Document node, an additional keyword argument encoding canbe used to specify the encoding field of the XML header.

在 3.8 版更改: The writexml() method now preserves the attribute order specifiedby the user.

  • Node.toxml(encoding=None)
  • Return a string or byte string containing the XML represented bythe DOM node.

With an explicit encoding1 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.

在 3.8 版更改: The toxml() method now preserves the attribute order specifiedby the user.

  • Node.toprettyxml(indent="\t", newl="\n", encoding=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().

在 3.8 版更改: The toprettyxml() method now preserves the attribute order specifiedby the user.

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.

  1. import xml.dom.minidom
  2.  
  3. document = """\
  4. <slideshow>
  5. <title>Demo slideshow</title>
  6. <slide><title>Slide title</title>
  7. <point>This is a demo</point>
  8. <point>Of a program for processing slides</point>
  9. </slide>
  10.  
  11. <slide><title>Another demo slide</title>
  12. <point>It is important</point>
  13. <point>To have more than</point>
  14. <point>one slide</point>
  15. </slide>
  16. </slideshow>
  17. """
  18.  
  19. dom = xml.dom.minidom.parseString(document)
  20.  
  21. def getText(nodelist):
  22.     rc = []
  23.     for node in nodelist:
  24.         if node.nodeType == node.TEXT_NODE:
  25.             rc.append(node.data)
  26.     return ''.join(rc)
  27.  
  28. def handleSlideshow(slideshow):
  29.     print("<html>")
  30.     handleSlideshowTitle(slideshow.getElementsByTagName("title")[0])
  31.     slides = slideshow.getElementsByTagName("slide")
  32.     handleToc(slides)
  33.     handleSlides(slides)
  34.     print("</html>")
  35.  
  36. def handleSlides(slides):
  37.     for slide in slides:
  38.         handleSlide(slide)
  39.  
  40. def handleSlide(slide):
  41.     handleSlideTitle(slide.getElementsByTagName("title")[0])
  42.     handlePoints(slide.getElementsByTagName("point"))
  43.  
  44. def handleSlideshowTitle(title):
  45.     print("<title>%s</title>" % getText(title.childNodes))
  46.  
  47. def handleSlideTitle(title):
  48.     print("<h2>%s</h2>" % getText(title.childNodes))
  49.  
  50. def handlePoints(points):
  51.     print("<ul>")
  52.     for point in points:
  53.         handlePoint(point)
  54.     print("</ul>")
  55.  
  56. def handlePoint(point):
  57.     print("<li>%s</li>" % getText(point.childNodes))
  58.  
  59. def handleToc(slides):
  60.     for slide in slides:
  61.         title = slide.getElementsByTagName("title")[0]
  62.         print("<p>%s</p>" % getText(title.childNodes))
  63.  
  64. 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 Document object. 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. void operations return None.

  • IDL attributes map to instance attributes. For compatibility with the OMG IDLlanguage mapping for Python, an attribute foo can 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, andboolean all map to Python integer objects.

  • The type DOMString maps to Python strings. xml.dom.minidom supportseither bytes or strings, but will normally produce strings.Values of type DOMString may also be None 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 in xml.dom.minidom.Instead, xml.dom.minidom uses standard Python exceptions such asTypeError and AttributeError.

  • 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 in xml.dom.minidom:

  • DOMTimeStamp

  • EntityReference

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

脚注