diff --git a/doc/source/whatsnew/v0.24.0.txt b/doc/source/whatsnew/v0.24.0.txt index a1a0857fe6365..62a2a358d3ba9 100644 --- a/doc/source/whatsnew/v0.24.0.txt +++ b/doc/source/whatsnew/v0.24.0.txt @@ -637,7 +637,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: diff --git a/pandas/core/arrays/datetimelike.py b/pandas/core/arrays/datetimelike.py index 1ce60510c6a69..e4ace2bfe1509 100644 --- 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 index 92803ab5f52e0..96a18a628fcf9 100644 --- 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 index 8de52fbfa79f0..0b5a10283946c 100644 --- 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 ----- diff --git a/pandas/tests/indexes/period/test_arithmetic.py b/pandas/tests/indexes/period/test_arithmetic.py index 3380a1ebc58dc..d9cbb3ea27d7b 100644 --- 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)