Deprecate add_prefix and add_suffix

Author: tp

doc/source/api.rst

@@ -1010,8 +1010,6 @@ Reindexing / Selection / Label manipulation
 .. autosummary::
    :toctree: generated/
 
-   DataFrame.add_prefix
-   DataFrame.add_suffix
    DataFrame.align
    DataFrame.at_time
    DataFrame.between_time
@@ -1317,8 +1315,6 @@ Reindexing / Selection / Label manipulation
 .. autosummary::
    :toctree: generated/
 
-   Panel.add_prefix
-   Panel.add_suffix
    Panel.drop
    Panel.equals
    Panel.filter

doc/source/whatsnew/v0.22.0.txt

@@ -55,7 +55,8 @@ Deprecations
 ~~~~~~~~~~~~
 
 - ``Series.from_array`` and ``SparseSeries.from_array`` are deprecated. Use the normal constructor ``Series(..)`` and ``SparseSeries(..)`` instead (:issue:`18213`).
--
+- ``DataFrame.add_prefix``, ``DataFrame.add_suffix``, ``Series.add_prefix`` and ``Series.add_suffix``
+  have been deprecated. Use the form ``obj.rename('prefix_{}_suffix'.format)`` or similar instead (:issue:`18347`).
 -
 
 .. _whatsnew_0220.prior_deprecations:

pandas/core/generic.py

@@ -785,6 +785,11 @@ def swaplevel(self, i=-2, j=-1, axis=0):
         1    2
         4    3
         dtype: int64
+        >>> s.rename('index_{}'.format)  # function, changes labels
+        index_0    1
+        index_1    2
+        index_2    3
+        dtype: object
         >>> s.rename({1: 3, 2: 5})  # mapping, changes labels
         0    1
         3    2
@@ -808,11 +813,11 @@ def swaplevel(self, i=-2, j=-1, axis=0):
         We *highly* recommend using keyword arguments to clarify your
         intent.
 
-        >>> df.rename(index=str, columns={"A": "a", "B": "c"})
-           a  c
-        0  1  4
-        1  2  5
-        2  3  6
+        >>> df.rename(index="index_{}".format, columns={"A": "a", "B": "c"})
+                 a  c
+        index_0  1  4
+        index_1  2  5
+        index_2  3  6
 
         >>> df.rename(index=str, columns={"A": "a", "C": "c"})
            a  B
@@ -2590,6 +2595,8 @@ def _update_inplace(self, result, verify_is_copy=True):
 
     def add_prefix(self, prefix):
         """
+        DEPRECATED: Use ``obj.rename('prefix_{}'.format)`` or similar instead.
+
         Concatenate prefix string with panel items names.
 
         Parameters
@@ -2599,12 +2606,20 @@ def add_prefix(self, prefix):
         Returns
         -------
         with_prefix : type of caller
+
+        See Also:
+        ---------
+        rename : Alter axes labels.
         """
+        warnings.warn("'add_prefix' is deprecated and will be removed in a "
+                      "future version.", FutureWarning, stacklevel=2)
         new_data = self._data.add_prefix(prefix)
         return self._constructor(new_data).__finalize__(self)
 
     def add_suffix(self, suffix):
         """
+        DEPRECATED: Use ``obj.rename('{}_suffix'.format)`` or similar instead.
+
         Concatenate suffix string with panel items names.
 
         Parameters
@@ -2614,7 +2629,13 @@ def add_suffix(self, suffix):
         Returns
         -------
         with_suffix : type of caller
+
+        See Also:
+        ---------
+        rename : Alter axes labels.
         """
+        warnings.warn("'add_suffix' is deprecated and will be removed in a "
+                      "future version.", FutureWarning, stacklevel=2)
         new_data = self._data.add_suffix(suffix)
         return self._constructor(new_data).__finalize__(self)
 

pandas/tests/frame/test_api.py

@@ -76,21 +76,25 @@ def test_get_value(self):
                 tm.assert_almost_equal(result, expected)
 
     def test_add_prefix_suffix(self):
-        with_prefix = self.frame.add_prefix('foo#')
-        expected = pd.Index(['foo#%s' % c for c in self.frame.columns])
-        tm.assert_index_equal(with_prefix.columns, expected)
-
-        with_suffix = self.frame.add_suffix('#foo')
-        expected = pd.Index(['%s#foo' % c for c in self.frame.columns])
-        tm.assert_index_equal(with_suffix.columns, expected)
-
-        with_pct_prefix = self.frame.add_prefix('%')
-        expected = pd.Index(['%{}'.format(c) for c in self.frame.columns])
-        tm.assert_index_equal(with_pct_prefix.columns, expected)
-
-        with_pct_suffix = self.frame.add_suffix('%')
-        expected = pd.Index(['{}%'.format(c) for c in self.frame.columns])
-        tm.assert_index_equal(with_pct_suffix.columns, expected)
+        with pytest.warns(FutureWarning):
+            with_prefix = self.frame.add_prefix('foo#')
+            expected = pd.Index(['foo#%s' % c for c in self.frame.columns])
+            tm.assert_index_equal(with_prefix.columns, expected)
+
+        with pytest.warns(FutureWarning):
+            with_suffix = self.frame.add_suffix('#foo')
+            expected = pd.Index(['%s#foo' % c for c in self.frame.columns])
+            tm.assert_index_equal(with_suffix.columns, expected)
+
+        with pytest.warns(FutureWarning):
+            with_pct_prefix = self.frame.add_prefix('%')
+            expected = pd.Index(['%{}'.format(c) for c in self.frame.columns])
+            tm.assert_index_equal(with_pct_prefix.columns, expected)
+
+        with pytest.warns(FutureWarning):
+            with_pct_suffix = self.frame.add_suffix('%')
+            expected = pd.Index(['{}%'.format(c) for c in self.frame.columns])
+            tm.assert_index_equal(with_pct_suffix.columns, expected)
 
     def test_get_axis(self):
         f = self.frame