Return type for DataFrame/Series iteration methods should be Iterator, not Iterable

[tilsche]

Describe the bug

Several iteration methods in pandas(-stubs) specify their return type as Iterable while they are implemented as generators or return zip objects which qualify them as Iterator. This flags straight-forward use with next, which should be perfectly valid. Most of them are documented to return an Iterator as per the docstring and it seems reasonable to assume that they actually return iterators.

1. DataFrame.itertuples - Documented to "Iterate over" and return an "iterator", returns a zip object
2. DataFrame.iterrows - Documented to "Iterate over", Generator function
3. DataFrame.items - Documented to "Iterate over", Generator function
4. Series.items - Documented to "Lazily iterate over", Generator function

To Reproduce

import pandas as pd

def foo(df: pd.DataFrame):
    next(df.items())

(mypy)

test.py:4: error: No overload variant of "next" matches argument type "Iterable[tuple[Hashable, Series[Any]]]"  [call-overload]
test.py:4: note: Possible overload variants:
test.py:4: note:     def [_T] next(SupportsNext[_T], /) -> _T
test.py:4: note:     def [_T, _VT] next(SupportsNext[_T], _VT, /) -> _T | _VT
Found 1 error in 1 file (checked 1 source file)

Please complete the following information:

• OS: Linux
• python 3.12.3
• mypy 1.15.0
• pandas-stubs 2.2.3.250308

Additional context

• This also affects the type within the main pandas code, should I make another issue there?
• Related documentation issue: DOC: Standardize use of "Iterate" and "Iterator" in the documentation for DataFrame and Series iterators pandas#27861

[Dr-Irv]

Thanks for the report. PR with tests welcome.

Creating an issue in the pandas repo would also be a good idea. You can cross-reference to this one.