DOC: date_range/timedelta_range confusing 3 out of 4 arguments note

[loicdiridollou]

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

Documentation problem

We are trying to improve the type hinting for those two functions in pandas-stubs repo.
Currently the note in both those functions mentions that we should specify 3 out of 4 arguments among start, end, period, freq.
However it seems like the usage (even in the examples) one can specify only 2 of the arguments like start and end. After looking at the code, it seems like freq even if none gets converted to D.

Suggested fix for documentation

I believe we should specify two out of three start, end, periods and never all four together. Rephrasing from three out of four but if freq is omitted then ... would help clarify the goal.

Here would be a possible version:

Of the four parameters start, end, periods, and freq, between two and three must be specified. If freq is omitted,
 the resulting TimedeltaIndex will have periods linearly spaced elements between start and end (closed on both
 sides) using a day increment.

[mazhar996]

@loicdiridollou after reading your conversation with @Dr-Irv in pandas-stubs/pull/1333, my understanding is as follows:

1. Out of the 4 parameters start, end, periods, and freq, maximum 3 can be specified simultaneously.
2. Out of the 3 parameters start, end, and perriods, at least 2 must be specified regardless if freq is specified or not.
3. There is no such restriction on other parameters.
4. If freq is not specified, it defaults to D (calendar day frequency)

If this is correct understanding, I would suggest to change the note to as follows:

Note:
Of the 4 parameters start, end, periods, and freq, maximum 3 can be specified simultaneously. Furthermore, of the 3 parameters start, end, and periods, at least two must be specified. If freq is ommitted, it will default to "D" (calendar day frequency), and the resulting DatetimeIndex will have periods linearly spaced elements between start and end (closed on both sides).

If you agree, then I would like to take this issue as my first issue on github. :-).

regards
Maz

P.S.
What to do with the ValueError raised if start, end, periods, and freq are provided simultaneous?
ValueError: Of the four parameters: start, end, periods, and freq, exactly three must be specified
Should this also not be changed?

[Dr-Irv]

If this is correct understanding, I would suggest to change the note to as follows:

Note: Of the 4 parameters start, end, periods, and freq, maximum 3 can be specified simultaneously. Furthermore, of the 3 parameters start, end, and periods, at least two must be specified. If freq is ommitted, it will default to "D" (calendar day frequency), and the resulting DatetimeIndex will have periods linearly spaced elements between start and end (closed on both sides).

If you agree, then I would like to take this issue as my first issue on github. :-).

Yes, that should work. Make sure you're not duplicating information that is already there on that doc page.

P.S. What to do with the ValueError raised if start, end, periods, and freq are provided simultaneous? ValueError: Of the four parameters: start, end, periods, and freq, exactly three must be specified Should this also not be changed?

If you can modify the code to detect when the error is due to 4 things being specified, versus the issue of start, end and period only having 1 specified, then you can adjust the error message accordingly.

[mazhar996]

take