GH1327 Add overloead for date_range and timedelta_range #1333

loicdiridollou · 2025-08-20T00:57:03Z

Closes Rewrite timedelta_range to use overloads in core/indexes/timedelta #1327
Tests added: Please use assert_type() to assert the type of any return value

tests/test_styler.py

loicdiridollou · 2025-08-20T00:58:08Z

tests/test_timefuncs.py

+        day1 = pd.Timedelta(1, unit="D")
+        day10 = pd.Timedelta(10, unit="D")
+        pd.timedelta_range(
+            day1, day10, periods=10, freq="D"  # type: ignore[call-overload]  # pyright: ignore[reportArgumentType]


Passing all four should be banned

Dr-Irv

You've added new overloads, but I don't see the benefit of them, without tests that don't work with the current stubs, but would work with your changes.

Dr-Irv · 2025-08-20T13:44:22Z

pandas-stubs/core/indexes/datetimes.pyi

+def date_range(
+    end: str | DateAndDatetimeLike,
+    periods: int,
+    freq: str | timedelta | Timedelta | BaseOffset | None = None,
+    tz: TimeZones = None,
+    normalize: bool = False,
+    name: Hashable | None = None,
+    inclusive: IntervalClosedType = "both",
+    unit: TimeUnit | None = None,
+) -> DatetimeIndex: ...
+@overload
+def date_range(
+    start: str | DateAndDatetimeLike,
+    periods: int,
+    freq: str | timedelta | Timedelta | BaseOffset | None = None,


These would only work if the arguments are keyword arguments, so I think you need to put an asterisk (*) right after the opening parenthesis.

Dr-Irv · 2025-08-20T13:45:40Z

pandas-stubs/core/indexes/datetimes.pyi

+def date_range(
+    start: str | DateAndDatetimeLike | None,
+    end: str | DateAndDatetimeLike | None,
+    freq: str | timedelta | Timedelta | BaseOffset | None = None,
+    tz: TimeZones = None,
+    normalize: bool = False,
+    name: Hashable | None = None,
+    inclusive: IntervalClosedType = "both",
+    unit: TimeUnit | None = None,
+) -> DatetimeIndex: ...
+@overload
 def date_range(
-    start: str | DateAndDatetimeLike | None = None,
-    end: str | DateAndDatetimeLike | None = None,
-    periods: int | None = None,
-    freq: str | timedelta | Timedelta | BaseOffset = "D",
+    start: str | DateAndDatetimeLike,
+    end: str | DateAndDatetimeLike,
+    periods: int,
+    freq: None = None,
    tz: TimeZones = None,


I don't see the point here of having separate overloads. Also, you need to put back the default values.

So the original goal was to only allow three out of the four values among start, end, periods and freq according to the docs.
Although the freq argument is often not passed.

Dr-Irv · 2025-08-20T13:46:30Z

pandas-stubs/core/indexes/timedeltas.pyi

+    start: TimedeltaConvertibleTypes,
+    end: TimedeltaConvertibleTypes,
+    periods: int,
+    freq: None = None,
+    name: Hashable | None = None,
+    closed: Literal["left", "right"] | None = None,
+    *,
+    unit: None | str = ...,
+) -> TimedeltaIndex: ...
+@overload
+def timedelta_range(
+    start: TimedeltaConvertibleTypes,
+    periods: int,
+    freq: None = None,


I think you're going to have a similar issue in terms of mixing positional vs. keyword arguments.

This is now fixed.

tests/test_styler.py

loicdiridollou · 2025-08-20T20:26:10Z

I have added two tests for Type invalid because this is what we want to check (that passing four arguments is not allowed).

Dr-Irv · 2025-08-20T21:03:46Z

pandas-stubs/core/indexes/datetimes.pyi

+    end: str | DateAndDatetimeLike = ...,
+    periods: int = ...,


I think this would allow pd.date_range() to be accepted.

The error message is " Of the four parameters: start, end, periods, and freq, exactly three must be specified".

So if you want this to work, you have to have overloads where 3 are required. You can't have = ... on any of them (or default values either), because that means the argument is optional.

The point where I am a bit unsure is that most of the usage I have seen it just about passing start and end, freq is often left alone so the usage does not reflect the docs.
Should we force the user to use three out of the four or allow only two?

So I think the docs and error message are a bit misleading.

You'll need to do a test to determine when 2 are allowed. I think the rule is as follows:

Whether or not freq is specified, you need at least 2 out of the 3 of start, end, periods

If I look at the docs, they don't even use three exactly, when looking at the code they are using the fact that freq defaults to None but is then replaced by D for day.
https://pandas.pydata.org/docs/dev/reference/api/pandas.timedelta_range.html#pandas.timedelta_range

See https://github.com/pandas-dev/pandas/blob/78ec27668163808b3488da6ed2c64d0b8e9bfbc8/pandas/core/indexes/timedeltas.py#L330-L331 for the code where they change freq=None to freq="D"
Should we force the user to do 3 args even if the docs example only uses 2.
Happy to open a PR in the pandas repo to ask for clarification.

Sorry took a bit of time to find all the docs and you had answered before.
Let me setup a quick test to validate that we need two out of three of start, end, and periods.

Seems like the freq is indeed the argument that does not need to be passed (it is also the last one in the order).
I think the correct way to type hint is like you said forcing 2 out of the 3 with freq being an str | None = ... without the need to be passed when you pass two other. I have also tried passing four and that works as long as one of the three is None (yet it would be a strange use case of passing None since it is a default).

>>> pd.date_range("2023-04-05", "2023-04-07", freq="D") DatetimeIndex(['2023-04-05', '2023-04-06', '2023-04-07'], dtype='datetime64[ns]', freq='D') >>> pd.date_range("2023-04-05", "2023-04-07") DatetimeIndex(['2023-04-05', '2023-04-06', '2023-04-07'], dtype='datetime64[ns]', freq='D')

pandas-dev/pandas#62161

I have asked for clarifications.

I have read and reread the docs, it is a bit confusing at first glance but I will add all the tests for it.

Dr-Irv · 2025-08-20T21:04:50Z

pandas-stubs/core/indexes/timedeltas.pyi

+    start: TimedeltaConvertibleTypes = ...,
+    end: TimedeltaConvertibleTypes = ...,
+    periods: int = ...,


same issue here as with date_range()

Dr-Irv · 2025-08-20T21:05:45Z

tests/test_timefuncs.py

+    if TYPE_CHECKING_INVALID_USAGE:
+        day1 = pd.Timedelta(1, unit="D")
+        day10 = pd.Timedelta(10, unit="D")
+        pd.timedelta_range(
+            day1, day10, 10, "D"  # type: ignore[call-overload]  # pyright: ignore[reportArgumentType]
+        )


should add checks where only 0, 1 or 2 of the 3 arguments are specified, as that should fail as well.

Dr-Irv · 2025-08-20T21:06:08Z

tests/test_timefuncs.py

+    if TYPE_CHECKING_INVALID_USAGE:
+        day1 = pd.Timestamp("2023-04-03")
+        day10 = pd.Timedelta("2023-04-08")
+        pd.date_range(
+            day1, day10, 10, "D"  # type: ignore[call-overload]  # pyright: ignore[reportCallIssue]
+        )


same comment - need to check that 0, 1 or 2 arguments specified causes a failure.

loicdiridollou · 2025-08-21T22:36:35Z

Rewrote the tests and the overloads properly with 2 (when omitting freq), 3 and forbidding 1 and 4 arguments among start, end, periods and freq.

Dr-Irv

thanks @loicdiridollou

GH1327 Add overloead for date_range and timedelta_range

2a99f70

loicdiridollou commented Aug 20, 2025

View reviewed changes

tests/test_styler.py Show resolved Hide resolved

loicdiridollou commented Aug 20, 2025

View reviewed changes

GH1327 Fix CI

f26b710

Dr-Irv requested changes Aug 20, 2025

View reviewed changes

loicdiridollou added 2 commits August 20, 2025 16:24

GH1327 PR feedback

584e288

Merge branch 'main' into gh1327_date_timedelta_range

9bf345a

Dr-Irv requested changes Aug 20, 2025

View reviewed changes

loicdiridollou added 2 commits August 21, 2025 17:44

GH1327 Revert changes to start clean

56be8d4

GH1327 PR Feedback

fc35578

Dr-Irv approved these changes Aug 22, 2025

View reviewed changes

Dr-Irv merged commit e799ec1 into pandas-dev:main Aug 22, 2025
13 checks passed

mazhar996 mentioned this pull request Aug 24, 2025

DOC: date_range/timedelta_range confusing 3 out of 4 arguments note pandas-dev/pandas#62161

Open

1 task

Uh oh!

GH1327 Add overloead for date_range and timedelta_range #1333

GH1327 Add overloead for date_range and timedelta_range #1333

Uh oh!

Conversation

loicdiridollou commented Aug 20, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Dr-Irv left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

loicdiridollou commented Aug 20, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

loicdiridollou commented Aug 21, 2025

Uh oh!

Dr-Irv left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!