Kaydet (Commit) 2c68e300 authored tarafından Eli Bendersky's avatar Eli Bendersky

Fix XMLPullParser documentation to say "non-blocking" instead of "asynchronous".

The latter is more ambiguous.

Related to issue #17741
üst 4879a963
...@@ -105,7 +105,7 @@ Children are nested, and we can access specific child nodes by index:: ...@@ -105,7 +105,7 @@ Children are nested, and we can access specific child nodes by index::
>>> root[0][1].text >>> root[0][1].text
'2008' '2008'
Pull API for asynchronous parsing Pull API for non-blocking parsing
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Most parsing functions provided by this module require to read the whole Most parsing functions provided by this module require to read the whole
...@@ -121,18 +121,18 @@ require a blocking read to obtain the XML data, and is instead fed with data ...@@ -121,18 +121,18 @@ require a blocking read to obtain the XML data, and is instead fed with data
incrementally with :meth:`XMLPullParser.feed` calls. To get the parsed XML incrementally with :meth:`XMLPullParser.feed` calls. To get the parsed XML
elements, call :meth:`XMLPullParser.read_events`. Here's an example:: elements, call :meth:`XMLPullParser.read_events`. Here's an example::
>>> asyncparser = ET.XMLPullParser(['start', 'end']) >>> parser = ET.XMLPullParser(['start', 'end'])
>>> asyncparser.feed('<mytag>sometext') >>> parser.feed('<mytag>sometext')
>>> list(asyncparser.read_events()) >>> list(parser.read_events())
[('start', <Element 'mytag' at 0x7fa66db2be58>)] [('start', <Element 'mytag' at 0x7fa66db2be58>)]
>>> asyncparser.feed(' more text</mytag>') >>> parser.feed(' more text</mytag>')
>>> for event, elem in asyncparser.read_events(): >>> for event, elem in parser.read_events():
... print(event) ... print(event)
... print(elem.tag, 'text=', elem.text) ... print(elem.tag, 'text=', elem.text)
... ...
end end
The obvious use case is applications that operate in an asynchronous fashion The obvious use case is applications that operate in a non-blocking fashion
where the XML data is being received from a socket or read incrementally from where the XML data is being received from a socket or read incrementally from
some storage device. In such cases, blocking reads are unacceptable. some storage device. In such cases, blocking reads are unacceptable.
...@@ -427,8 +427,8 @@ Functions ...@@ -427,8 +427,8 @@ Functions
Note that while :func:`iterparse` builds the tree incrementally, it issues 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 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 for applications where blocking reads can't be made. For fully non-blocking
asynchronous parsing, see :class:`XMLPullParser`. parsing, see :class:`XMLPullParser`.
.. note:: .. note::
...@@ -1016,14 +1016,14 @@ XMLPullParser Objects ...@@ -1016,14 +1016,14 @@ XMLPullParser Objects
.. class:: XMLPullParser(events=None) .. class:: XMLPullParser(events=None)
A pull parser suitable for nonblocking (asynchronous) applications. Its A pull parser suitable for non-blocking applications. Its input-side API is
input-side API is similar to that of :class:`XMLParser`, but instead of similar to that of :class:`XMLParser`, but instead of pushing calls to a
pushing calls to a callback target, :class:`XMLPullParser` collects an callback target, :class:`XMLPullParser` collects an internal list of parsing
internal list of parsing events and lets the user read from it. *events* is a events and lets the user read from it. *events* is a sequence of events to
sequence of events to report back. The supported events are the strings report back. The supported events are the strings ``"start"``, ``"end"``,
``"start"``, ``"end"``, ``"start-ns"`` and ``"end-ns"`` (the "ns" events are ``"start-ns"`` and ``"end-ns"`` (the "ns" events are used to get detailed
used to get detailed namespace information). If *events* is omitted, only namespace information). If *events* is omitted, only ``"end"`` events are
``"end"`` events are reported. reported.
.. method:: feed(data) .. method:: feed(data)
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment