pandas replace() — swap sentinels, labels and currency in one call

$ import pandas as pd

export = pd.DataFrame({
    "order":  ["SO-1001", "SO-1002", "SO-1003", "SO-1004"],
    "city":   ["Vienna", "Berlin", "n/a", "Rome"],
    "units":  ["12", "-", "40", "8"],
    "note":   ["", "late", "NULL", "ok"],
})
clean = export.replace(["n/a", "-", "NULL", ""], pd.NA)
print(clean.to_string(index=False))
print(clean.isna().sum().to_string())

  order   city units note
SO-1001 Vienna    12  NaN
SO-1002 Berlin   NaN late
SO-1003    NaN    40  NaN
SO-1004   Rome     8   ok
order    0
city     1
units    1
note     2

The frame-wide list form: every column is checked for the same four sentinels and each cell that matches becomes a real missing value. Note the detail in the printout — the str column shows NaN, not <NA>, because a pandas 3.0 string column stores its missing value as NaN, while the counts from .isna() are the same. Before this line, .isna().sum() reported 0 for city, units and note; now dropna(), fillna() and groupby(dropna=False) all see the truth.

$ import pandas as pd

tickets = pd.DataFrame({
    "ticket":   [501, 502, 503, 504, 505, 506],
    "priority": ["P0", "HIGH", "high", "Med", "medium", "LOW"],
})
tickets["priority"] = tickets["priority"].replace({
    "P0": "high", "HIGH": "high",
    "Med": "medium",
    "LOW": "low",
})
print(tickets["priority"].value_counts().to_string())

priority
high      3
medium    2
low       1

A dict with no value is a label map: exact matches only, applied to the frame, unknown labels untouched. 'P0' folded into 'high' without a second call, which is what you want when a support tool renamed its priorities three times and the export still carries all three spellings. Because matching is exact, 'HIGH' had to be listed next to 'P0' — one misspelt key and that row silently stays as it was.

$ import pandas as pd

invoices = pd.DataFrame({
    "invoice": ["INV-2201", "INV-2202", "INV-2203"],
    "amount":  ["$1,240.50", "$980.00", "$2,015.75"],
})
invoices["amount"] = invoices["amount"].replace(r"[$,]", "", regex=True).astype("float64")
print(invoices.to_string(index=False))
print("total:", invoices["amount"].sum())

 invoice  amount
INV-2201 1240.50
INV-2202  980.00
INV-2203 2015.75
total: 4236.25

The nested dict is the whole cleaning spec in one argument: region gets its own rules, stage gets different ones, and any other column is left exactly as it was. This is the form to keep in a report script — it reads like a config block and a reviewer can diff it. The traceback at the bottom is the 3.0 behaviour worth knowing: passing a list of values without a value used to silently *fill* instead (see the fun facts); now it is a ValueError that names the three legal shapes.

$ import pandas as pd

leads = pd.DataFrame({
    "region": ["EMEA", "NAM", "EMEA", "APAC"],
    "stage":  ["Q", "Closed Won", "W", "Q"],
})
print(leads.replace({
    "region": {"EMEA": "Europe", "NAM": "North America"},
    "stage":  {"Q": "qualified", "W": "won"},
}).to_string(index=False))
try:
    leads["region"].replace(["EMEA", "NAM"])
except ValueError as err:
    print("ValueError:", err)

       region      stage
       Europe  qualified
North America Closed Won
       Europe        won
         APAC  qualified
ValueError: Series.replace must specify either 'value', a dict-like 'to_replace', or dict-like 'regex'.

regex=True turns to_replace into a pattern and makes matching sub-string, which is what currency and measurement columns need. The character class [$,] is applied inside every cell — each '1,240.50' cell keeps its digits and loses the decoration. The .astype('float64') afterwards is not part of replace(); replace() rewrites text, it does not parse it, and the column is still str until something declares it numeric.

$ import pandas as pd
import numpy as np

readings = pd.DataFrame({
    "sensor": ["T-01", "T-02", "T-03", "T-04"],
    "temp_c": [21.4, -999.0, 22.0, -999.0],
})
fixed = readings.assign(
    temp_nan = readings["temp_c"].replace(-999.0, np.nan),
    temp_na  = readings["temp_c"].replace(-999.0, pd.NA),
)
print(fixed.to_string(index=False))
print(fixed[["temp_nan", "temp_na"]].dtypes.to_string())
print("mean:", round(fixed["temp_nan"].mean(), 2), "| dtype kept:", fixed["temp_nan"].dtype)

sensor  temp_c  temp_nan temp_na
  T-01    21.4      21.4    21.4
  T-02  -999.0       NaN    <NA>
  T-03    22.0      22.0    22.0
  T-04  -999.0       NaN    <NA>
temp_nan    float64
temp_na      object
mean: 21.7 | dtype kept: float64

The numeric twin of example 1, and the dtype lesson: -999.0 into np.nan keeps the column float64 and .mean() then returns 21.7 from the two real readings, while the same replacement with pd.NA — pandas' own missing scalar — leaves the column as object, because object is the only thing that can hold <NA> next to a float. Both are 'correct'; only one keeps your arithmetic and your groupby working. Same trick in a nullable 'Int64' column keeps the dtype, and there pd.NA is the right choice.

$ import pandas as pd

df = pd.DataFrame({"sku": ["abc123", "xyz"], "qty": [1, 2]})
fixed = df.replace(r"\d+", 0, regex=True)
print("result:")
print(fixed.to_string())
print("the frame I called it on:")
print(df.to_string())
print("and its sku column still claims dtype:", df["sku"].dtype)

result:
   sku  qty
0    0    1
1  xyz    2
the frame I called it on:
   sku  qty
0    0    1
1  xyz    2
and its sku column still claims dtype: str

This one is not a lesson about your data, it is a lesson about the method: on pandas 3.0.3, a regex replacement whose value is *not* a string rewrites the frame you called it on. The copy and the original print identically, and the sku column still reports dtype str while holding 0. It only happens on the extension-backed string columns (3.0's str dtype and the nullable 'string' dtype) — a numpy object column is untouched — and it only happens for non-string values, because that is the branch where the block is upcast to object before the regex pass writes into it. Reproduced on 3.0.3, 2026-10-10.