DOC/API: PeriodIndex sub/add with Integers: update docs or undo deprecation

[jorisvandenbossche]

Creating an issue of my comment on the PR that deprecated PeriodIndex add/sub with integers (#22535):

@jbrockmendel what was actually the rationale of deprecating it for Periods as well?
The issue that is closed by this (#21939, cc @jreback @mroeschke) 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 (in several places throughout the docs), and the documentation is now no longer up to date (you can check the doc build to see the deprecation warnings being raised).

But instead of updating the docs, I think we should maybe also reconsider the deprecation (given that is was a clearly documented behaviour). Or at least provide a clear alternative way.

(and to be clear: I fully agree with the deprecation for DatetimeIndex / TimedeltaIndex!)

[jbrockmendel]

I think we should maybe also reconsider the deprecation

I'm open to this. The part I care about is the TS/TD/DTI/TDI

[aa1371]

+1 for reconsidering the deprecation for Periods.

The behavior is unambiguous, simple and useful. Anecdotally speaking it’s used heavily at my organization, and is one of the reasons that people prefer working with periods.

That said I still think that the new behavior of period1 - period2 returning an offset object is good, and wouldn’t want to see that change.