API/DEPR: 'periods' argument instead of 'n' for PeriodIndex.shift() (pandas-dev#22912)

Author: arminv

doc/source/whatsnew/v0.24.0.txt

@@ -638,7 +638,7 @@ Deprecations
 - :meth:`Series.str.cat` has deprecated using arbitrary list-likes *within* list-likes. A list-like container may still contain
   many ``Series``, ``Index`` or 1-dimensional ``np.ndarray``, or alternatively, only scalar values. (:issue:`21950`)
 - :meth:`FrozenNDArray.searchsorted` has deprecated the ``v`` parameter in favor of ``value`` (:issue:`14645`)
-- :func:`DatetimeIndex.shift` now accepts ``periods`` argument instead of ``n`` for consistency with :func:`Index.shift` and :func:`Series.shift`. Using ``n`` throws a deprecation warning (:issue:`22458`)
+- :func:`DatetimeIndex.shift` and :func:`PeriodIndex.shift` now accept ``periods`` argument instead of ``n`` for consistency with :func:`Index.shift` and :func:`Series.shift`. Using ``n`` throws a deprecation warning (:issue:`22458`, :issue:`22912`)
 
 .. _whatsnew_0240.prior_deprecations:
 

pandas/core/arrays/datetimelike.py

@@ -552,6 +552,7 @@ def shift(self, periods, freq=None):
         See Also
         --------
         Index.shift : Shift values of Index.
+        PeriodIndex.shift : Shift values of PeriodIndex.
         """
         return self._time_shift(periods=periods, freq=freq)
 

pandas/core/arrays/period.py

@@ -14,7 +14,7 @@
 from pandas._libs.tslibs.fields import isleapyear_arr
 
 from pandas import compat
-from pandas.util._decorators import cache_readonly
+from pandas.util._decorators import (cache_readonly, deprecate_kwarg)
 
 from pandas.core.dtypes.common import (
     is_integer_dtype, is_float_dtype, is_period_dtype)
@@ -319,20 +319,32 @@ def _add_delta(self, other):
         ordinal_delta = self._maybe_convert_timedelta(other)
         return self._time_shift(ordinal_delta)
 
-    def shift(self, n):
+    @deprecate_kwarg(old_arg_name='n', new_arg_name='periods')
+    def shift(self, periods):
         """
-        Specialized shift which produces an Period Array/Index
+        Shift index by desired number of increments.
+
+        This method is for shifting the values of period indexes
+        by a specified time increment.
 
         Parameters
         ----------
-        n : int
-            Periods to shift by
+        periods : int
+            Number of periods (or increments) to shift by,
+            can be positive or negative.
+
+            .. versionchanged:: 0.24.0
 
         Returns
         -------
-        shifted : Period Array/Index
+        pandas.PeriodIndex
+            Shifted index.
+
+        See Also
+        --------
+        DatetimeIndex.shift : Shift values of DatetimeIndex.
         """
-        return self._time_shift(n)
+        return self._time_shift(periods)
 
     def _time_shift(self, n):
         values = self._ndarray_values + n * self.freq.n

pandas/core/generic.py

@@ -8304,6 +8304,7 @@ def mask(self, cond, other=np.nan, inplace=False, axis=None, level=None,
         --------
         Index.shift : Shift values of Index.
         DatetimeIndex.shift : Shift values of DatetimeIndex.
+        PeriodIndex.shift : Shift values of PeriodIndex.
 
         Notes
         -----

pandas/tests/indexes/period/test_arithmetic.py

@@ -97,3 +97,12 @@ def test_shift_gh8083(self):
         expected = PeriodIndex(['2013-01-02', '2013-01-03', '2013-01-04',
                                 '2013-01-05', '2013-01-06'], freq='D')
         tm.assert_index_equal(result, expected)
+
+    def test_shift_periods(self):
+        # GH #22458 : argument 'n' was deprecated in favor of 'periods'
+        idx = PeriodIndex(freq='A', start='1/1/2001', end='12/1/2009')
+        tm.assert_index_equal(idx.shift(periods=0), idx)
+        tm.assert_index_equal(idx.shift(0), idx)
+        with tm.assert_produces_warning(FutureWarning,
+                                        check_stacklevel=True):
+            tm.assert_index_equal(idx.shift(n=0), idx)