> > As for faking the new API, I don't know if that's a good idea because
> we're not yet sure what that new API is.
>
> If that's your concern, then I suggest not adding the feature at all, as
> long as we don't know if we can (or should) keep up the IncrementalParser
> facade with the revised implementation.
>
> For example, can it accept a user defined parser instance as input or not?
> Can it accept a user defined parser target as input? Can it wrap it or
> would it maybe have to inherit from a TreeBuilder? Should it be a class or
> a helper function? I don't see how the interface you proposed leaves less
> questions open than what I am proposing.
>

This is an existing API within ET:

  xml.etree.ElementTree.iterparse(source, events=None, parser=None)

The parser argument is limited: it can't use a custom TreeBuilder. It also
must provide _setevents, so either inherit from XMLParser or just provide
that method in another way [I'll try to improve the documentation to make
all of this explicit]. Whatever we say in this issue, iterparse is here to
stay.

  class xml.etree.ElementTree.IncrementalParser(events=None, parser=None)

Is the new class. Its interface combines iterparse and XMLParser - so it is
subject to the same constraints. It also serves as a basis of iterparse's
implementation.

If the internals are changed, the constrains we'll be subject to with
iterparse will be the same for IncrementalParse; no more. For example, the
solution can be substituting the target of the given parser to the "event
builder" target. Since we force the target to be TreeBuilder now, it should
not really break user code because that part isn't custom. But whatever the
solution is, it will be the same solution for both IncrementalParser and
iterparse.

Also, even if the new approach is implemented in the next release,
IncrementalParser can stay as a simple synonym to
XMLParser(target=EventBuilder(...)).