Description
Pandas version checks
- I have checked that the issue still exists on the latest versions of the docs on
mainhere
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"