DOC: DataFrame.unstack should accept fill_value with more types than just int/str/dict

[loicdiridollou]

Pandas version checks

• I have checked that the issue still exists on the latest versions of the docs on main here

Location of the documentation

https://pandas.pydata.org/docs/dev/reference/api/pandas.DataFrame.unstack.html#pandas.DataFrame.unstack

Documentation problem

Currently the docs stipulate that only int, str and dict are allowed for the fill_value, yet it seems like all the types that could be used when creating a DataFrame seem to pass at runtime. I have not tried them all yet but int, float, complex, timestamp are working fine.

Suggested fix for documentation

Add all allowed types for dataframe elements for the fill_value field.
Happy to create the PR if this is agreed by the maintainers. I will raise the issue in the pandas-stubs repo.

[loicdiridollou]

Also I realized that the dict option is quite confusing, I am not able to make it work, the following code will fail:

pd.DataFrame([
    ["a", "b", pd.Timestamp(2021, 3, 2)],
    ["a", "a", pd.Timestamp(2023, 4, 2)],
    ["b", "b", pd.Timestamp(2024, 3, 2)]
]).set_index([0, 1]).unstack(1, fill_value={2: pd.Timestamp(2023, 4, 5)})

  File "/Users/loic/Documents/Code/pandas-stubs/gh1214_unstack/.venv/lib/python3.13/site-packages/pandas/core/reshape/reshape.py", line 238, in get_result
    values, _ = self.get_new_values(values, fill_value)
                ~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^
  File "/Users/loic/Documents/Code/pandas-stubs/gh1214_unstack/.venv/lib/python3.13/site-packages/pandas/core/reshape/reshape.py", line 288, in get_new_values
    dtype, fill_value = maybe_promote(dtype, fill_value)
                        ~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^
  File "/Users/loic/Documents/Code/pandas-stubs/gh1214_unstack/.venv/lib/python3.13/site-packages/pandas/core/dtypes/cast.py", line 595, in maybe_promote
    dtype, fill_value = _maybe_promote(dtype, fill_value)
                        ~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^
  File "/Users/loic/Documents/Code/pandas-stubs/gh1214_unstack/.venv/lib/python3.13/site-packages/pandas/core/dtypes/cast.py", line 622, in _maybe_promote
    raise ValueError("fill_value must be a scalar")
ValueError: fill_value must be a scalar

[Dr-Irv]

FWIW, I didn't see any tests for fill_value being a dict, so I think this is erroneous docs.

Seems like the doc change was part of this PR #28655 and it was just erroneous to document the fill_value that way.

[KevsterAmp]

take