From: Georg Brandl <georg@python.org>
Date: Thu, 1 Jan 2009 11:46:51 +0000 (+0000)
Subject: #4100: note that element children are not necessarily present on "start" events.
X-Git-Tag: v2.7a1~2451
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=fb222635866ced44125822482230a0cf24d0d132;p=thirdparty%2FPython%2Fcpython.git

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

diff --git a/Doc/library/xml.etree.elementtree.rst b/Doc/library/xml.etree.elementtree.rst
index cdc774ec07f6..b17d5103aa11 100644
--- a/Doc/library/xml.etree.elementtree.rst
+++ b/Doc/library/xml.etree.elementtree.rst
@@ -94,6 +94,16 @@ Functions
    *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])