ENH: Broaden dict to Mapping as replace argument

[DavideCanton]

Feature Type

• Adding new functionality to pandas

• Changing existing functionality in pandas

• Removing existing functionality in pandas

Problem Description

Currently the replace method of Series allows only dict, but not Mapping inputs, as the DataFrame one does.

For example:

from collections.abc import Mapping
import pandas as pd


df = pd.DataFrame({"A": [1, 2, 3], "B": [4, 5, 6]})

d: Mapping[int, str] = {1: "a", 2: "b", 3: "c"}

d2: Mapping[str, Mapping[int, str]] = {"A": d}
print(df.replace(d2))  # typechecks

print(df["A"].replace(d))  # works but doesn't typecheck

Feature Description

I guess it's enough to change from dict to Mapping in the type signature, since it seems to work even if the argument is not a dict (for example if it's a MappingProxyType instance).

Alternative Solutions

I guess an alternative solution is just to type ignore the replace invocation.

Additional Context

No response

[loicdiridollou]

Hey @DavideCanton,

Have you installed the pandas-stubs package? It is an extension of the pandas repo for types.
I have tried locally in an environment where pandas-stubs is installed and no warning are raised (pyright/mypy).
Can you provide how you typecheck this code?

See below, the type is Mapping as you are suggesting:
https://github.com/pandas-dev/pandas-stubs/blob/93a9e11f4e4656a935853d3814ac9073adf4c9cc/pandas-stubs/core/frame.pyi#L863-L880

[DavideCanton]

This is what I do

$ uv pip install pandas pandas-stubs mypy
Resolved 11 packages in 17ms
Installed 11 packages in 4.57s
 + mypy==1.15.0
 + mypy-extensions==1.1.0
 + numpy==2.2.6
 + pandas==2.2.3
 + pandas-stubs==2.2.3.250308
 + python-dateutil==2.9.0.post0
 + pytz==2025.2
 + six==1.17.0
 + types-pytz==2025.2.0.20250516
 + typing-extensions==4.13.2
 + tzdata==2025.2
$ mypy .
foo.py:10: error: Argument 1 to "replace" of "DataFrame" has incompatible type "Mapping[str, Mapping[int, str]]"; expected "str | bytes | date | datetime | timedelta | <14 more items> | None"  [arg-type]
Found 2 errors in 2 files (checked 2 source files)

[loicdiridollou]

I see why you are seeing the issue and I don't, can you try running with pandas-stubs on main:
uv pip install "git+https://github.com/pandas-dev/pandas-stubs.git"
With your setup I saw the error, with the stubs repo on main I don't meaning that it was fixed in: pandas-dev/pandas-stubs#1164
Please let me know if when pulling from main you still see the issue, we should be able to ask for a new release of the stubs.

[DavideCanton]

Seems fixed if using the main version, so probably as you said it's just a stubs problem.

Thanks!