Close #18990: remove root attribute from XMLPullParser

- this was an internal implementation detail for iterparse
- this has been changed to use a new private method instead
- XMLPullParser.close docs are now more explicit about not
  returning a root element and instead direct users towards
  read_events
- also added missing docstrings and clarified some details
  related to exactly *when* events are consumed from the
  internal queue

(Initial patch by Stefan Behnel)

1 files changed, 10 insertions, 3 deletions

diff --git a/Doc/library/xml.etree.elementtree.rst b/Doc/library/xml.etree.elementtree.rst
index 97550edaaa..c15041f2e0 100644
--- a/Doc/library/xml.etree.elementtree.rst
+++ b/Doc/library/xml.etree.elementtree.rst
@@ -1031,15 +1031,22 @@ XMLPullParser Objects
 
    .. method:: close()
 
-      Signal the parser that the data stream is terminated.
+      Signal the parser that the data stream is terminated. Unlike
+      :meth:`XMLParser.close`, this method always returns :const:`None`.
+      Any events not yet retrieved when the parser is closed can still be
+      read with :meth:`read_events`.
 
    .. method:: read_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:`read_events` will not be yielded again.
+      encountered :class:`Element` object.
+
+      Events provided in a previous call to :meth:`read_events` will not be
+      yielded again. As events are consumed from the internal queue only as
+      they are retrieved from the iterator, multiple readers calling
+      :meth:`read_events` in parallel will have unpredictable results.
 
    .. note::