Better document the terminating behaviour of `PySeqIter_Type` in the `iter()` docs

[jonathandung]

Documentation

It is not exactly clear when the iterator returned by iter(seq) stops, where the type of seq implements __getitem__ . It was only by consulting the ABI docs that I found out it stops when IndexError is raised, and by experimenting in the console that only __length_hint__ on the iterator calls __len__ on seq if present and subtracts it by the number of items yielded. I believe this can be better documented, preferably in the iter() function documentation, which only mentions:

or it must support the sequence protocol (the __getitem__() method
with integer arguments starting at 0)

with no further explanation.

[jonathandung]

The Google Search AI output cites Stack Overflow rather than the Python docs, and Deepseek is unable to find the page I linked even when I specifically asked it to cite the Python docs.

[picnixz]

It's already mentioned in __getitem__:

The sequence iteration protocol (used, for example, in for loops), expects that an IndexError will be raised for illegal indexes to allow proper detection of the end of a sequence.

The docs for __iter__ clearly say:

Without a second argument, the single argument must be a collection object which supports the iterable protocol (the iter() method), or it must support the sequence protocol (the getitem() method with integer arguments starting at 0

So from __iter__ we go to __getitem__ which itself explains the sequence protocol.

[picnixz]

In addition, __length_hint__ is not relevant. Python implementations are not required to use it and it's an implementation detail of when and how it's being used as explained in its doc:

This method is purely an optimization and is never required for correctness