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

[eli.bendersky]

http://hg.python.org/cpython/rev/871278b87c62
changeset:   90116:871278b87c62
branch:      3.4
parent:      90113:095fbf03cad7
user:        Eli Bendersky <eliben at gmail.com>
date:        Thu Apr 03 06:14:38 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