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)
diff --git a/Doc/library/xml.etree.elementtree.rst b/Doc/library/xml.etree.elementtree.rst
index 97550ed..c15041f 100644
--- a/Doc/library/xml.etree.elementtree.rst
+++ b/Doc/library/xml.etree.elementtree.rst
@@ -1031,15 +1031,22 @@
.. 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::