BUG: fillna() doesn't work with `value=None` without method specified, but method is deprecated

[Dr-Irv]

Pandas version checks

• I have checked that this issue has not already been reported.

• I have confirmed this bug exists on the latest version of pandas.

• I have confirmed this bug exists on the main branch of pandas.

Reproducible Example

>>> s = pd.Series([1,None,3])
>>> s
0    1.0
1    NaN
2    3.0
dtype: float64
>>> s.fillna()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "C:\Code\pandas_dev\pandas\pandas\core\generic.py", line 6887, in fillna
    value, method = validate_fillna_kwargs(value, method)
  File "C:\Code\pandas_dev\pandas\pandas\util\_validators.py", line 293, in validate_fillna_kwargs
    raise ValueError("Must specify a fill 'value' or 'method'.")
ValueError: Must specify a fill 'value' or 'method'.
>>> s.fillna(value=None, method="ffill")
<stdin>:1: FutureWarning: Series.fillna with 'method' is deprecated and will raise in a future version. Use obj.ffill() or obj.bfill() instead.
0    1.0
1    1.0
2    3.0
dtype: float64

Issue Description

The method parameter is deprecated in version 2.1. But the docs for Series.fillna() indicate that a value of None is valid. So you can't do a fillna() with a value of None

Expected Behavior

Unclear. Do we want to allow None as the possible value in fillna()? This could be a docs issue or a code issue.

Installed Versions

INSTALLED VERSIONS

commit : fd3f571
python : 3.10.13.final.0
python-bits : 64
OS : Linux
OS-release : 4.4.0-19041-Microsoft
Version : #3996-Microsoft Thu Jan 18 16:36:00 PST 2024
machine : x86_64
processor : x86_64
byteorder : little
LC_ALL : None
LANG : C.UTF-8
LOCALE : en_US.UTF-8

pandas : 2.2.0
numpy : 1.26.4
pytz : 2024.1
dateutil : 2.8.2
setuptools : 69.1.0
pip : 23.2.1
Cython : None
pytest : 8.0.1
hypothesis : None
sphinx : None
blosc : None
feather : None
xlsxwriter : None
lxml.etree : None
html5lib : None
pymysql : None
psycopg2 : None
jinja2 : None
IPython : None
pandas_datareader : None
adbc-driver-postgresql: None
adbc-driver-sqlite : None
bs4 : None
bottleneck : None
dataframe-api-compat : None
fastparquet : None
fsspec : None
gcsfs : None
matplotlib : None
numba : None
numexpr : None
odfpy : None
openpyxl : None
pandas_gbq : None
pyarrow : None
pyreadstat : None
python-calamine : None
pyxlsb : None
s3fs : None
scipy : None
sqlalchemy : None
tables : None
tabulate : None
xarray : None
xlrd : None
zstandard : None
tzdata : 2024.1
qtpy : None
pyqt5 : None

[rhshadrach]

I believe this issue existed prior to the deprecation: it was never possible to just .fillna(value=None). And doing .fillna(value=None, method="ffill") would ignore the value parameter (since forward filling does not utilize a value). When the deprecation is enforced, we can make the value parameter required (instead of having a default), and then enable users to use .fillna(value=None).

[rhshadrach]

Ref: #47639

[Dr-Irv]

I believe this issue existed prior to the deprecation: it was never possible to just .fillna(value=None). And doing .fillna(value=None, method="ffill") would ignore the value parameter (since forward filling does not utilize a value). When the deprecation is enforced, we can make the value parameter required (instead of having a default), and then enable users to use .fillna(value=None).

So should we update the docs now to reflect that Series.fillna(value=None) doesn't work? Because the way it reads now, it appears that it should work. I think that is what led to the confusion of the OP in pandas-dev/pandas-stubs#884

[rhshadrach]

So should we update the docs now to reflect that Series.fillna(value=None) doesn't work?

I would vote no, but not opposed if someone wants to do that. This deficiency in the docs has existed for a long time, and I expect it to work come 3.0, so it doesn't seem worth the effort to change now.

[phofl]

agree with @rhshadrach

[rhshadrach]

I have a PR in the works for enforcing said deprecation, I'll add a test for this and use that PR to close this issue.