Issue #17902: Clarify doc of ElementTree.iterparse and IncrementalParser

Based on patch by Aaron Oakley

diff --cc Doc/library/xml.etree.elementtree.rst
index d0bfed0ddaa06ceafa938ac6036bf7ac38e5dea3,00cdacda59f17f9a537f4e3d891faf75b09033bd..c0cc683068a7b6dfa46ebaae68dbddf0c17c41ea
--- 1/Doc/library/xml.etree.elementtree.rst
--- 2/Doc/library/xml.etree.elementtree.rst
+++ b/Doc/library/xml.etree.elementtree.rst
@@@ -416,14 -384,10 +416,15 @@@ Function
     and ``"end-ns"`` (the "ns" events are used to get detailed namespace
     information).  If *events* is omitted, only ``"end"`` events are reported.
     *parser* is an optional parser instance.  If not given, the standard
-    :class:`XMLParser` parser is used.  Returns an :term:`iterator` providing
+    :class:`XMLParser` parser is used.  *parser* can only use the default
+    :class:`TreeBuilder` as a target.  Returns an :term:`iterator` providing
     ``(event, elem)`` pairs.
  
 +   Note that while :func:`iterparse` builds the tree incrementally, it issues
 +   blocking reads on *source* (or the file it names).  As such, it's unsuitable
 +   for asynchronous applications where blocking reads can't be made.  For fully
 +   asynchronous parsing, see :class:`IncrementalParser`.
 +
     .. note::
  
        :func:`iterparse` only guarantees that it has seen the ">"
@@@ -869,49 -816,6 +870,49 @@@ QName Object
     :class:`QName` instances are opaque.
  
  
-    used.
 +IncrementalParser Objects
 +^^^^^^^^^^^^^^^^^^^^^^^^^
 +
 +.. class:: IncrementalParser(events=None, parser=None)
 +
 +   An incremental, event-driven parser suitable for non-blocking applications.
 +   *events* is a sequence of events to report back.  The supported events are
 +   the strings ``"start"``, ``"end"``, ``"start-ns"`` and ``"end-ns"`` (the "ns"
 +   events are used to get detailed namespace information).  If *events* is
 +   omitted, only ``"end"`` events are reported.  *parser* is an optional
 +   parser instance.  If not given, the standard :class:`XMLParser` parser is
++   used.  *parser* can only use the default :class:`TreeBuilder` as a target.
 +
 +   .. method:: data_received(data)
 +
 +      Feed the given bytes data to the incremental parser.
 +
 +   .. method:: eof_received()
 +
 +      Signal the incremental parser that the data stream is terminated.
 +
 +   .. method:: events()
 +
 +      Iterate over the events which have been encountered in the data fed
 +      to the parser.  This method yields ``(event, elem)`` pairs, where
 +      *event* is a string representing the type of event (e.g. ``"end"``)
 +      and *elem* is the encountered :class:`Element` object.  Events
 +      provided in a previous call to :meth:`events` will not be yielded
 +      again.
 +
 +   .. note::
 +
 +      :class:`IncrementalParser` 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.
 +
 +   .. versionadded:: 3.4
 +
 +
  .. _elementtree-treebuilder-objects:
  
  TreeBuilder Objects