Backport PR #48599 on branch 1.5.x (DOC: Add deprecation infos to deprecated functions) (#48690)

Backport PR #48599: DOC: Add deprecation infos to deprecated functions

Co-authored-by: Patrick Hoefler <[email protected]>

Author: meeseeksmachine

pandas/core/groupby/groupby.py

@@ -2948,6 +2948,22 @@ def ffill(self, limit=None):
         return self._fill("ffill", limit=limit)
 
     def pad(self, limit=None):
+        """
+        Forward fill the values.
+
+        .. deprecated:: 1.4
+            Use ffill instead.
+
+        Parameters
+        ----------
+        limit : int, optional
+            Limit of how many values to fill.
+
+        Returns
+        -------
+        Series or DataFrame
+            Object with missing values filled.
+        """
         warnings.warn(
             "pad is deprecated and will be removed in a future version. "
             "Use ffill instead.",
@@ -2956,8 +2972,6 @@ def pad(self, limit=None):
         )
         return self.ffill(limit=limit)
 
-    pad.__doc__ = ffill.__doc__
-
     @final
     @Substitution(name="groupby")
     def bfill(self, limit=None):
@@ -2984,6 +2998,22 @@ def bfill(self, limit=None):
         return self._fill("bfill", limit=limit)
 
     def backfill(self, limit=None):
+        """
+        Backward fill the values.
+
+        .. deprecated:: 1.4
+            Use bfill instead.
+
+        Parameters
+        ----------
+        limit : int, optional
+            Limit of how many values to fill.
+
+        Returns
+        -------
+        Series or DataFrame
+            Object with missing values filled.
+        """
         warnings.warn(
             "backfill is deprecated and will be removed in a future version. "
             "Use bfill instead.",
@@ -2992,8 +3022,6 @@ def backfill(self, limit=None):
         )
         return self.bfill(limit=limit)
 
-    backfill.__doc__ = bfill.__doc__
-
     @final
     @Substitution(name="groupby")
     @Substitution(see_also=_common_see_also)

pandas/core/indexes/base.py

@@ -3766,6 +3766,10 @@ def get_loc(self, key, method=None, tolerance=None):
             * backfill / bfill: use NEXT index value if no exact match
             * nearest: use the NEAREST index value if no exact match. Tied
               distances are broken by preferring the larger index value.
+
+            .. deprecated:: 1.4
+                Use index.get_indexer([item], method=...) instead.
+
         tolerance : int or float, optional
             Maximum distance from index value for inexact matches. The value of
             the index at the matching location must satisfy the equation

pandas/core/indexes/interval.py

@@ -592,6 +592,8 @@ def get_loc(
         method : {None}, optional
             * default: matches where the label is within an interval only.
 
+            .. deprecated:: 1.4
+
         Returns
         -------
         int if unique index, slice if monotonic index, else mask

pandas/core/resample.py

@@ -546,6 +546,21 @@ def ffill(self, limit=None):
         return self._upsample("ffill", limit=limit)
 
     def pad(self, limit=None):
+        """
+        Forward fill the values.
+
+        .. deprecated:: 1.4
+            Use ffill instead.
+
+        Parameters
+        ----------
+        limit : int, optional
+            Limit of how many values to fill.
+
+        Returns
+        -------
+        An upsampled Series.
+        """
         warnings.warn(
             "pad is deprecated and will be removed in a future version. "
             "Use ffill instead.",
@@ -554,8 +569,6 @@ def pad(self, limit=None):
         )
         return self.ffill(limit=limit)
 
-    pad.__doc__ = ffill.__doc__
-
     def nearest(self, limit=None):
         """
         Resample by using the nearest value.
@@ -719,6 +732,22 @@ def bfill(self, limit=None):
         return self._upsample("bfill", limit=limit)
 
     def backfill(self, limit=None):
+        """
+        Backward fill the values.
+
+        .. deprecated:: 1.4
+            Use bfill instead.
+
+        Parameters
+        ----------
+        limit : int, optional
+            Limit of how many values to fill.
+
+        Returns
+        -------
+        Series, DataFrame
+            An upsampled Series or DataFrame with backward filled NaN values.
+        """
         warnings.warn(
             "backfill is deprecated and will be removed in a future version. "
             "Use bfill instead.",
@@ -727,8 +756,6 @@ def backfill(self, limit=None):
         )
         return self.bfill(limit=limit)
 
-    backfill.__doc__ = bfill.__doc__
-
     def fillna(self, method, limit=None):
         """
         Fill missing values introduced by upsampling.