CLN: enforce deprecation of the method keyword on df.fillna (#57760)

* enforce deprecation of param method in df.fillna: correct def fillna, fix tests

* correct def fillna, fix tests

* correct an example in v0.10.0, fix test

* add a note to v3.0.0

* remove an entry from ignored_doctest_warnings

* fix pylint error in test_sparse.py

* correct fillna docstring

* correct fillna docstring II

* correct tests

Author: natmokval

Diff for: doc/source/whatsnew/v0.10.0.rst

@@ -242,18 +242,42 @@ labeled the aggregated group with the end of the interval: the next day).
 - Calling ``fillna`` on Series or DataFrame with no arguments is no longer
   valid code. You must either specify a fill value or an interpolation method:
 
-.. ipython:: python
-   :okwarning:
+.. code-block:: ipython
 
-   s = pd.Series([np.nan, 1.0, 2.0, np.nan, 4])
-   s
-   s.fillna(0)
-   s.fillna(method="pad")
+    In [6]: s = pd.Series([np.nan, 1.0, 2.0, np.nan, 4])
+
+    In [7]: s
+    Out[7]:
+    0      NaN
+    1      1.0
+    2      2.0
+    3      NaN
+    4      4.0
+    dtype: float64
+
+    In [8]: s.fillna(0)
+    Out[8]:
+    0      0.0
+    1      1.0
+    2      2.0
+    3      0.0
+    4      4.0
+    dtype: float64
+
+    In [9]: s.fillna(method="pad")
+    Out[9]:
+    0      NaN
+    1      1.0
+    2      2.0
+    3      2.0
+    4      4.0
+    dtype: float64
 
 Convenience methods ``ffill`` and  ``bfill`` have been added:
 
 .. ipython:: python
 
+   s = pd.Series([np.nan, 1.0, 2.0, np.nan, 4])
    s.ffill()
 
 

Diff for: doc/source/whatsnew/v3.0.0.rst

@@ -241,6 +241,7 @@ Removal of prior version deprecations/changes
 - Removed argument ``limit`` from :meth:`DataFrame.pct_change`, :meth:`Series.pct_change`, :meth:`.DataFrameGroupBy.pct_change`, and :meth:`.SeriesGroupBy.pct_change`; the argument ``method`` must be set to ``None`` and will be removed in a future version of pandas (:issue:`53520`)
 - Removed deprecated argument ``obj`` in :meth:`.DataFrameGroupBy.get_group` and :meth:`.SeriesGroupBy.get_group` (:issue:`53545`)
 - Removed deprecated behavior of :meth:`Series.agg` using :meth:`Series.apply` (:issue:`53325`)
+- Removed deprecated keyword ``method`` on :meth:`Series.fillna`, :meth:`DataFrame.fillna` (:issue:`57760`)
 - Removed option ``mode.use_inf_as_na``, convert inf entries to ``NaN`` before instead (:issue:`51684`)
 - Removed support for :class:`DataFrame` in :meth:`DataFrame.from_records`(:issue:`51697`)
 - Removed support for ``errors="ignore"`` in :func:`to_datetime`, :func:`to_timedelta` and :func:`to_numeric` (:issue:`55734`)

Diff for: pandas/conftest.py

@@ -173,10 +173,6 @@ def pytest_collection_modifyitems(items, config) -> None:
             "DataFrameGroupBy.fillna",
             "DataFrameGroupBy.fillna with 'method' is deprecated",
         ),
-        (
-            "DataFrameGroupBy.fillna",
-            "DataFrame.fillna with 'method' is deprecated",
-        ),
         ("read_parquet", "Passing a BlockManager to DataFrame is deprecated"),
     ]
 

Diff for: pandas/core/generic.py

