Repository: pandas-dev/pandas

Issue:
Inconsistent keyword argument name for the 'periods' in pandas.Index.shift for a DatetimeIndex
The actual implementation of ``pandas.Index.shift`` for a datetime-like index takes a differently named parameter for the number of shifts than the base method.

It should be named ``periods``, which would also be consistent with the ``pandas.DataFrame.shift`` or ``pandas.Series.shift`` methods. But for a DatetimeIndex it's ``n``.

See:
https://github.com/pandas-dev/pandas/blob/v0.23.4/pandas/core/indexes/base.py#L2586
vs.
https://github.com/pandas-dev/pandas/blob/v0.23.4/pandas/core/indexes/datetimelike.py#L1021

With a DatetimeIndex, following the documentation leads to a
```
TypeError: shift() got an unexpected keyword argument 'periods'
```

If this is somehow intended, then it should be stated so in the docstring for ``pandas.Index.shift``.

pandas version is 0.23.4



Discussion:
They probably used to be separate classes, and then were merged. We could deprecate `n` and replace it with `periods`.
@arminv do you have any interest in doing the same for `PeriodIndex`? I think we should be consistent everywhere if possible. https://github.com/pandas-dev/pandas/blob/7343fd37f809feeb98844a34dc5854a08df2aa94/pandas/core/arrays/period.py#L322
@TomAugspurger yeah sure! I’ll start working on it

Resolving patch:
diff --git a/pandas/core/arrays/datetimelike.py b/pandas/core/arrays/datetimelike.py
--- a/pandas/core/arrays/datetimelike.py
+++ b/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)
 
diff --git a/pandas/core/arrays/period.py b/pandas/core/arrays/period.py
--- a/pandas/core/arrays/period.py
+++ b/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
diff --git a/pandas/core/generic.py b/pandas/core/generic.py
--- a/pandas/core/generic.py
+++ b/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
         -----


Test patch:
diff --git a/pandas/tests/indexes/period/test_arithmetic.py b/pandas/tests/indexes/period/test_arithmetic.py
--- a/pandas/tests/indexes/period/test_arithmetic.py
+++ b/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)