Return types of XMLPullParser.read_events and iterparse from xml.etree.ElementTree

[Prometheus3375]

typeshed assigns return type for iterparse as Iterator[tuple[str, Any]] and for XMLPullParser.read_events as Iterator[tuple[str, Element]].

Internally, iterparse uses XMLPullParser and then yields from XMLPullParser.read_events. But iterparse returns a special iterator object which has a nullable root attribute.

XMLPullParser.read_events itself returns tuples with different 2nd object depending on the event. From docs:

start, end: the current Element.
comment, pi: the current comment / processing instruction
start-ns: a tuple (prefix, uri) naming the declared namespace mapping.
end-ns: None (this may change in a future version)

At now, the presence of root attribute of iterparse result is not documented (issue), so I suggest to ignore it and simply use Iterator[T] as return type for both XMLPullParser.read_events and iterparse.

I propose several variants for T:

tuple[str, Any]

tuple[str, Element | tuple[str, str] | None]

tuple[Literal['start', 'end', 'comment', 'pi'], Element] | \
    tuple[Literal['start-ns'], tuple[str, str]] | \
    tuple[Literal['end-ns'], None]

I am not sure which one is better for type checkers.

[AlexWaygood]

In general, we prefer to avoid union return types in typeshed: see python/mypy#1693 for some detailed discussion. They end up being annoying for end users due to the number of checks they have to perform on the returned object in order to precisely narrow the type. So -- while I'm far from an expert on the xml modules -- I would guess that Iterator[tuple[str, Any]] would probably be the return type least likely to cause false-positive errors.

[Prometheus3375]

Great, it that case only return type of XMLPullParser.read_events must be changed. Should I create a PR or is it better to wait some others for discussion?

[AlexWaygood]

Feel free to create a PR! :)