DEPR: deprecate integer add/sub with DTI/TDI/PI/Timestamp/Period
State: closed

Discussed in #21939; these operations cause headaches and internal-inconsistencies (e.g. ATM `Timedelta` is the only one of the related classes that doesn't support integer ops)

- [x] closes #21939
- [x] tests added / passed
- [x] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [x] whatsnew entry


Labels:
name: Datetime
description: Datetime data dtype
name: Numeric Operations
description: Arithmetic, Comparison, and Logical operations
name: Deprecate
description: Functionality to remove in pandas

Comments:
There are some reference to integer arithmetic in `timeseries.rst` (e.g. https://pandas.pydata.org/pandas-docs/stable/timeseries.html#period). It's probably a good idea to scrub them so we don't advertise depreciated functionality
Is there a usage of `tm.assert_produces_warning` to use when we expect the affected code to produce two warnings?
> Is there a usage of tm.assert_produces_warning to use when we expect the affected code to produce two warnings?

I think you can pass a list? (you can to the underlying machinery, so maybe this just works, if not it should)
@jbrockmendel pls add to the list in the deprecation issue (#6581) , when we merge can check the box
Will update as indicated.  BTW gentle ping re #22350; many upcoming PRs touch those files, so it'd be helpful to get it out of the way.
> I think you can pass a list? (you can to the underlying machinery, so maybe this just works, if not it should)

Doesn't look like it, I'll fix that.
> I think you can pass a list? (you can to the underlying machinery, so maybe this just works, if not it should)

Trying to implement this, I've got most of it working, but can find no combination of `stacklevel=` parameters that don't cause the "not set with correct stacklevel" assertion to fail.  Who is the team expert on this?
don't worry about checking the stacklevel too much, the idea is to raise it to a reasonable level, e.g. if you run the tests, it should point to the top-level of the code where its most releveant (rather than a lower level call). Just pick something that looks reasonable, and you can turn off the stacklevel check itself. 
Hello @jbrockmendel! Thanks for updating the PR.

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

 - There are no PEP8 issues in the file [`pandas/core/resample.py`](https://github.com/jbrockmendel/pandas/blob/55dc265f3b80c2d047967b1a7afc3fbfe20d83d3/pandas/core/resample.py) !

 - There are no PEP8 issues in the file [`pandas/plotting/_converter.py`](https://github.com/jbrockmendel/pandas/blob/55dc265f3b80c2d047967b1a7afc3fbfe20d83d3/pandas/plotting/_converter.py) !

 - There are no PEP8 issues in the file [`pandas/tests/arithmetic/test_datetime64.py`](https://github.com/jbrockmendel/pandas/blob/55dc265f3b80c2d047967b1a7afc3fbfe20d83d3/pandas/tests/arithmetic/test_datetime64.py) !

 - There are no PEP8 issues in the file [`pandas/tests/arithmetic/test_period.py`](https://github.com/jbrockmendel/pandas/blob/55dc265f3b80c2d047967b1a7afc3fbfe20d83d3/pandas/tests/arithmetic/test_period.py) !

 - There are no PEP8 issues in the file [`pandas/tests/frame/test_timeseries.py`](https://github.com/jbrockmendel/pandas/blob/55dc265f3b80c2d047967b1a7afc3fbfe20d83d3/pandas/tests/frame/test_timeseries.py) !

 - There are no PEP8 issues in the file [`pandas/tests/indexes/datetimelike.py`](https://github.com/jbrockmendel/pandas/blob/55dc265f3b80c2d047967b1a7afc3fbfe20d83d3/pandas/tests/indexes/datetimelike.py) !

 - There are no PEP8 issues in the file [`pandas/tests/indexes/datetimes/test_arithmetic.py`](https://github.com/jbrockmendel/pandas/blob/55dc265f3b80c2d047967b1a7afc3fbfe20d83d3/pandas/tests/indexes/datetimes/test_arithmetic.py) !

 - There are no PEP8 issues in the file [`pandas/tests/indexes/period/test_period.py`](https://github.com/jbrockmendel/pandas/blob/55dc265f3b80c2d047967b1a7afc3fbfe20d83d3/pandas/tests/indexes/period/test_period.py) !

 - There are no PEP8 issues in the file [`pandas/tests/indexes/timedeltas/test_arithmetic.py`](https://github.com/jbrockmendel/pandas/blob/55dc265f3b80c2d047967b1a7afc3fbfe20d83d3/pandas/tests/indexes/timedeltas/test_arithmetic.py) !

 - There are no PEP8 issues in the file [`pandas/tests/indexing/test_partial.py`](https://github.com/jbrockmendel/pandas/blob/55dc265f3b80c2d047967b1a7afc3fbfe20d83d3/pandas/tests/indexing/test_partial.py) !

 - There are no PEP8 issues in the file [`pandas/tests/scalar/period/test_asfreq.py`](https://github.com/jbrockmendel/pandas/blob/55dc265f3b80c2d047967b1a7afc3fbfe20d83d3/pandas/tests/scalar/period/test_asfreq.py) !

 - There are no PEP8 issues in the file [`pandas/tests/scalar/period/test_period.py`](https://github.com/jbrockmendel/pandas/blob/55dc265f3b80c2d047967b1a7afc3fbfe20d83d3/pandas/tests/scalar/period/test_period.py) !

 - There are no PEP8 issues in the file [`pandas/tests/scalar/timestamp/test_arithmetic.py`](https://github.com/jbrockmendel/pandas/blob/55dc265f3b80c2d047967b1a7afc3fbfe20d83d3/pandas/tests/scalar/timestamp/test_arithmetic.py) !

 - There are no PEP8 issues in the file [`pandas/tests/test_resample.py`](https://github.com/jbrockmendel/pandas/blob/55dc265f3b80c2d047967b1a7afc3fbfe20d83d3/pandas/tests/test_resample.py) !

 - There are no PEP8 issues in the file [`pandas/tests/tseries/offsets/test_offsets.py`](https://github.com/jbrockmendel/pandas/blob/55dc265f3b80c2d047967b1a7afc3fbfe20d83d3/pandas/tests/tseries/offsets/test_offsets.py) !

 - There are no PEP8 issues in the file [`pandas/tseries/offsets.py`](https://github.com/jbrockmendel/pandas/blob/55dc265f3b80c2d047967b1a7afc3fbfe20d83d3/pandas/tseries/offsets.py) !



##### Comment last updated on October 15, 2018 at 19:17 Hours UTC
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/22535?src=pr&el=h1) Report
> Merging [#22535](https://codecov.io/gh/pandas-dev/pandas/pull/22535?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/de39bfc5e5c6483cb2669773fa10ddc2e32ca111?src=pr&el=desc) will **decrease** coverage by `<.01%`.
> The diff coverage is `81.25%`.

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

```diff
@@            Coverage Diff             @@
##           master   #22535      +/-   ##
==========================================
- Coverage   92.21%   92.21%   -0.01%     
==========================================
  Files         161      161              
  Lines       51173    51191      +18     
==========================================
+ Hits        47190    47206      +16     
- Misses       3983     3985       +2
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.65% <81.25%> (-0.01%)` | :arrow_down: |
| #single | `42.22% <3.12%> (-0.02%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/22535?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/arrays/datetimelike.py](https://codecov.io/gh/pandas-dev/pandas/pull/22535/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvYXJyYXlzL2RhdGV0aW1lbGlrZS5weQ==) | `96.16% <100%> (+0.04%)` | :arrow_up: |
| [pandas/core/arrays/period.py](https://codecov.io/gh/pandas-dev/pandas/pull/22535/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvYXJyYXlzL3BlcmlvZC5weQ==) | `97.48% <100%> (ø)` | :arrow_up: |
| [pandas/plotting/\_converter.py](https://codecov.io/gh/pandas-dev/pandas/pull/22535/diff?src=pr&el=tree#diff-cGFuZGFzL3Bsb3R0aW5nL19jb252ZXJ0ZXIucHk=) | `63.67% <50%> (ø)` | :arrow_up: |
| [pandas/core/resample.py](https://codecov.io/gh/pandas-dev/pandas/pull/22535/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvcmVzYW1wbGUucHk=) | `96.99% <75%> (ø)` | :arrow_up: |
| [pandas/tseries/offsets.py](https://codecov.io/gh/pandas-dev/pandas/pull/22535/diff?src=pr&el=tree#diff-cGFuZGFzL3RzZXJpZXMvb2Zmc2V0cy5weQ==) | `97.22% <83.33%> (-0.15%)` | :arrow_down: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/22535?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/22535?src=pr&el=footer). Last update [de39bfc...4a7b589](https://codecov.io/gh/pandas-dev/pandas/pull/22535?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

needs a rebase
> needs a rebase

Yah, first needs a whatsnew section, which I've been procrastinating on.
Since last review:

Edits to pass CI env that fails on unhandled warnings, so lots of `tm.assert_produces_warning`s added.

Identified a bug in PeriodIndex addition #22998.  The place this shows up here is in `PeriodIndex.to_timestamp` which filters out the FutureWarning and continues using the deprecated behavior until 22998 is fixed.

in tseries.offsets, many DateOffset subclasses have `apply_index` implementations that use the deprecated behavior.  They are not hard to update, but that would come with a non-trivial performance penalty.  For now they filter out the warning and continue using the deprecated behavior.  I think the thing to do is to make a non-method helper function (possibly in tslibs.offsets) to take the place of this behavior.
also prob need to check the docs and change / remove the cases which causes warnings.
thanks @jbrockmendel sometimes they take a lot of iterations :-D
It's all about the power of Teamwork.
@jbrockmendel what was actually the rationale of deprecating it for Periods as well? 
The issue that is closed by this (https://github.com/pandas-dev/pandas/issues/21939) discusses it for DatetimeIndex/TimedeltaIndex, but I think says to keep it for PeriodIndex for now. 

In any case, for PeriodIndex, this was an explicitly documented behaviour, and the documentation is now no longer up to date. 
But instead of updating the docs, I think we should also reconsider the deprecation. Or at least provide a clear alternative way.

(and to be clear: I fully agree with the deprecation for DatetimeIndex / TimedeltaIndex!)

> I think we should also reconsider the deprecation

I'm open to that.  The ones I care about are the TS/TD/DTI/TDI
After commenting here I opened an issue with the same content: https://github.com/pandas-dev/pandas/issues/24305. Can you post it there?