@@ -6758,7 +6758,6 @@ def fillna(
         self,
         value: Hashable | Mapping | Series | DataFrame = ...,
         *,
-        method: FillnaOptions | None = ...,
         axis: Axis | None = ...,
         inplace: Literal[False] = ...,
         limit: int | None = ...,
@@ -6769,7 +6768,6 @@ def fillna(
         self,
         value: Hashable | Mapping | Series | DataFrame = ...,
         *,
-        method: FillnaOptions | None = ...,
         axis: Axis | None = ...,
         inplace: Literal[True],
         limit: int | None = ...,
@@ -6780,7 +6778,6 @@ def fillna(
         self,
         value: Hashable | Mapping | Series | DataFrame = ...,
         *,
-        method: FillnaOptions | None = ...,
         axis: Axis | None = ...,
         inplace: bool = ...,
         limit: int | None = ...,
@@ -6795,13 +6792,12 @@ def fillna(
         self,
         value: Hashable | Mapping | Series | DataFrame | None = None,
         *,
-        method: FillnaOptions | None = None,
         axis: Axis | None = None,
         inplace: bool = False,
         limit: int | None = None,
     ) -> Self | None:
         """
-        Fill NA/NaN values using the specified method.
+        Fill NA/NaN values with `value`.
 
         Parameters
         ----------
@@ -6811,15 +6807,6 @@ def fillna(
             each index (for a Series) or column (for a DataFrame).  Values not
             in the dict/Series/DataFrame will not be filled. This value cannot
             be a list.
-        method : {{'backfill', 'bfill', 'ffill', None}}, default None
-            Method to use for filling holes in reindexed Series:
-
-            * ffill: propagate last valid observation forward to next valid.
-            * backfill / bfill: use next valid observation to fill gap.
-
-            .. deprecated:: 2.1.0
-                Use ffill or bfill instead.
-
         axis : {axes_single_arg}
             Axis along which to fill missing values. For `Series`
             this parameter is unused and defaults to 0.
@@ -6828,12 +6815,8 @@ def fillna(
             other views on this object (e.g., a no-copy slice for a column in a
             DataFrame).
         limit : int, default None
-            If method is specified, this is the maximum number of consecutive
-            NaN values to forward/backward fill. In other words, if there is
-            a gap with more than this number of consecutive NaNs, it will only
-            be partially filled. If method is not specified, this is the
-            maximum number of entries along the entire axis where NaNs will be
-            filled. Must be greater than 0 if not None.
+            This is the maximum number of entries along the entire axis
+            where NaNs will be filled. Must be greater than 0 if not None.
 
         Returns
         -------
@@ -6918,14 +6901,10 @@ def fillna(
                         stacklevel=2,
                     )
 
-        value, method = validate_fillna_kwargs(value, method)
-        if method is not None:
-            warnings.warn(
-                f"{type(self).__name__}.fillna with 'method' is deprecated and "
-                "will raise in a future version. Use obj.ffill() or obj.bfill() "
-                "instead.",
-                FutureWarning,
-                stacklevel=find_stack_level(),
+        if isinstance(value, (list, tuple)):
+            raise TypeError(
+                '"value" parameter must be a scalar or dict, but '
+                f'you passed a "{type(value).__name__}"'
             )
 
         # set the default here, so functions examining the signaure
@@ -6935,15 +6914,7 @@ def fillna(
         axis = self._get_axis_number(axis)
 
         if value is None:
-            return self._pad_or_backfill(
-                # error: Argument 1 to "_pad_or_backfill" of "NDFrame" has
-                # incompatible type "Optional[Literal['backfill', 'bfill', 'ffill',
-                # 'pad']]"; expected "Literal['ffill', 'bfill', 'pad', 'backfill']"
-                method,  # type: ignore[arg-type]
-                axis=axis,
-                limit=limit,
-                inplace=inplace,
-            )
+            raise ValueError("Must specify a fill 'value'.")
         else:
             if self.ndim == 1:
                 if isinstance(value, (dict, ABCSeries)):

Diff for: pandas/tests/extension/base/missing.py

@@ -68,9 +68,6 @@ def test_fillna_scalar(self, data_missing):
         expected = data_missing.fillna(valid)
         tm.assert_extension_array_equal(result, expected)
 
-    @pytest.mark.filterwarnings(
-        "ignore:Series.fillna with 'method' is deprecated:FutureWarning"
-    )
     def test_fillna_limit_pad(self, data_missing):
         arr = data_missing.take([1, 0, 0, 0, 1])
         result = pd.Series(arr).ffill(limit=2)
@@ -99,12 +96,9 @@ def test_ffill_limit_area(
         expected = pd.Series(data_missing.take(expected_ilocs))
         tm.assert_series_equal(result, expected)
 
-    @pytest.mark.filterwarnings(
-        "ignore:Series.fillna with 'method' is deprecated:FutureWarning"
-    )
     def test_fillna_limit_backfill(self, data_missing):
         arr = data_missing.take([1, 0, 0, 0, 1])
-        result = pd.Series(arr).fillna(method="backfill", limit=2)
+        result = pd.Series(arr).bfill(limit=2)
         expected = pd.Series(data_missing.take([1, 0, 1, 1, 1]))
         tm.assert_series_equal(result, expected)
 

Diff for: pandas/tests/extension/decimal/test_decimal.py

@@ -187,15 +187,6 @@ def test_ffill_limit_area(
                 )
 
     def test_fillna_limit_backfill(self, data_missing):
-        msg = "Series.fillna with 'method' is deprecated"
-        with tm.assert_produces_warning(
-            FutureWarning,
-            match=msg,
-            check_stacklevel=False,
-            raise_on_extra_warnings=False,
-        ):
-            super().test_fillna_limit_backfill(data_missing)
-
         msg = "ExtensionArray.fillna 'method' keyword is deprecated"
         with tm.assert_produces_warning(
             DeprecationWarning,

Diff for: pandas/tests/extension/test_sparse.py

@@ -234,11 +234,6 @@ def test_isna(self, data_missing):
         expected = SparseArray([False, False], fill_value=False, dtype=expected_dtype)
         tm.assert_equal(sarr.isna(), expected)
 
-    def test_fillna_limit_backfill(self, data_missing):
-        warns = FutureWarning
-        with tm.assert_produces_warning(warns, check_stacklevel=False):
-            super().test_fillna_limit_backfill(data_missing)
-
     def test_fillna_no_op_returns_copy(self, data, request):
         super().test_fillna_no_op_returns_copy(data)