Issue #17741: Rename IncrementalParser and its methods.

The new names are hopefully more descriptive and consistent. If you feel you
don't agree with this change, *please* read issue 17741 first - there's a lot of
discussion in there.

2 files changed, 46 insertions, 42 deletions

diff --git a/Lib/test/test_xml_etree.py b/Lib/test/test_xml_etree.py
index dec25b5..8cc50a1 100644
--- a/Lib/test/test_xml_etree.py
+++ b/Lib/test/test_xml_etree.py
@@ -950,24 +950,24 @@ class ElementTreeTest(unittest.TestCase):
                 self.assertEqual(serialized, expected)
 
 
-class IncrementalParserTest(unittest.TestCase):
+class XMLPullParserTest(unittest.TestCase):
 
     def _feed(self, parser, data, chunk_size=None):
         if chunk_size is None:
-            parser.data_received(data)
+            parser.feed(data)
         else:
             for i in range(0, len(data), chunk_size):
-                parser.data_received(data[i:i+chunk_size])
+                parser.feed(data[i:i+chunk_size])
 
     def assert_event_tags(self, parser, expected):
-        events = parser.events()
+        events = parser.read_events()
         self.assertEqual([(action, elem.tag) for action, elem in events],
                          expected)
 
     def test_simple_xml(self):
         for chunk_size in (None, 1, 5):
             with self.subTest(chunk_size=chunk_size):
-                parser = ET.IncrementalParser()
+                parser = ET.XMLPullParser()
                 self.assert_event_tags(parser, [])
                 self._feed(parser, "<!-- comment -->\n", chunk_size)
                 self.assert_event_tags(parser, [])
@@ -985,14 +985,14 @@ class IncrementalParserTest(unittest.TestCase):
                     ])
                 self._feed(parser, "</root>\n", chunk_size)
                 self.assert_event_tags(parser, [('end', 'root')])
-                # Receiving EOF sets the `root` attribute
+                # Closing sets the `root` attribute
                 self.assertIs(parser.root, None)
-                parser.eof_received()
+                parser.close()
                 self.assertEqual(parser.root.tag, 'root')
 
-    def test_data_received_while_iterating(self):
-        parser = ET.IncrementalParser()
-        it = parser.events()
+    def test_feed_while_iterating(self):
+        parser = ET.XMLPullParser()
+        it = parser.read_events()
         self._feed(parser, "<root>\n  <element key='value'>text</element>\n")
         action, elem = next(it)
         self.assertEqual((action, elem.tag), ('end', 'element'))
@@ -1003,7 +1003,7 @@ class IncrementalParserTest(unittest.TestCase):
             next(it)
 
     def test_simple_xml_with_ns(self):
-        parser = ET.IncrementalParser()
+        parser = ET.XMLPullParser()
         self.assert_event_tags(parser, [])
         self._feed(parser, "<!-- comment -->\n")
         self.assert_event_tags(parser, [])
@@ -1021,32 +1021,32 @@ class IncrementalParserTest(unittest.TestCase):
             ])
         self._feed(parser, "</root>\n")
         self.assert_event_tags(parser, [('end', '{namespace}root')])
-        # Receiving EOF sets the `root` attribute
+        # Closing sets the `root` attribute
         self.assertIs(parser.root, None)
-        parser.eof_received()
+        parser.close()
         self.assertEqual(parser.root.tag, '{namespace}root')
 
     def test_ns_events(self):
-        parser = ET.IncrementalParser(events=('start-ns', 'end-ns'))
+        parser = ET.XMLPullParser(events=('start-ns', 'end-ns'))
         self._feed(parser, "<!-- comment -->\n")
         self._feed(parser, "<root xmlns='namespace'>\n")
         self.assertEqual(
-            list(parser.events()),
+            list(parser.read_events()),
             [('start-ns', ('', 'namespace'))])
         self._feed(parser, "<element key='value'>text</element")
         self._feed(parser, ">\n")
         self._feed(parser, "<element>text</element>tail\n")
         self._feed(parser, "<empty-element/>\n")
         self._feed(parser, "</root>\n")
-        self.assertEqual(list(parser.events()), [('end-ns', None)])
-        parser.eof_received()
+        self.assertEqual(list(parser.read_events()), [('end-ns', None)])
+        parser.close()
 
     def test_events(self):
-        parser = ET.IncrementalParser(events=())
+        parser = ET.XMLPullParser(events=())
         self._feed(parser, "<root/>\n")
         self.assert_event_tags(parser, [])
 
-        parser = ET.IncrementalParser(events=('start', 'end'))
+        parser = ET.XMLPullParser(events=('start', 'end'))
         self._feed(parser, "<!-- comment -->\n")
         self.assert_event_tags(parser, [])
         self._feed(parser, "<root>\n")
@@ -1064,12 +1064,12 @@ class IncrementalParserTest(unittest.TestCase):
             ('end', '{foo}element'),
             ])
         self._feed(parser, "</root>")
-        parser.eof_received()
+        parser.close()
         self.assertIs(parser.root, None)
         self.assert_event_tags(parser, [('end', 'root')])
         self.assertEqual(parser.root.tag, 'root')
 
