Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
tilsche opened this issue May 16, 2025 · 1 comment · May be fixed by #1225
Open

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

tilsche opened this issue May 16, 2025 · 1 comment · May be fixed by #1225

Comments

@tilsche
Copy link

tilsche commented May 16, 2025

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

@Dr-Irv
Copy link
Collaborator

Dr-Irv commented May 16, 2025

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants