Backport PR #54838 on branch 2.1.x (Don't expose EA.pad_or_backfill to users + switch to DeprecationWarning) (#54851)

Backport PR #54838: Don't expose EA.pad_or_backfill to users + switch to DeprecationWarning

Co-authored-by: Joris Van den Bossche <[email protected]>

Author: meeseeksmachine

doc/source/reference/extensions.rst

@@ -39,6 +39,7 @@ objects.
       api.extensions.ExtensionArray._from_sequence
       api.extensions.ExtensionArray._from_sequence_of_strings
       api.extensions.ExtensionArray._hash_pandas_object
+      api.extensions.ExtensionArray._pad_or_backfill
       api.extensions.ExtensionArray._reduce
       api.extensions.ExtensionArray._values_for_argsort
       api.extensions.ExtensionArray._values_for_factorize
@@ -54,7 +55,6 @@ objects.
       api.extensions.ExtensionArray.interpolate
       api.extensions.ExtensionArray.isin
       api.extensions.ExtensionArray.isna
-      api.extensions.ExtensionArray.pad_or_backfill
       api.extensions.ExtensionArray.ravel
       api.extensions.ExtensionArray.repeat
       api.extensions.ExtensionArray.searchsorted

doc/source/whatsnew/v2.1.0.rst

@@ -583,7 +583,7 @@ Other Deprecations
 - Deprecated positional indexing on :class:`Series` with :meth:`Series.__getitem__` and :meth:`Series.__setitem__`, in a future version ``ser[item]`` will *always* interpret ``item`` as a label, not a position (:issue:`50617`)
 - Deprecated replacing builtin and NumPy functions in ``.agg``, ``.apply``, and ``.transform``; use the corresponding string alias (e.g. ``"sum"`` for ``sum`` or ``np.sum``) instead (:issue:`53425`)
 - Deprecated strings ``T``, ``t``, ``L`` and ``l`` denoting units in :func:`to_timedelta` (:issue:`52536`)
-- Deprecated the "method" and "limit" keywords in ``.ExtensionArray.fillna``, implement and use ``pad_or_backfill`` instead (:issue:`53621`)
+- Deprecated the "method" and "limit" keywords in ``.ExtensionArray.fillna``, implement ``_pad_or_backfill`` instead (:issue:`53621`)
 - Deprecated the ``method`` and ``limit`` keywords in :meth:`DataFrame.replace` and :meth:`Series.replace` (:issue:`33302`)
 - Deprecated the ``method`` and ``limit`` keywords on :meth:`Series.fillna`, :meth:`DataFrame.fillna`, :meth:`.SeriesGroupBy.fillna`, :meth:`.DataFrameGroupBy.fillna`, and :meth:`.Resampler.fillna`, use ``obj.bfill()`` or ``obj.ffill()`` instead (:issue:`53394`)
 - Deprecated the behavior of :meth:`Series.__getitem__`, :meth:`Series.__setitem__`, :meth:`DataFrame.__getitem__`, :meth:`DataFrame.__setitem__` with an integer slice on objects with a floating-dtype index, in a future version this will be treated as *positional* indexing (:issue:`49612`)

pandas/core/arrays/_mixins.py

