rest25/library/xml.dom.minidom.rst => rest262/library/xml.dom.minidom.rst
103
104
105.. seealso::
106
107   `Document Object Model (DOM) Level 1 Specification <http://www.w3.org/TR/REC-DOM-Level-1/>`_
108      The W3C recommendation for the DOM supported by :mod:`xml.dom.minidom`.
109
110
n111-.. _dom-objects:
n111+.. _minidom-objects:
112
113DOM Objects
114-----------
115
116The definition of the DOM API for Python is given as part of the :mod:`xml.dom`
117module documentation.  This section lists the differences between the API and
118:mod:`xml.dom.minidom`.
119
123   Break internal references within the DOM so that it will be garbage collected on
124   versions of Python without cyclic GC.  Even when cyclic GC is available, using
125   this can make large amounts of memory available sooner, so calling this on DOM
126   objects as soon as they are no longer needed is good practice.  This only needs
127   to be called on the :class:`Document` object, but may be called on child nodes
128   to discard children of that node.
129
130
n131-.. method:: Node.writexml(writer[,indent=""[,addindent=""[,newl=""]]])
n131+.. method:: Node.writexml(writer[, indent=""[, addindent=""[, newl=""[, encoding=""]]]])
132
133   Write XML to the writer object.  The writer should have a :meth:`write` method
134   which matches that of the file object interface.  The *indent* parameter is the
135   indentation of the current node.  The *addindent* parameter is the incremental
136   indentation to use for subnodes of the current one.  The *newl* parameter
137   specifies the string to use to terminate newlines.
138
139   .. versionchanged:: 2.1
140      The optional keyword parameters *indent*, *addindent*, and *newl* were added to
141      support pretty output.
142
143   .. versionchanged:: 2.3
n144-      For the :class:`Document` node, an additional keyword argument *encoding* can be
n144+      For the :class:`Document` node, an additional keyword argument
145-      used to specify the encoding field of the XML header.
145+      *encoding* can be used to specify the encoding field of the XML header.
146
147
148.. method:: Node.toxml([encoding])
149
150   Return the XML that the DOM represents as a string.
151
152   With no argument, the XML header does not specify an encoding, and the result is
153   Unicode string if the default encoding cannot represent all characters in the
154   document. Encoding this string in an encoding other than UTF-8 is likely
155   incorrect, since UTF-8 is the default encoding of XML.
156
n157-   With an explicit *encoding* argument, the result is a byte string in the
n157+   With an explicit *encoding* [1]_ argument, the result is a byte string in the
158   specified encoding. It is recommended that this argument is always specified. To
159   avoid :exc:`UnicodeError` exceptions in case of unrepresentable text data, the
160   encoding argument should be specified as "utf-8".
161
162   .. versionchanged:: 2.3
n163-      the *encoding* argument was introduced.
n163+      the *encoding* argument was introduced; see :meth:`writexml`.
164
165
n166-.. method:: Node.toprettyxml([indent[, newl]])
n166+.. method:: Node.toprettyxml([indent=""[, newl=""[, encoding=""]]])
167
168   Return a pretty-printed version of the document. *indent* specifies the
169   indentation string and defaults to a tabulator; *newl* specifies the string
170   emitted at the end of each line and defaults to ``\n``.
171
172   .. versionadded:: 2.1
173
174   .. versionchanged:: 2.3
n175-      the encoding argument; see :meth:`toxml`.
n175+      the encoding argument was introduced; see :meth:`writexml`.
176
177The following standard DOM methods have special considerations with
178:mod:`xml.dom.minidom`:
179
180
181.. method:: Node.cloneNode(deep)
182
183   Although this method was present in the version of :mod:`xml.dom.minidom`
188.. _dom-example:
189
190DOM Example
191-----------
192
193This example program is a fairly realistic example of a simple program. In this
194particular case, we do not take much advantage of the flexibility of the DOM.
195
n196- 
197-.. include:: ../includes/minidom-example.py
196+.. literalinclude:: ../includes/minidom-example.py
198-   :literal:
199
200
201.. _minidom-and-dom:
202
203minidom and the DOM standard
204----------------------------
205
206The :mod:`xml.dom.minidom` module is essentially a DOM 1.0-compatible DOM with
211
212* Interfaces are accessed through instance objects. Applications should not
213  instantiate the classes themselves; they should use the creator functions
214  available on the :class:`Document` object. Derived interfaces support all
215  operations (and attributes) from the base interfaces, plus any new operations.
216
217* Operations are used as methods. Since the DOM uses only :keyword:`in`
218  parameters, the arguments are passed in normal order (from left to right).
n219-  There are no optional arguments. :keyword:`void` operations return ``None``.
n217+  There are no optional arguments. ``void`` operations return ``None``.
220
221* IDL attributes map to instance attributes. For compatibility with the OMG IDL
222  language mapping for Python, an attribute ``foo`` can also be accessed through
n223-  accessor methods :meth:`_get_foo` and :meth:`_set_foo`.  :keyword:`readonly`
n221+  accessor methods :meth:`_get_foo` and :meth:`_set_foo`.  ``readonly``
224  attributes must not be changed; this is not enforced at runtime.
225
226* The types ``short int``, ``unsigned int``, ``unsigned long long``, and
227  ``boolean`` all map to Python integer objects.
228
229* The type ``DOMString`` maps to Python strings. :mod:`xml.dom.minidom` supports
230  either byte or Unicode strings, but will normally produce Unicode strings.
231  Values of type ``DOMString`` may also be ``None`` where allowed to have the IDL
232  ``null`` value by the DOM specification from the W3C.
233
n234-:keyword:`const` declarations map to variables in their respective scope (e.g.
n232+``const`` declarations map to variables in their respective scope (e.g.
235  ``xml.dom.minidom.Node.PROCESSING_INSTRUCTION_NODE``); they must not be changed.
236
237* ``DOMException`` is currently not supported in :mod:`xml.dom.minidom`.
238  Instead, :mod:`xml.dom.minidom` uses standard Python exceptions such as
239  :exc:`TypeError` and :exc:`AttributeError`.
240
241* :class:`NodeList` objects are implemented using Python's built-in list type.
242  Starting with Python 2.2, these objects provide the interface defined in the DOM
262
263* :class:`EntityReference`
264
265* :class:`DocumentFragment`
266
267Most of these reflect information in the XML document that is not of general
268utility to most DOM users.
269
t268+.. rubric:: Footnotes
269+ 
270+.. [#] The encoding string included in XML output should conform to the
271+   appropriate standards. For example, "UTF-8" is valid, but "UTF8" is
272+   not. See http://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl
273+   and http://www.iana.org/assignments/character-sets .
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op