-        parser = ET.IncrementalParser(events=('start',))
+        parser = ET.XMLPullParser(events=('start',))
         self._feed(parser, "<!-- comment -->\n")
         self.assert_event_tags(parser, [])
         self._feed(parser, "<root>\n")
@@ -1085,13 +1085,13 @@ class IncrementalParserTest(unittest.TestCase):
             ('start', '{foo}empty-element'),
             ])
         self._feed(parser, "</root>")
-        parser.eof_received()
+        parser.close()
         self.assertEqual(parser.root.tag, 'root')
 
     def test_events_sequence(self):
         # Test that events can be some sequence that's not just a tuple or list
         eventset = {'end', 'start'}
-        parser = ET.IncrementalParser(events=eventset)
+        parser = ET.XMLPullParser(events=eventset)
         self._feed(parser, "<foo>bar</foo>")
         self.assert_event_tags(parser, [('start', 'foo'), ('end', 'foo')])
 
@@ -1103,14 +1103,14 @@ class IncrementalParserTest(unittest.TestCase):
             def __next__(self):
                 return next(self.events)
 
-        parser = ET.IncrementalParser(events=DummyIter())
+        parser = ET.XMLPullParser(events=DummyIter())
         self._feed(parser, "<foo>bar</foo>")
         self.assert_event_tags(parser, [('start', 'foo'), ('end', 'foo')])
 
 
     def test_unknown_event(self):
         with self.assertRaises(ValueError):
-            ET.IncrementalParser(events=('start', 'end', 'bogus'))
+            ET.XMLPullParser(events=('start', 'end', 'bogus'))
 
 
 #
@@ -2546,7 +2546,6 @@ def test_main(module=None):
         ElementSlicingTest,
         BasicElementTest,
         ElementTreeTest,
-        IncrementalParserTest,
         IOTest,
         ParseErrorTest,
         XIncludeTest,
@@ -2555,6 +2554,7 @@ def test_main(module=None):
         ElementIterTest,
         TreeBuilderTest,
         XMLParserTest,
+        XMLPullParserTest,
         BugsTest,
         ]
 
diff --git a/Lib/xml/etree/ElementTree.py b/Lib/xml/etree/ElementTree.py
index 3e3b09c..6526b3e 100644
--- a/Lib/xml/etree/ElementTree.py
+++ b/Lib/xml/etree/ElementTree.py
@@ -1210,37 +1210,39 @@ def iterparse(source, events=None, parser=None):
     return _IterParseIterator(source, events, parser, close_source)
 
 
-class IncrementalParser:
+class XMLPullParser:
+
+    def __init__(self, events=None, *, _parser=None):
+        # The _parser argument is for internal use only and must not be relied
+        # upon in user code. It will be removed in a future release.
+        # See http://bugs.python.org/issue17741 for more details.
 
-    def __init__(self, events=None, parser=None):
         # _elementtree.c expects a list, not a deque
         self._events_queue = []
         self._index = 0
         self.root = self._root = None
-        if not parser:
-            parser = XMLParser(target=TreeBuilder())
-        self._parser = parser
+        self._parser = _parser or XMLParser(target=TreeBuilder())
         # wire up the parser for event reporting
         if events is None:
             events = ("end",)
         self._parser._setevents(self._events_queue, events)
 
-    def data_received(self, data):
+    def feed(self, data):
         if self._parser is None:
-            raise ValueError("data_received() called after end of stream")
+            raise ValueError("feed() called after end of stream")
         if data:
             try:
                 self._parser.feed(data)
             except SyntaxError as exc:
                 self._events_queue.append(exc)
 
-    def eof_received(self):
+    def close(self):
         self._root = self._parser.close()
         self._parser = None
         if self._index >= len(self._events_queue):
             self.root = self._root
 
-    def events(self):
+    def read_events(self):
         events = self._events_queue
         while True:
             index = self._index
@@ -1268,14 +1270,16 @@ class IncrementalParser:
 class _IterParseIterator:
 
     def __init__(self, source, events, parser, close_source=False):
-        self._parser = IncrementalParser(events, parser)
+        # Use the internal, undocumented _parser argument for now; When the
+        # parser argument of iterparse is removed, this can be killed.
+        self._parser = XMLPullParser(events=events, _parser=parser)
         self._file = source
         self._close_file = close_source
         self.root = None
 
     def __next__(self):
         while 1:
-            for event in self._parser.events():
+            for event in self._parser.read_events():
                 return event
             if self._parser._parser is None:
                 self.root = self._parser.root
@@ -1283,11 +1287,11 @@ class _IterParseIterator:
                     self._file.close()
                 raise StopIteration
             # load event buffer
-            data = self._file.read(16384)
+            data = self._file.read(16 * 1024)
             if data:
-                self._parser.data_received(data)
+                self._parser.feed(data)
             else:
-                self._parser.eof_received()
+                self._parser.close()
 
     def __iter__(self):
         return self
@@ -1481,9 +1485,9 @@ class XMLParser:
             pass # unknown
 
     def _setevents(self, events_queue, events_to_report):
-        # Internal API for IncrementalParser
+        # Internal API for XMLPullParser
         # events_to_report: a list of events to report during parsing (same as
-        # the *events* of IncrementalParser's constructor.
+        # the *events* of XMLPullParser's constructor.
         # events_queue: a list of actual parsing events that will be populated
         # by the underlying parser.
         #