@@ -296,13 +296,8 @@ def _fill_mask_inplace(
         func = missing.get_fill_func(method, ndim=self.ndim)
         func(self._ndarray.T, limit=limit, mask=mask.T)
 
-    def pad_or_backfill(
-        self,
-        *,
-        method: FillnaOptions,
-        limit: int | None = None,
-        limit_area: Literal["inside", "outside"] | None = None,
-        copy: bool = True,
+    def _pad_or_backfill(
+        self, *, method: FillnaOptions, limit: int | None = None, copy: bool = True
     ) -> Self:
         mask = self.isna()
         if mask.any():

pandas/core/arrays/arrow/array.py

@@ -924,19 +924,14 @@ def dropna(self) -> Self:
         """
         return type(self)(pc.drop_null(self._pa_array))
 
-    def pad_or_backfill(
-        self,
-        *,
-        method: FillnaOptions,
-        limit: int | None = None,
-        limit_area: Literal["inside", "outside"] | None = None,
-        copy: bool = True,
+    def _pad_or_backfill(
+        self, *, method: FillnaOptions, limit: int | None = None, copy: bool = True
     ) -> Self:
         if not self._hasna:
             # TODO(CoW): Not necessary anymore when CoW is the default
             return self.copy()
 
-        if limit is not None and limit_area is not None:
+        if limit is None:
             method = missing.clean_fill_method(method)
             try:
                 if method == "pad":
@@ -952,9 +947,7 @@ def pad_or_backfill(
 
         # TODO(3.0): after EA.fillna 'method' deprecation is enforced, we can remove
         #  this method entirely.
-        return super().pad_or_backfill(
-            method=method, limit=limit, limit_area=limit_area, copy=copy
-        )
+        return super()._pad_or_backfill(method=method, limit=limit, copy=copy)
 
     @doc(ExtensionArray.fillna)
     def fillna(
@@ -974,7 +967,7 @@ def fillna(
             return super().fillna(value=value, method=method, limit=limit, copy=copy)
 
         if method is not None:
-            return super().pad_or_backfill(method=method, limit=limit, copy=copy)
+            return super().fillna(method=method, limit=limit, copy=copy)
 
         if isinstance(value, (np.ndarray, ExtensionArray)):
             # Similar to check_value_size, but we do not mask here since we may

pandas/core/arrays/base.py

@@ -132,7 +132,6 @@ class ExtensionArray:
     interpolate
     isin
     isna
-    pad_or_backfill
     ravel
     repeat
     searchsorted
@@ -148,6 +147,7 @@ class ExtensionArray:
     _from_sequence
     _from_sequence_of_strings
     _hash_pandas_object
+    _pad_or_backfill
     _reduce
     _values_for_argsort
     _values_for_factorize
@@ -183,7 +183,7 @@ class ExtensionArray:
     methods:
 
     * fillna
-    * pad_or_backfill
+    * _pad_or_backfill
     * dropna
     * unique
     * factorize / _values_for_factorize
@@ -917,13 +917,8 @@ def interpolate(
             f"{type(self).__name__} does not implement interpolate"
         )
 
-    def pad_or_backfill(
-        self,
-        *,
-        method: FillnaOptions,
-        limit: int | None = None,
-        limit_area: Literal["inside", "outside"] | None = None,
-        copy: bool = True,
+    def _pad_or_backfill(
+        self, *, method: FillnaOptions, limit: int | None = None, copy: bool = True
     ) -> Self:
         """
         Pad or backfill values, used by Series/DataFrame ffill and bfill.
@@ -959,26 +954,26 @@ def pad_or_backfill(
         Examples
         --------
         >>> arr = pd.array([np.nan, np.nan, 2, 3, np.nan, np.nan])
-        >>> arr.pad_or_backfill(method="backfill", limit=1)
+        >>> arr._pad_or_backfill(method="backfill", limit=1)
         <IntegerArray>
         [<NA>, 2, 2, 3, <NA>, <NA>]
         Length: 6, dtype: Int64
         """
 
         # If a 3rd-party EA has implemented this functionality in fillna,
-        #  we warn that they need to implement pad_or_backfill instead.
+        #  we warn that they need to implement _pad_or_backfill instead.
         if (
             type(self).fillna is not ExtensionArray.fillna
-            and type(self).pad_or_backfill is ExtensionArray.pad_or_backfill
+            and type(self)._pad_or_backfill is ExtensionArray._pad_or_backfill
         ):
-            # Check for pad_or_backfill here allows us to call
-            #  super().pad_or_backfill without getting this warning
+            # Check for _pad_or_backfill here allows us to call
+            #  super()._pad_or_backfill without getting this warning
             warnings.warn(
                 "ExtensionArray.fillna 'method' keyword is deprecated. "
-                "In a future version. arr.pad_or_backfill will be called "
+                "In a future version. arr._pad_or_backfill will be called "
                 "instead. 3rd-party ExtensionArray authors need to implement "
-                "pad_or_backfill.",
-                FutureWarning,
+                "_pad_or_backfill.",
+                DeprecationWarning,
                 stacklevel=find_stack_level(),
             )
             return self.fillna(method=method, limit=limit)
@@ -1062,8 +1057,7 @@ def fillna(
         if method is not None:
             warnings.warn(
                 f"The 'method' keyword in {type(self).__name__}.fillna is "
-                "deprecated and will be removed in a future version. "
-                "Use pad_or_backfill instead.",
+                "deprecated and will be removed in a future version.",
                 FutureWarning,
                 stacklevel=find_stack_level(),
             )

pandas/core/arrays/interval.py

@@ -890,19 +890,12 @@ def max(self, *, axis: AxisInt | None = None, skipna: bool = True) -> IntervalOr
         indexer = obj.argsort()[-1]
         return obj[indexer]
 
-    def pad_or_backfill(  # pylint: disable=useless-parent-delegation
-        self,
-        *,
-        method: FillnaOptions,
-        limit: int | None = None,
-        limit_area: Literal["inside", "outside"] | None = None,
-        copy: bool = True,
+    def _pad_or_backfill(  # pylint: disable=useless-parent-delegation
+        self, *, method: FillnaOptions, limit: int | None = None, copy: bool = True
     ) -> Self:
         # TODO(3.0): after EA.fillna 'method' deprecation is enforced, we can remove
         #  this method entirely.
-        return super().pad_or_backfill(
-            method=method, limit=limit, limit_area=limit_area, copy=copy
-        )
+        return super()._pad_or_backfill(method=method, limit=limit, copy=copy)
 
     def fillna(
         self, value=None, method=None, limit: int | None = None, copy: bool = True

pandas/core/arrays/masked.py

@@ -190,13 +190,8 @@ def __getitem__(self, item: PositionalIndexer) -> Self | Any:
 
         return self._simple_new(self._data[item], newmask)
 
-    def pad_or_backfill(
-        self,
-        *,
-        method: FillnaOptions,
-        limit: int | None = None,
-        limit_area: Literal["inside", "outside"] | None = None,
-        copy: bool = True,
+    def _pad_or_backfill(
+        self, *, method: FillnaOptions, limit: int | None = None, copy: bool = True
     ) -> Self:
         mask = self._mask
 

pandas/core/arrays/numpy_.py

@@ -240,7 +240,10 @@ def _values_for_factorize(self) -> tuple[np.ndarray, float | None]:
             fv = np.nan
         return self._ndarray, fv
 
-    def pad_or_backfill(
+    # Base EA class (and all other EA classes) don't have limit_area keyword
+    # This can be removed here as well when the interpolate ffill/bfill method
+    # deprecation is enforced
+    def _pad_or_backfill(
         self,
         *,
         method: FillnaOptions,

pandas/core/arrays/period.py

@@ -791,20 +791,13 @@ def searchsorted(
         m8arr = self._ndarray.view("M8[ns]")
         return m8arr.searchsorted(npvalue, side=side, sorter=sorter)
 
-    def pad_or_backfill(
-        self,
-        *,
-        method: FillnaOptions,
-        limit: int | None = None,
-        limit_area: Literal["inside", "outside"] | None = None,
-        copy: bool = True,
+    def _pad_or_backfill(
+        self, *, method: FillnaOptions, limit: int | None = None, copy: bool = True
     ) -> Self:
         # view as dt64 so we get treated as timelike in core.missing,
         #  similar to dtl._period_dispatch
         dta = self.view("M8[ns]")
-        result = dta.pad_or_backfill(
-            method=method, limit=limit, limit_area=limit_area, copy=copy
-        )
+        result = dta._pad_or_backfill(method=method, limit=limit, copy=copy)
         if copy:
             return cast("Self", result.view(self.dtype))
         else:

pandas/core/arrays/sparse/array.py

@@ -712,19 +712,12 @@ def isna(self):
         mask[self.sp_index.indices] = isna(self.sp_values)
         return type(self)(mask, fill_value=False, dtype=dtype)
 
-    def pad_or_backfill(  # pylint: disable=useless-parent-delegation
-        self,
-        *,
-        method: FillnaOptions,
-        limit: int | None = None,
-        limit_area: Literal["inside", "outside"] | None = None,
-        copy: bool = True,
+    def _pad_or_backfill(  # pylint: disable=useless-parent-delegation
+        self, *, method: FillnaOptions, limit: int | None = None, copy: bool = True
     ) -> Self:
         # TODO(3.0): We can remove this method once deprecation for fillna method
         #  keyword is enforced.
-        return super().pad_or_backfill(
-            method=method, limit=limit, limit_area=limit_area, copy=copy
-        )
+        return super()._pad_or_backfill(method=method, limit=limit, copy=copy)
 
     def fillna(
         self,