ENH: Add pd.to_period

[gfyoung]

Would return Period or PeriodIndex, analogous to functions like to_datetime and to_timedelta.

xref #5886
xref #14048

cc @sinhrks

[sinhrks]

If we follow the same policy as #8254, DatetimeIndex.to_period should be deprecated in favor of this.

[jorisvandenbossche]

If we follow the same policy as #8254, DatetimeIndex.to_period should be deprecated in favor of this.

IMO that is not needed. The current Index.to_datetime was for parsing non-time values to datetime (wich is the core business of pd.to_datetime). Where DatetimeIndex/Timestamp.to_period and PeriodIndex/Period.to_timestamp are methods for converting between the different time representations.

[TomAugspurger]

The PeriodArray PR is adding a period_array method for constructing a PeriodArray from a list-like of periods.

The only thing that won't handle is scalars. Is that OK? I think that case is already covered by pd.Period(scalar, freq).

[jorisvandenbossche]

A to_period could also have a format argument to be able to parse datetime strings that are out of range for to_datetime.

[TomAugspurger]

@jorisvandenbossche, do you have an example in mind?

In [4]: pd.core.arrays.period_array(['0001-01-01', '0001-01-02'], freq='D')
Out[4]:
<PeriodArray>
['0001-01-01', '0001-01-02']
Length: 2, dtype: period[D]