API: PeriodIndex subtraction to return object Index of DateOffsets
State: closed

Implements _sub_period_array in DatetimeIndexOpsMixin.  Behavior is analogous to subtraction of Period scalar.

- [x] closes #13077
- [x] tests added / passed
- [x] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [x] whatsnew entry


Labels:
name: Frequency
description: DateOffsets
name: Period
description: Period data type

Comments:
I think we should be returning an array (Index?) of offsets rather than the integers which are untyped.

we don't really support this so an object Index would be ok I think.
> I think we should be returning an array (Index?) of offsets rather than the integers which are untyped.

I more-or-less agree, but ATM Period - Period returns an integer and PeriodIndex - Period returns an integer array.  These three operations should all be consistent.
> I more-or-less agree, but ATM Period - Period returns an integer and PeriodIndex - Period returns an integer array. These three operations should all be consistent.

and these should changed (both). yes its an API breaking change but much more intuitve / better. it will just have to be an object array but that's ok.
> and these should changed (both). yes its an API breaking change but much more intuitve / better. it will just have to be an object array but that's ok.


Implementing this, the non-obvious issue that comes up is what to do with `NaT`s in a `PeriodIndex` when subtracting `Period`.
 Never mind, this is easy to handle.
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20049?src=pr&el=h1) Report
> Merging [#20049](https://codecov.io/gh/pandas-dev/pandas/pull/20049?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/f1ffc5fae06a7294dc831887b0d76177aec9b708?src=pr&el=desc) will **increase** coverage by `<.01%`.
> The diff coverage is `94.44%`.

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

```diff
@@            Coverage Diff             @@
##           master   #20049      +/-   ##
==========================================
+ Coverage    91.9%    91.9%   +<.01%     
==========================================
  Files         153      153              
  Lines       49549    49565      +16     
==========================================
+ Hits        45537    45554      +17     
+ Misses       4012     4011       -1
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.3% <94.44%> (ø)` | :arrow_up: |
| #single | `41.76% <11.11%> (-0.02%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/20049?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/indexes/datetimelike.py](https://codecov.io/gh/pandas-dev/pandas/pull/20049/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9kYXRldGltZWxpa2UucHk=) | `96.8% <94.44%> (-0.09%)` | :arrow_down: |
| [pandas/util/testing.py](https://codecov.io/gh/pandas-dev/pandas/pull/20049/diff?src=pr&el=tree#diff-cGFuZGFzL3V0aWwvdGVzdGluZy5weQ==) | `85.27% <0%> (+0.2%)` | :arrow_up: |

------

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

Hello @jbrockmendel! Thanks for updating the PR.









Cheers ! There are no PEP8 issues in this Pull Request. :beers: 

##### Comment last updated on June 22, 2018 at 03:51 Hours UTC
Removing `test_pi_sub_pi` because it is entirely redundant with `test_pi_sub_isub_pi`.  Moving the latter to where it _should_ be in the test file.
@jorisvandenbossche yes, thats in #21314.
gentle ping (this should be tandem with #21314)
thanks @jbrockmendel 

also pls have a look at the period docs to see if we need updating anywhere.