[Python-checkins] r68116 - python/trunk/Doc/library/xml.etree.elementtree.rst

[georg.brandl]

Author: georg.brandl
Date: Thu Jan  1 12:46:51 2009
New Revision: 68116

Log:
#4100: note that element children are not necessarily present on "start" events.


Modified:
   python/trunk/Doc/library/xml.etree.elementtree.rst

Modified: python/trunk/Doc/library/xml.etree.elementtree.rst
==============================================================================
--- python/trunk/Doc/library/xml.etree.elementtree.rst	(original)
+++ python/trunk/Doc/library/xml.etree.elementtree.rst	Thu Jan  1 12:46:51 2009
@@ -94,6 +94,16 @@
    *events* is a list of events to report back.  If omitted, only "end" events are
    reported. Returns an :term:`iterator` providing ``(event, elem)`` pairs.
 
+   .. note::
+
+      :func:`iterparse` only guarantees that it has seen the ">"
+      character of a starting tag when it emits a "start" event, so the
+      attributes are defined, but the contents of the text and tail attributes
+      are undefined at that point.  The same applies to the element children;
+      they may or may not be present.
+
+      If you need a fully populated element, look for "end" events instead.
+
 
 .. function:: parse(source[, parser])