root attribute of xml.etree.ElementTree.iterparse is not documented

[Prometheus3375]

Documentation

iterparse implementation from Python 3.10.5:

def iterparse(source, events=None, parser=None):
    """Incrementally parse XML document into ElementTree.

    This class also reports what's going on to the user based on the
    *events* it is initialized with.  The supported events are the strings
    "start", "end", "start-ns" and "end-ns" (the "ns" events are used to get
    detailed namespace information).  If *events* is omitted, only
    "end" events are reported.

    *source* is a filename or file object containing XML data, *events* is
    a list of events to report back, *parser* is an optional parser instance.

    Returns an iterator providing (event, elem) pairs.

    """
    # Use the internal, undocumented _parser argument for now; When the
    # parser argument of iterparse is removed, this can be killed.
    pullparser = XMLPullParser(events=events, _parser=parser)

    def iterator(source):
        close_source = False
        try:
            if not hasattr(source, "read"):
                source = open(source, "rb")
                close_source = True
            yield None
            while True:
                yield from pullparser.read_events()
                # load event buffer
                data = source.read(16 * 1024)
                if not data:
                    break
                pullparser.feed(data)
            root = pullparser._close_and_return_root()
            yield from pullparser.read_events()
            it.root = root
        finally:
            if close_source:
                source.close()

    class IterParseIterator(collections.abc.Iterator):
        __next__ = iterator(source).__next__
    it = IterParseIterator()
    it.root = None
    del iterator, IterParseIterator

    next(it)
    return it

The resulting iterator has root attribute. It is None all the time, but if the source is fully read, the root element is assigned to root. Documentation does not describe this behavior.

• PR: gh-93607: document root attribute of iterparse #99410

• PR: [3.12] gh-93607: document root attribute of iterparse (GH-99410) #111555

• PR: [3.11] gh-93607: document root attribute of iterparse (GH-99410) #111556

[AA-Turner]

PR welcome!

A

[hugovk]

Thanks!