DOC: Using timedelta as freq for timedelta_range, interval_range, and date_range

[bemoody]

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/dev/reference/api/pandas.timedelta_range.html
https://pandas.pydata.org/docs/dev/reference/api/pandas.interval_range.html
https://pandas.pydata.org/docs/dev/reference/api/pandas.date_range.html
https://pandas.pydata.org/docs/dev/reference/api/pandas.bdate_range.html

Documentation problem

The documentation of timedelta_range indicates that the freq argument must be a "str or DateOffset". However, in actuality the function will also accept a pandas.Timedelta object, a datetime.timedelta object, or maybe other things (the start and end arguments are "timedelta-like"; I'm not sure what that means.)

For example, pd.timedelta_range(datetime.timedelta(0), datetime.timedelta(seconds=60), freq=datetime.timedelta(seconds=1)) produces a range of 0 to 60 seconds by one-second steps.

The functions timedelta_range, interval_range, date_range, and bdate_range all appear to work similarly. However, the current documentation is inconsistent:

• timedelta_range: "str or DateOffset, default ‘D’"
• interval_range: "numeric, str, datetime.timedelta, or DateOffset, default None"
• date_range: "str, datetime.timedelta, or DateOffset, default ‘D’"
• bdate_range: "str, Timedelta, datetime.timedelta, or DateOffset, default ‘B’"

All four of these functions will in fact accept either a datetime.timedelta object or a Timedelta object.

Related issues:
#48460
#48631
pandas-dev/pandas-stubs#600

Suggested fix for documentation

Following the example of bdate_range, the freq parameter should be documented:

• for timedelta_range: "str, Timedelta, datetime.timedelta, or DateOffset, default ‘D’"
• for date_range: "str, Timedelta, datetime.timedelta, or DateOffset, default ‘D’"
• for interval_range: "numeric, str, Timedelta, datetime.timedelta, or DateOffset, default None"

[allisonkwan]

take