DOC: pd.Period and pd.period_range should document that they accept datetime, date and pd.Timestamp

[Daverball]

Pandas version checks

• I have checked that the issue still exists on the latest versions of the docs on main here

Location of the documentation

https://pandas.pydata.org/docs/reference/api/pandas.Period.html#pandas-period
https://pandas.pydata.org/docs/reference/api/pandas.period_range.html#pandas-period-range

Documentation problem

Period documents the value argument as str or Period, while period_range will document it as str or period-like. Both just use the Period constructor implemented in cython internally. As per said implementation, it will also accept a datetime, date and pd.Timestamp as can be seen here: https://github.com/pandas-dev/pandas/blob/v2.0.1/pandas/_libs/tslibs/period.pyx#L2626-L2643

Technically it would also accept an integer/float, but this seems more of an edge case, so it might be fine to exclude it from the documentation, it's also not particularly helpful.

Suggested fix for documentation

Extend parameter documentation with additional allowed types. It might also be nice to mention that freq is required if value is not already period-like (i.e. a Period or a string representation of a period)

This issue was opened as a result of discussion on the following pandas-stubs issue: pandas-dev/pandas-stubs#675

[ABizzinotto]

take