DEPR: PeriodDtype.freq
State: open

- [ ] closes #xxxx (Replace xxxx with the GitHub issue number)
- [x] [Tests added and passed](https://pandas.pydata.org/pandas-docs/dev/development/contributing_codebase.html#writing-tests) if fixing a bug or adding a new feature
- [ ] All [code checks passed](https://pandas.pydata.org/pandas-docs/dev/development/contributing_codebase.html#pre-commit).
- [ ] Added [type annotations](https://pandas.pydata.org/pandas-docs/dev/development/contributing_codebase.html#type-hints) to new arguments/methods/functions.
- [x] Added an entry in the latest `doc/source/whatsnew/vX.X.X.rst` file if fixing a bug or adding a new feature.

Motivated by #47227.

First (and by a wide margin smallest) of several PRs to deprecate using `freq` to refer to a Period's resolution.  If we go down this route, the other PRs will incrementally do the same for `freq` in the Period constructor, then `freq` as a Period attribute, then the same for PeriodArray/Index.  We shouldn't merge this until we're agreed to do this across the board.

This uses "unit" as the replacement, as that is also what we use for Timestamp/Timedelta.  _But_ while it has roughly the same semantic meaning, Period.unit does return a different type from Timestamp.unit, which might be a reason to use a third term?  Also "unit" is overloaded in to_datetime/to_timedelta.  So while "unit" is the best idea I've had, I'll understand if people want to bikeshed.

cc @mroeschke @jorisvandenbossche 

Labels:
name: Period
description: Period data type
name: Deprecate
description: Functionality to remove in pandas

Comments:
Could do "offset" for the BaseOffset object and "unit" for the string?
> Period.unit does return a different type from Timestamp.unit, which might be a reason to use a third term?

I think this is a good reason to use a different term. I think "offset" or "interval" would be good terms
> I think this is a good reason to use a different term. I think "offset" or "interval" would be good terms

I'd like to avoid "interval" since that already has a meaning in pandas.  offset im happy with.

@jorisvandenbossche are you on board with this plan?
Agreed that we should ideally avoid overloading `unit`.

While I definitely understand the issue for DatetimeIndex vs PeriodIndex `freq` attribute, and that it would be nice that those two cases would have the same meaning, I am not entirely sure that I feel that this is worth deprecating `freq` in all the period-related places (and the code churn for user of it). Certainly if we think the alternative we can come up with is not necessarily a better name (I don't know if that is the case though, `freq` is also not the ideal term) 
(if we do this, IMO we could start with adding the alternatives before actually deprecating)

An alternative would be to add a new method to DTI/PI to avoid the conflict? 

---

On alternative names for Period's `freq`: while "offset" is an obvious choice given that we use this term in our implementation, and therefore I am also used to hearing this term, I am not actually sure this is a very clear term for newcomers? Outside of the context of pandas, I wouldn't directly think about those kind of periods when hearing "offset" (and for "time offset" I would mostly thinking about the +/-HH:SS offset for tz ware timestamps)

Looking at R's lubridate / Java's JodaTime, they have the concept of durations, periods and intervals, where the duration is essentially our timedelta (absolute length of time in seconds), a period is the calendar time length, and interval is span with specific start/stop instant (so like our Interval but specific to timestamps). 
So in that sense, you could say that the `pandas.Period` represents a "period" (day, month, etc) at a certain point in time. But using `pd.Period.period` is probably not going to be less confusing ..? 

Arrow (and some SQL systems) calls the period from JodaTime/lubridate an "interval" , so that could also be an option as mentioned above, but indeed that then conflicts with our `pd.Interval` ..

Assume we would add a pandas extension dtype for Arrow's interval type of data (i.e. what you can now store as `pd.ArrowDtype(pa.month_day_nano_interval())`), how would we call that?

I think I am also coming around to liking `unit` .. ("the unit of time that each period represents") 
While it is annoying that the _type_ is different (str vs object), it does match in meaning. Timestamps just represents an instant point in time and only supports small (fixed-size) units, and periods represents the span for the same units, and then additionally also supports larger (and relative) units. 

But as Brock mentioned in the top post, `unit` is then also already overloaded in `to_datetime`

Yet another idea: "span", indicating the time span of the Period (although I don't know if people's first connotation for "time span" is the absolute vs the relative version .., while here it would of course represent a relative time span)

(sorry, not being very helpful here in coming closer to a decision ..)