Deprecate .add_prefix and .add_suffix

Author: tp

doc/source/whatsnew/v0.22.0.txt

@@ -56,7 +56,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/frame.py

@@ -304,7 +304,8 @@ def _constructor(self):
 
     _constructor_sliced = Series
     _deprecations = NDFrame._deprecations | frozenset(
-        ['sortlevel', 'get_value', 'set_value', 'from_csv'])
+        ['sortlevel', 'get_value', 'set_value', 'from_csv', 'add_prefix',
+         'add_suffix'])
 
     @property
     def _constructor_expanddim(self):

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/core/series.py

@@ -149,7 +149,8 @@ class Series(base.IndexOpsMixin, generic.NDFrame):
     _metadata = ['name']
     _accessors = frozenset(['dt', 'cat', 'str'])
     _deprecations = generic.NDFrame._deprecations | frozenset(
-        ['sortlevel', 'reshape', 'get_value', 'set_value', 'from_csv'])
+        ['sortlevel', 'reshape', 'get_value', 'set_value', 'from_csv',
+         'add_prefix', 'add_suffix'])
     _allow_index_ops = True
 
     def __init__(self, data=None, index=None, dtype=None, name=None,

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 tm.assert_produces_warning(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 tm.assert_produces_warning(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 tm.assert_produces_warning(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 tm.assert_produces_warning(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