DEPR: downcast keyword in Index.fillna (pandas-dev#53956)

* DEPR: downcast keyword in Index.fillna

* GH ref

* docstring fixup

Author: jbrockmendel

doc/source/whatsnew/v2.1.0.rst

@@ -249,6 +249,7 @@ Other API changes
 Deprecations
 ~~~~~~~~~~~~
 - Deprecated 'broadcast_axis' keyword in :meth:`Series.align` and :meth:`DataFrame.align`, upcast before calling ``align`` with ``left = DataFrame({col: left for col in right.columns}, index=right.index)`` (:issue:`51856`)
+- Deprecated 'downcast' keyword in :meth:`Index.fillna` (:issue:`53956`)
 - Deprecated 'fill_method' and 'limit' keywords in :meth:`DataFrame.pct_change`, :meth:`Series.pct_change`, :meth:`DataFrameGroupBy.pct_change`, and :meth:`SeriesGroupBy.pct_change`, explicitly call ``ffill`` or ``bfill`` before calling ``pct_change`` instead (:issue:`53491`)
 - Deprecated 'method', 'limit', and 'fill_axis' keywords in :meth:`DataFrame.align` and :meth:`Series.align`, explicitly call ``fillna`` on the alignment results instead (:issue:`51856`)
 - Deprecated 'quantile' keyword in :meth:`Rolling.quantile` and :meth:`Expanding.quantile`, renamed as 'q' instead (:issue:`52550`)

pandas/core/indexes/base.py

@@ -2927,7 +2927,7 @@ def notna(self) -> npt.NDArray[np.bool_]:
 
     notnull = notna
 
-    def fillna(self, value=None, downcast=None):
+    def fillna(self, value=None, downcast=lib.no_default):
         """
         Fill NA/NaN values with the specified value.
 
@@ -2941,6 +2941,8 @@ def fillna(self, value=None, downcast=None):
             or the string 'infer' which will try to downcast to an appropriate
             equal type (e.g. float64 to int64 if possible).
 
+            .. deprecated:: 2.1.0
+
         Returns
         -------
         Index
@@ -2958,6 +2960,16 @@ def fillna(self, value=None, downcast=None):
         """
         if not is_scalar(value):
             raise TypeError(f"'value' must be a scalar, passed: {type(value).__name__}")
+        if downcast is not lib.no_default:
+            warnings.warn(
+                f"The 'downcast' keyword in {type(self).__name__}.fillna is "
+                "deprecated and will be removed in a future version. "
+                "It was previously silently ignored.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+        else:
+            downcast = None
 
         if self.hasnans:
             result = self.putmask(self._isnan, value)

pandas/tests/indexes/test_old_base.py

@@ -593,9 +593,11 @@ def test_fillna(self, index):
             idx = type(index)(values)
 
             msg = "does not support 'downcast'"
-            with pytest.raises(NotImplementedError, match=msg):
-                # For now at least, we only raise if there are NAs present
-                idx.fillna(idx[0], downcast="infer")
+            msg2 = r"The 'downcast' keyword in .*Index\.fillna is deprecated"
+            with tm.assert_produces_warning(FutureWarning, match=msg2):
+                with pytest.raises(NotImplementedError, match=msg):
+                    # For now at least, we only raise if there are NAs present
+                    idx.fillna(idx[0], downcast="infer")
 
             expected = np.array([False] * len(idx), dtype=bool)
             expected[1] = True