[Python-checkins] cpython (merge 3.4 -> default): Issue #20375: Clarify ET's parsing of comments and processing instructions.

eli.bendersky python-checkins at python.org
Thu Apr 3 15:15:30 CEST 2014


http://hg.python.org/cpython/rev/5c3166ec80e1
changeset:   90117:5c3166ec80e1
parent:      90115:c9cb931b20f4
parent:      90116:871278b87c62
user:        Eli Bendersky <eliben at gmail.com>
date:        Thu Apr 03 06:15:28 2014 -0700
summary:
  Issue #20375: Clarify ET's parsing of comments and processing instructions.

Based on patch by Nikolaus Rath.

files:
  Doc/library/xml.etree.elementtree.rst |  22 +++++++++++++++
  1 files changed, 22 insertions(+), 0 deletions(-)


diff --git a/Doc/library/xml.etree.elementtree.rst b/Doc/library/xml.etree.elementtree.rst
--- a/Doc/library/xml.etree.elementtree.rst
+++ b/Doc/library/xml.etree.elementtree.rst
@@ -106,6 +106,19 @@
    '2008'
 
 
+.. note::
+
+   Not all elements of the XML input will end up as elements of the
+   parsed tree. Currently, this module skips over any XML comments,
+   processing instructions, and document type declarations in the
+   input. Nevertheless, trees built using this module's API rather
+   than parsing from XML text can have comments and processing
+   instructions in them; they will be included when generating XML
+   output. A document type declaration may be accessed by passing a
+   custom :class:`TreeBuilder` instance to the :class:`XMLParser`
+   constructor.
+
+
 .. _elementtree-pull-parsing:
 
 Pull API for non-blocking parsing
@@ -381,6 +394,10 @@
    string containing the comment string.  Returns an element instance
    representing a comment.
 
+   Note that :class:`XMLParser` skips over comments in the input
+   instead of creating comment objects for them. An :class:`ElementTree` will
+   only contain comment nodes if they have been inserted into to
+   the tree using one of the :class:`Element` methods.
 
 .. function:: dump(elem)
 
@@ -461,6 +478,11 @@
    containing the PI target.  *text* is a string containing the PI contents, if
    given.  Returns an element instance, representing a processing instruction.
 
+   Note that :class:`XMLParser` skips over processing instructions
+   in the input instead of creating comment objects for them. An
+   :class:`ElementTree` will only contain processing instruction nodes if
+   they have been inserted into to the tree using one of the
+   :class:`Element` methods.
 
 .. function:: register_namespace(prefix, uri)
 

-- 
Repository URL: http://hg.python.org/cpython


More information about the Python-checkins mailing list