| 1 |
:mod:`!xml.dom.minidom` --- Minimal DOM implementation |
| 2 |
====================================================== |
| 3 |
|
| 4 |
.. module:: xml.dom.minidom |
| 5 |
:synopsis: Minimal Document Object Model (DOM) implementation. |
| 6 |
|
| 7 |
.. moduleauthor:: Paul Prescod <[email protected]> |
| 8 |
.. sectionauthor:: Paul Prescod <[email protected]> |
| 9 |
.. sectionauthor:: Martin v. Löwis <[email protected]> |
| 10 |
|
| 11 |
**Source code:** :source:`Lib/xml/dom/minidom.py` |
| 12 |
|
| 13 |
-------------- |
| 14 |
|
| 15 |
:mod:`!xml.dom.minidom` is a minimal implementation of the Document Object |
| 16 |
Model interface, with an API similar to that in other languages. It is intended |
| 17 |
to be simpler than the full DOM and also significantly smaller. Users who are |
| 18 |
not already proficient with the DOM should consider using the |
| 19 |
:mod:`xml.etree.ElementTree` module for their XML processing instead. |
| 20 |
|
| 21 |
|
| 22 |
.. note:: |
| 23 |
|
| 24 |
If you need to parse untrusted or unauthenticated data, see |
| 25 |
:ref:`xml-security`. |
| 26 |
|
| 27 |
|
| 28 |
DOM applications typically start by parsing some XML into a DOM. With |
| 29 |
:mod:`!xml.dom.minidom`, this is done through the parse functions:: |
| 30 |
|
| 31 |
from xml.dom.minidom import parse, parseString |
| 32 |
|
| 33 |
dom1 = parse('c:\\temp\\mydata.xml') # parse an XML file by name |
| 34 |
|
| 35 |
datasource = open('c:\\temp\\mydata.xml') |
| 36 |
dom2 = parse(datasource) # parse an open file |
| 37 |
|
| 38 |
dom3 = parseString('<myxml>Some data<empty/> some more data</myxml>') |
| 39 |
|
| 40 |
The :func:`parse` function can take either a filename or an open file object. |
| 41 |
|
| 42 |
|
| 43 |
.. function:: parse(filename_or_file, parser=None, bufsize=None) |
| 44 |
|
| 45 |
Return a :class:`Document` from the given input. *filename_or_file* may be |
| 46 |
either a file name, or a file-like object. *parser*, if given, must be a SAX2 |
| 47 |
parser object. This function will change the document handler of the parser and |
| 48 |
activate namespace support; other parser configuration (like setting an entity |
| 49 |
resolver) must have been done in advance. |
| 50 |
|
| 51 |
If you have XML in a string, you can use the :func:`parseString` function |
| 52 |
instead: |
| 53 |
|
| 54 |
|
| 55 |
.. function:: parseString(string, parser=None) |
| 56 |
|
| 57 |
Return a :class:`Document` that represents the *string*. This method creates an |
| 58 |
:class:`io.StringIO` object for the string and passes that on to :func:`parse`. |
| 59 |
|
| 60 |
Both functions return a :class:`Document` object representing the content of the |
| 61 |
document. |
| 62 |
|
| 63 |
What the :func:`parse` and :func:`parseString` functions do is connect an XML |
| 64 |
parser with a "DOM builder" that can accept parse events from any SAX parser and |
| 65 |
convert them into a DOM tree. The names of the functions are perhaps misleading, |
| 66 |
but are easy to grasp when learning the interfaces. The parsing of the document |
| 67 |
will be completed before these functions return; it's simply that these |
| 68 |
functions do not provide a parser implementation themselves. |
| 69 |
|
| 70 |
You can also create a :class:`Document` by calling a method on a "DOM |
| 71 |
Implementation" object. You can get this object either by calling the |
| 72 |
:func:`getDOMImplementation` function in the :mod:`xml.dom` package or the |
| 73 |
:mod:`!xml.dom.minidom` module. Once you have a :class:`Document`, you |
| 74 |
can add child nodes to it to populate the DOM:: |
| 75 |
|
| 76 |
from xml.dom.minidom import getDOMImplementation |
| 77 |
|
| 78 |
impl = getDOMImplementation() |
| 79 |
|
| 80 |
newdoc = impl.createDocument(None, "some_tag", None) |
| 81 |
top_element = newdoc.documentElement |
| 82 |
text = newdoc.createTextNode('Some textual content.') |
| 83 |
top_element.appendChild(text) |
| 84 |
|
| 85 |
Once you have a DOM document object, you can access the parts of your XML |
| 86 |
document through its properties and methods. These properties are defined in |
| 87 |
the DOM specification. The main property of the document object is the |
| 88 |
:attr:`documentElement` property. It gives you the main element in the XML |
| 89 |
document: the one that holds all others. Here is an example program:: |
| 90 |
|
| 91 |
dom3 = parseString("<myxml>Some data</myxml>") |
| 92 |
assert dom3.documentElement.tagName == "myxml" |
| 93 |
|
| 94 |
When you are finished with a DOM tree, you may optionally call the |
| 95 |
:meth:`unlink` method to encourage early cleanup of the now-unneeded |
| 96 |
objects. :meth:`unlink` is an :mod:`!xml.dom.minidom`\ -specific |
| 97 |
extension to the DOM API that renders the node and its descendants |
| 98 |
essentially useless. Otherwise, Python's garbage collector will |
| 99 |
eventually take care of the objects in the tree. |
| 100 |
|
| 101 |
.. seealso:: |
| 102 |
|
| 103 |
`Document Object Model (DOM) Level 1 Specification <https://www.w3.org/TR/REC-DOM-Level-1/>`_ |
| 104 |
The W3C recommendation for the DOM supported by :mod:`!xml.dom.minidom`. |
| 105 |
|
| 106 |
|
| 107 |
.. _minidom-objects: |
| 108 |
|
| 109 |
DOM Objects |
| 110 |
----------- |
| 111 |
|
| 112 |
The definition of the DOM API for Python is given as part of the :mod:`xml.dom` |
| 113 |
module documentation. This section lists the differences between the API and |
| 114 |
:mod:`!xml.dom.minidom`. |
| 115 |
|
| 116 |
|
| 117 |
.. method:: Node.unlink() |
| 118 |
|
| 119 |
Break internal references within the DOM so that it will be garbage collected on |
| 120 |
versions of Python without cyclic GC. Even when cyclic GC is available, using |
| 121 |
this can make large amounts of memory available sooner, so calling this on DOM |
| 122 |
objects as soon as they are no longer needed is good practice. This only needs |
| 123 |
to be called on the :class:`Document` object, but may be called on child nodes |
| 124 |
to discard children of that node. |
| 125 |
|
| 126 |
You can avoid calling this method explicitly by using the :keyword:`with` |
| 127 |
statement. The following code will automatically unlink *dom* when the |
| 128 |
:keyword:`!with` block is exited:: |
| 129 |
|
| 130 |
with xml.dom.minidom.parse(datasource) as dom: |
| 131 |
... # Work with dom. |
| 132 |
|
| 133 |
|
| 134 |
.. method:: Node.writexml(writer, indent="", addindent="", newl="", \ |
| 135 |
encoding=None, standalone=None) |
| 136 |
|
| 137 |
Write XML to the writer object. The writer receives texts but not bytes as input, |
| 138 |
it should have a :meth:`write` method which matches that of the file object |
| 139 |
interface. The *indent* parameter is the indentation of the current node. |
| 140 |
The *addindent* parameter is the incremental indentation to use for subnodes |
| 141 |
of the current one. The *newl* parameter specifies the string to use to |
| 142 |
terminate newlines. |
| 143 |
|
| 144 |
For the :class:`Document` node, an additional keyword argument *encoding* can |
| 145 |
be used to specify the encoding field of the XML header. |
| 146 |
|
| 147 |
Similarly, explicitly stating the *standalone* argument causes the |
| 148 |
standalone document declarations to be added to the prologue of the XML |
| 149 |
document. |
| 150 |
If the value is set to ``True``, ``standalone="yes"`` is added, |
| 151 |
otherwise it is set to ``"no"``. |
| 152 |
Not stating the argument will omit the declaration from the document. |
| 153 |
|
| 154 |
.. versionchanged:: 3.8 |
| 155 |
The :meth:`writexml` method now preserves the attribute order specified |
| 156 |
by the user. |
| 157 |
|
| 158 |
.. versionchanged:: 3.9 |
| 159 |
The *standalone* parameter was added. |
| 160 |
|
| 161 |
.. method:: Node.toxml(encoding=None, standalone=None) |
| 162 |
|
| 163 |
Return a string or byte string containing the XML represented by |
| 164 |
the DOM node. |
| 165 |
|
| 166 |
With an explicit *encoding* [1]_ argument, the result is a byte |
| 167 |
string in the specified encoding. |
| 168 |
With no *encoding* argument, the result is a Unicode string, and the |
| 169 |
XML declaration in the resulting string does not specify an |
| 170 |
encoding. Encoding this string in an encoding other than UTF-8 is |
| 171 |
likely incorrect, since UTF-8 is the default encoding of XML. |
| 172 |
|
| 173 |
The *standalone* argument behaves exactly as in :meth:`writexml`. |
| 174 |
|
| 175 |
.. versionchanged:: 3.8 |
| 176 |
The :meth:`toxml` method now preserves the attribute order specified |
| 177 |
by the user. |
| 178 |
|
| 179 |
.. versionchanged:: 3.9 |
| 180 |
The *standalone* parameter was added. |
| 181 |
|
| 182 |
.. method:: Node.toprettyxml(indent="\t", newl="\n", encoding=None, \ |
| 183 |
standalone=None) |
| 184 |
|
| 185 |
Return a pretty-printed version of the document. *indent* specifies the |
| 186 |
indentation string and defaults to a tabulator; *newl* specifies the string |
| 187 |
emitted at the end of each line and defaults to ``\n``. |
| 188 |
|
| 189 |
The *encoding* argument behaves like the corresponding argument of |
| 190 |
:meth:`toxml`. |
| 191 |
|
| 192 |
The *standalone* argument behaves exactly as in :meth:`writexml`. |
| 193 |
|
| 194 |
.. versionchanged:: 3.8 |
| 195 |
The :meth:`toprettyxml` method now preserves the attribute order specified |
| 196 |
by the user. |
| 197 |
|
| 198 |
.. versionchanged:: 3.9 |
| 199 |
The *standalone* parameter was added. |
| 200 |
|
| 201 |
.. _dom-example: |
| 202 |
|
| 203 |
DOM Example |
| 204 |
----------- |
| 205 |
|
| 206 |
This example program is a fairly realistic example of a simple program. In this |
| 207 |
particular case, we do not take much advantage of the flexibility of the DOM. |
| 208 |
|
| 209 |
.. literalinclude:: ../includes/minidom-example.py |
| 210 |
|
| 211 |
|
| 212 |
.. _minidom-and-dom: |
| 213 |
|
| 214 |
minidom and the DOM standard |
| 215 |
---------------------------- |
| 216 |
|
| 217 |
The :mod:`!xml.dom.minidom` module is essentially a DOM 1.0-compatible DOM with |
| 218 |
some DOM 2 features (primarily namespace features). |
| 219 |
|
| 220 |
Usage of the DOM interface in Python is straight-forward. The following mapping |
| 221 |
rules apply: |
| 222 |
|
| 223 |
* Interfaces are accessed through instance objects. Applications should not |
| 224 |
instantiate the classes themselves; they should use the creator functions |
| 225 |
available on the :class:`Document` object. Derived interfaces support all |
| 226 |
operations (and attributes) from the base interfaces, plus any new operations. |
| 227 |
|
| 228 |
* Operations are used as methods. Since the DOM uses only :keyword:`in` |
| 229 |
parameters, the arguments are passed in normal order (from left to right). |
| 230 |
There are no optional arguments. ``void`` operations return ``None``. |
| 231 |
|
| 232 |
* IDL attributes map to instance attributes. For compatibility with the OMG IDL |
| 233 |
language mapping for Python, an attribute ``foo`` can also be accessed through |
| 234 |
accessor methods :meth:`_get_foo` and :meth:`_set_foo`. ``readonly`` |
| 235 |
attributes must not be changed; this is not enforced at runtime. |
| 236 |
|
| 237 |
* The types ``short int``, ``unsigned int``, ``unsigned long long``, and |
| 238 |
``boolean`` all map to Python integer objects. |
| 239 |
|
| 240 |
* The type ``DOMString`` maps to Python strings. :mod:`!xml.dom.minidom` supports |
| 241 |
either bytes or strings, but will normally produce strings. |
| 242 |
Values of type ``DOMString`` may also be ``None`` where allowed to have the IDL |
| 243 |
``null`` value by the DOM specification from the W3C. |
| 244 |
|
| 245 |
* ``const`` declarations map to variables in their respective scope (e.g. |
| 246 |
``xml.dom.minidom.Node.PROCESSING_INSTRUCTION_NODE``); they must not be changed. |
| 247 |
|
| 248 |
* ``DOMException`` is currently not supported in :mod:`!xml.dom.minidom`. |
| 249 |
Instead, :mod:`!xml.dom.minidom` uses standard Python exceptions such as |
| 250 |
:exc:`TypeError` and :exc:`AttributeError`. |
| 251 |
|
| 252 |
* :class:`NodeList` objects are implemented using Python's built-in list type. |
| 253 |
These objects provide the interface defined in the DOM specification, but with |
| 254 |
earlier versions of Python they do not support the official API. They are, |
| 255 |
however, much more "Pythonic" than the interface defined in the W3C |
| 256 |
recommendations. |
| 257 |
|
| 258 |
The following interfaces have no implementation in :mod:`!xml.dom.minidom`: |
| 259 |
|
| 260 |
* :class:`DOMTimeStamp` |
| 261 |
|
| 262 |
* :class:`EntityReference` |
| 263 |
|
| 264 |
Most of these reflect information in the XML document that is not of general |
| 265 |
utility to most DOM users. |
| 266 |
|
| 267 |
.. rubric:: Footnotes |
| 268 |
|
| 269 |
.. [1] The encoding name included in the XML output should conform to |
| 270 |
the appropriate standards. For example, "UTF-8" is valid, but |
| 271 |
"UTF8" is not valid in an XML document's declaration, even though |
| 272 |
Python accepts it as an encoding name. |
| 273 |
See https://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl |
| 274 |
and https://www.iana.org/assignments/character-sets/character-sets.xhtml. |