API/DEPR: 'periods' argument instead of 'n' for DatetimeIndex.shift()

[arminv]

• closes Inconsistent keyword argument name for the 'periods' in pandas.Index.shift for a DatetimeIndex #22458
• tests added / passed
• passes git diff upstream/master -u -- "*.py" | flake8 --diff
• whatsnew entry

In order to be consistent with Index.shift & Series.shift, n argument was deprecated in favor of periods.

In [2]: idx = pd.DatetimeIndex(start='2014-08-01 10:00', freq='H',
   ...:                         periods=3, tz='Asia/Calcutta')
   ...:                         

In [3]: idx
Out[3]: 
DatetimeIndex(['2014-08-01 10:00:00+05:30', '2014-08-01 11:00:00+05:30',
               '2014-08-01 12:00:00+05:30'],
              dtype='datetime64[ns, Asia/Calcutta]', freq='H')

In [4]: idx.shift(1, freq=None)
Out[4]: 
DatetimeIndex(['2014-08-01 11:00:00+05:30', '2014-08-01 12:00:00+05:30',
               '2014-08-01 13:00:00+05:30'],
              dtype='datetime64[ns, Asia/Calcutta]', freq='H')

In [5]: idx.shift(periods=1, freq=None)
Out[5]: 
DatetimeIndex(['2014-08-01 11:00:00+05:30', '2014-08-01 12:00:00+05:30',
               '2014-08-01 13:00:00+05:30'],
              dtype='datetime64[ns, Asia/Calcutta]', freq='H')

In [6]: idx.shift(n=1, freq=None)
//anaconda/envs/pandas_dev/bin/ipython:1: FutureWarning: the 'n' keyword is deprecated, use 'periods' instead
  #!//anaconda/envs/pandas_dev/bin/python
Out[6]: 
DatetimeIndex(['2014-08-01 11:00:00+05:30', '2014-08-01 12:00:00+05:30',
               '2014-08-01 13:00:00+05:30'],
              dtype='datetime64[ns, Asia/Calcutta]', freq='H')

[pep8speaks]

Hello @arminv! Thanks for updating the PR.

• There are no PEP8 issues in the file pandas/core/arrays/datetimelike.py !

• There are no PEP8 issues in the file pandas/tests/indexes/datetimes/test_ops.py !

Comment last updated on September 15, 2018 at 18:58 Hours UTC

[TomAugspurger]

We'll need to deprecate periods. Your change would break people doing .shift(n=1).

This could be somewhat tricky to do... I think you may have to make the signature *args, **kwargs, and manually do the parsing

• shift(1): no warning
• shift(n=1): warning
• shift(periods=1): no warning

lmk if you need help.

[arminv]

@TomAugspurger Thanks. I started parsing manually but couldn't make some tests pass. Then I realized there is a decorator in pandas/pandas/util/_decorators.py that I could use for deprecating n. Lmk if there is anything else to be done.

[codecov]

Codecov Report

Merging #22697 into master will increase coverage by <.01%.
The diff coverage is 100%.

@@            Coverage Diff             @@
##           master   #22697      +/-   ##
==========================================
+ Coverage   92.17%   92.17%   +<.01%     
==========================================
  Files         169      169              
  Lines       50778    50780       +2     
==========================================
+ Hits        46807    46809       +2     
  Misses       3971     3971

Flag	Coverage Δ
#multiple	90.59% <100%> (ø)	⬆️
#single	42.33% <42.85%> (ø)	⬆️

Impacted Files	Coverage Δ
pandas/core/generic.py	96.67% <ø> (ø)	⬆️
pandas/core/arrays/datetimelike.py	95.53% <100%> (+0.02%)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 1c113db...d9bbfe8. Read the comment docs.

[arminv]

@jreback I also added Index.shift here.

[TomAugspurger]

Could you change this to true? If the test fails, you may need to increase the stacklevel 1.

[arminv]

@TomAugspurger done, test passed too.

[TomAugspurger]

Thanks!