[Python-checkins] [Python-Dev] cpython: whatsnew: XMLPullParser, plus some doc updates.

[R. David Murray]

On Tue, 07 Jan 2014 01:22:21 +1000, Nick Coghlan <ncoghlan at gmail.com> wrote:
> On 5 Jan 2014 12:54, "r.david.murray" <python-checkins at python.org> wrote:
> >
> > http://hg.python.org/cpython/rev/069f88f4935f
> > changeset:   88308:069f88f4935f
> > user:        R David Murray <rdmurray at bitdance.com>
> > date:        Sat Jan 04 23:52:50 2014 -0500
> > summary:
> >   whatsnew: XMLPullParser, plus some doc updates.
> >
> > I was confused by the text saying that read_events "iterated", since it
> > actually returns an iterator (that's what a generator does) that the
> > caller must then iterate.  So I tidied up the language.  I'm not sure
> > what the sentence "Events provided in a previous call to read_events()
> > will not be yielded again." is trying to convey, so I didn't try to fix
> that.
> 
> It's a mutating API - once the events have been retrieved, that's it,
> they're gone from the internal state. Suggestions for wording improvements
> welcome :)

Well, my guess as to what it meant was roughly:

"An Event will be yielded exactly once regardless of how many read_events
iterators are processed."

Looking at the code, though, I'm not sure that's actually true.  The
code does not appear to be thread-safe.  Of course, it isn't intended to
be used in a threaded context, but the docs don't quite make that
explicit.  I imagine that's the intent of the statement about "parallel"
reading, but it doesn't actually say that the code is not thread safe.
It reads more as if it is warning that the order of retrieval would be
unpredictable.

--David