Changeset 391 for python/trunk/Doc/library/xml.dom.minidom.rst

Timestamp:

Mar 19, 2014, 11:31:01 PM (11 years ago)

Author:

dmik

Message:

python: Merge vendor 2.7.6 to trunk.

Location:

python/trunk

Files:

• . (modified) (1 prop)
• Doc/library/xml.dom.minidom.rst (modified) (6 diffs)

python/trunk/Doc/library/xml.dom.minidom.rst

@@ -1 @@
-
-:mod:`xml.dom.minidom` --- Lightweight DOM implementation
-=========================================================
+:mod:`xml.dom.minidom` --- Minimal DOM implementation
+=====================================================
 
 .. module:: xml.dom.minidom
-   :synopsis: Lightweight Document Object Model (DOM) implementation.
+   :synopsis: Minimal Document Object Model (DOM) implementation.
 .. moduleauthor:: Paul Prescod <paul@prescod.net>
 .. sectionauthor:: Paul Prescod <paul@prescod.net>
@@ -12 +11 @@
 .. versionadded:: 2.0
 
-:mod:`xml.dom.minidom` is a light-weight implementation of the Document Object
-Model interface.  It is intended to be simpler than the full DOM and also
-significantly smaller.
+**Source code:** :source:`Lib/xml/dom/minidom.py`
+
+--------------
+
+:mod:`xml.dom.minidom` is a minimal implementation of the Document Object
+Model interface, with an API similar to that in other languages.  It is intended
+to be simpler than the full DOM and also significantly smaller.  Users who are
+not already proficient with the DOM should consider using the
+:mod:`xml.etree.ElementTree` module for their XML processing instead
+
+
+.. warning::
+
+   The :mod:`xml.dom.minidom` module is not secure against
+   maliciously constructed data.  If you need to parse untrusted or
+   unauthenticated data see :ref:`xml-vulnerabilities`.
+
 
 DOM applications typically start by parsing some XML into a DOM.  With
@@ -46 +59 @@
 
    Return a :class:`Document` that represents the *string*. This method creates a
-   :class:`StringIO` object for the string and passes that on to :func:`parse`.
+   :class:`~StringIO.StringIO` object for the string and passes that on to :func:`parse`.
 
 Both functions return a :class:`Document` object representing the content of the
@@ -86 +99 @@
    assert dom3.documentElement.tagName == "myxml"
 
-When you are finished with a DOM, you should clean it up.  This is necessary
-because some versions of Python do not support garbage collection of objects
-that refer to each other in a cycle.  Until this restriction is removed from all
-versions of Python, it is safest to write your code as if cycles would not be
-cleaned up.
-
-The way to clean up a DOM is to call its :meth:`unlink` method::
-
-   dom1.unlink()
-   dom2.unlink()
-   dom3.unlink()
-
-:meth:`unlink` is a :mod:`xml.dom.minidom`\ -specific extension to the DOM API.
-After calling :meth:`unlink` on a node, the node and its descendants are
-essentially useless.
-
+When you are finished with a DOM tree, you may optionally call the
+:meth:`unlink` method to encourage early cleanup of the now-unneeded
+objects.  :meth:`unlink` is a :mod:`xml.dom.minidom`\ -specific
+extension to the DOM API that renders the node and its descendants are
+essentially useless.  Otherwise, Python's garbage collector will
+eventually take care of the objects in the tree.
 
 .. seealso::
@@ -129 +132 @@
 
 
-.. method:: Node.writexml(writer[, indent=""[, addindent=""[, newl=""[, encoding=""]]]])
+.. method:: Node.writexml(writer, indent="", addindent="", newl="")
 
    Write XML to the writer object.  The writer should have a :meth:`write` method
@@ -137 +140 @@
    specifies the string to use to terminate newlines.
 
+   For the :class:`Document` node, an additional keyword argument *encoding* can
+   be used to specify the encoding field of the XML header.
+
    .. versionchanged:: 2.1
       The optional keyword parameters *indent*, *addindent*, and *newl* were added to