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

- [x] closes #22458 
- [x] tests added / passed
- [x] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [x] 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')
```

Labels:
name: Datetime
description: Datetime data dtype
name: API Design
name: Deprecate
description: Functionality to remove in pandas

Comments:
Hello @arminv! Thanks for updating the PR.

 - There are no PEP8 issues in the file [`pandas/core/arrays/datetimelike.py`](https://github.com/arminv/pandas/blob/6f627ac2d96aa25881f3514242c95af001ae3b74/pandas/core/arrays/datetimelike.py) !

 - There are no PEP8 issues in the file [`pandas/tests/indexes/datetimes/test_ops.py`](https://github.com/arminv/pandas/blob/6f627ac2d96aa25881f3514242c95af001ae3b74/pandas/tests/indexes/datetimes/test_ops.py) !



##### Comment last updated on September 15, 2018 at 18:58 Hours UTC
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/22697?src=pr&el=h1) Report
> Merging [#22697](https://codecov.io/gh/pandas-dev/pandas/pull/22697?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/1c113db60b68c5a262d64e92dc9de72bfe59aed5?src=pr&el=desc) will **increase** coverage by `<.01%`.
> The diff coverage is `100%`.

[![Impacted file tree graph](https://codecov.io/gh/pandas-dev/pandas/pull/22697/graphs/tree.svg?width=650&token=eZ4WkYLtcO&height=150&src=pr)](https://codecov.io/gh/pandas-dev/pandas/pull/22697?src=pr&el=tree)

```diff
@@            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%> (ø)` | :arrow_up: |
| #single | `42.33% <42.85%> (ø)` | :arrow_up: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/22697?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/generic.py](https://codecov.io/gh/pandas-dev/pandas/pull/22697/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ2VuZXJpYy5weQ==) | `96.67% <ø> (ø)` | :arrow_up: |
| [pandas/core/arrays/datetimelike.py](https://codecov.io/gh/pandas-dev/pandas/pull/22697/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvYXJyYXlzL2RhdGV0aW1lbGlrZS5weQ==) | `95.53% <100%> (+0.02%)` | :arrow_up: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/22697?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/22697?src=pr&el=footer). Last update [1c113db...d9bbfe8](https://codecov.io/gh/pandas-dev/pandas/pull/22697?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

Thanks!