`DataFrame.__setitem__` fails type check when using column names from DataFrame iteration

[kgutwin]

Describe the bug
The return type of DataFrame.__iter__ seems to be typing.Hashable which is not recognized as a valid type for DataFrame.__setitem__, even though it works as a valid type for DataFrame.__getitem__.

To Reproduce

The example Python code:

from typing import reveal_type

import pandas as pd

df = pd.read_csv('test.csv')

for col_name in df:
    reveal_type(col_name)
    if col_name == 'foo':
        df[col_name] = df[col_name].map({'a': 'alpha', 'b': 'beta'})

print(df)

When run against mypy gives the output:

test.py:8: note: Revealed type is "typing.Hashable"
test.py:10: error: No overload variant of "__setitem__" of "DataFrame" matches argument types "Hashable", "Series[str]"  [call-overload]
test.py:10: note: Possible overload variants:
test.py:10: note:     def __setitem__(self, int | slice[Any, Any, Any] | ndarray[tuple[Any, ...], dtype[integer[Any]]] | Index[Any] | list[int] | Series[int] | tuple[int, int] | tuple[slice[Any, Any, Any] | ndarray[tuple[Any, ...], dtype[integer[Any]]] | Index[Any] | list[int] | Series[int], int] | tuple[slice[Any, Any, Any] | ndarray[tuple[Any, ...], dtype[integer[Any]]] | Index[Any] | list[int] | Series[int], slice[Any, Any, Any] | ndarray[tuple[Any, ...], dtype[integer[Any]]] | Index[Any] | list[int] | Series[int]] | tuple[int, slice[Any, Any, Any] | ndarray[tuple[Any, ...], dtype[integer[Any]]] | Index[Any] | list[int] | Series[int]], str | bytes | date | datetime | timedelta | <7 more items> | complex | integer[Any] | floating[Any] | complexfloating[Any, Any] | IndexOpsMixin[Any, Any] | Sequence[str | bytes | date | datetime | timedelta | <7 more items> | complex | integer[Any] | floating[Any] | complexfloating[Any, Any]] | DataFrame | ndarray[tuple[Any, ...], dtype[Any]] | NAType | NaTType | Mapping[Hashable, str | bytes | date | datetime | timedelta | <7 more items> | complex | integer[Any] | floating[Any] | complexfloating[Any, Any] | NAType | NaTType] | None, /) -> None
test.py:10: note:     def [ScalarT: str | bytes | date | datetime | timedelta | <7 more items> | complex | integer[Any] | floating[Any] | complexfloating[Any, Any]] __setitem__(self, Series[builtins.bool] | ndarray[tuple[Any, ...], dtype[numpy.bool[builtins.bool]]] | list[builtins.bool] | str | str_ | <9 more items>, str | bytes | date | datetime | timedelta | <20 more items> | None, /) -> None
test.py:10: note:     def __setitem__(self, tuple[tuple[IndexOpsMixin[Any, Any] | Series[builtins.bool] | ndarray[tuple[Any, ...], dtype[numpy.bool[builtins.bool]]] | list[builtins.bool] | str | bytes | date | datetime | timedelta | <7 more items> | complex | integer[Any] | floating[Any] | complexfloating[Any, Any] | Sequence[str | bytes | date | datetime | timedelta | <7 more items> | complex | integer[Any] | floating[Any] | complexfloating[Any, Any]] | slice[Any, Any, Any], ...], Hashable], str | bytes | date | datetime | timedelta | <7 more items> | complex | integer[Any] | floating[Any] | complexfloating[Any, Any] | NAType | NaTType | ExtensionArray | ndarray[tuple[Any, ...], dtype[Any]] | IndexOpsMixin[Any, Any] | Sequence[str | bytes | date | datetime | timedelta | <7 more items> | complex | integer[Any] | floating[Any] | complexfloating[Any, Any]] | Sequence[Sequence[str | bytes | date | datetime | timedelta | <7 more items> | complex | integer[Any] | floating[Any] | complexfloating[Any, Any]]] | Mapping[Hashable, str | bytes | date | datetime | timedelta | <7 more items> | complex | integer[Any] | floating[Any] | complexfloating[Any, Any] | NAType | NaTType] | None, /) -> None
test.py:10: note:     def __setitem__(self, IndexOpsMixin[Any, Any] | DataFrame, str | bytes | date | datetime | timedelta | <7 more items> | complex | integer[Any] | floating[Any] | complexfloating[Any, Any] | NAType | NaTType | ExtensionArray | ndarray[tuple[Any, ...], dtype[Any]] | IndexOpsMixin[Any, Any] | Sequence[str | bytes | date | datetime | timedelta | <7 more items> | complex | integer[Any] | floating[Any] | complexfloating[Any, Any]] | Sequence[Sequence[str | bytes | date | datetime | timedelta | <7 more items> | complex | integer[Any] | floating[Any] | complexfloating[Any, Any]]] | Mapping[Hashable, str | bytes | date | datetime | timedelta | <7 more items> | complex | integer[Any] | floating[Any] | complexfloating[Any, Any] | NAType | NaTType] | None, /) -> None
Found 1 error in 1 file (checked 1 source file)

The code itself runs fine on pandas 2.3.3.

Please complete the following information:

• OS: macOS
• OS Version: Tahoe 26.1
• python version: 3.13.3
• version of type checker: mypy 1.19.0 (compiled: yes)
• version of installed pandas-stubs: pandas-stubs==2.3.3.251201

Additional context
The reproduction works fine on pandas-stubs==2.3.2.250926.

[cmp0xff]

I can confirm the issue persists in main 6b7bfc9.

@MarcoGorelli do you think you can take a look? I can provide the following more comprehensive example which works at runtime.

We do not need to get everything recognised, but it would be good to improve.

from collections import UserList
from typing import reveal_type
import pandas as pd

from collections.abc import Hashable

df = pd.DataFrame()


def foo(a: Hashable) -> None:
    df[a] = [1, 2, 3]  # fails mypy and pyright
    # df[{a}] = [[1], [2], [3]]  # fails at runtime
    df[iter([a])] = [[1], [2], [3]]  # fails mypy and pyright
    df.loc[:, a] = [1, 2, 3]  # fails mypy and pyright
    df.loc[:, UserList([a])] = [[1], [2], [3]]  # fails mypy and pyright
    # df.loc[:, {a}] = [[1], [2], [3]]  # fails at runtime
    df.loc[:, iter([a])] = [[1], [2], [3]]  # fails mypy and pyright
    _1 = df[a]  # passes mypy and pyright
    _2 = df[UserList([a])]  # passes mypy and pyright
    _3 = df.loc[:, a]  # fails mypy and pyright
    _4 = df.loc[:, UserList([a])]  # passes mypy and pyright
    # _5 = df.loc[:, {a}]  # passes mypy and pyright, fails at runtime
    _6 = df.loc[:, iter([a])]  # passes mypy and pyright


foo("a")