Skip to content

API: date_range, timedelta_range infer unit from start/end/freq #63146

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 13 commits into
base: main
Choose a base branch
from
+635 −412
Open

API: date_range, timedelta_range infer unit from start/end/freq #63146

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
908a88e
API: date_range, timedelta_range infer unit from start/end/freq
jbrockmendel Nov 18, 2025
257f410
Merge branch 'main' into api-date_range
jbrockmendel Nov 19, 2025
df7376e
update expecteds
jbrockmendel Nov 19, 2025
6fae9cc
mypy fixup
jbrockmendel Nov 20, 2025
8863e26
stub fixup
jbrockmendel Nov 20, 2025
3d8c0b6
stubtest fixup
jbrockmendel Nov 20, 2025
3b2cd0d
stubtest fixup
jbrockmendel Nov 20, 2025
4210a9e
Merge branch 'main' into api-date_range
jbrockmendel Nov 20, 2025
affa6f0
update gcs test
jbrockmendel Nov 20, 2025
964c908
update slow test
jbrockmendel Nov 21, 2025
6dfc65d
update xarray test
jbrockmendel Nov 21, 2025
873ea3a
pyright fixup
jbrockmendel Nov 21, 2025
a142fbf
update doctests
jbrockmendel Nov 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions doc/source/whatsnew/v3.0.0.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -745,6 +745,7 @@ Other API changes
the dtype of the resulting Index (:issue:`60797`)
- :class:`IncompatibleFrequency` now subclasses ``TypeError`` instead of ``ValueError``. As a result, joins with mismatched frequencies now cast to object like other non-comparable joins, and arithmetic with indexes with mismatched frequencies align (:issue:`55782`)
- :class:`Series` "flex" methods like :meth:`Series.add` no longer allow passing a :class:`DataFrame` for ``other``; use the DataFrame reversed method instead (:issue:`46179`)
- :func:`date_range` and :func:`timedelta_range` no longer default to ``unit="ns"``, instead will infer a unit from the ``start``, ``end``, and ``freq`` parameters. Explicitly specify a desired ``unit`` to override these (:issue:`59031`)
- :meth:`CategoricalIndex.append` no longer attempts to cast different-dtype indexes to the caller's dtype (:issue:`41626`)
- :meth:`ExtensionDtype.construct_array_type` is now a regular method instead of a ``classmethod`` (:issue:`58663`)
- Comparison operations between :class:`Index` and :class:`Series` now consistently return :class:`Series` regardless of which object is on the left or right (:issue:`36759`)
Expand Down
14 changes: 7 additions & 7 deletions pandas/core/arrays/datetimelike.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1900,21 +1900,21 @@ def strftime(self, date_format: str) -> npt.NDArray[np.object_]:
>>> rng
DatetimeIndex(['2018-01-01 11:59:00', '2018-01-01 12:00:00',
'2018-01-01 12:01:00'],
dtype='datetime64[ns]', freq='min')
dtype='datetime64[us]', freq='min')
"""

_round_example = """>>> rng.round('h')
DatetimeIndex(['2018-01-01 12:00:00', '2018-01-01 12:00:00',
'2018-01-01 12:00:00'],
dtype='datetime64[ns]', freq=None)
dtype='datetime64[us]', freq=None)
**Series**
>>> pd.Series(rng).dt.round("h")
0 2018-01-01 12:00:00
1 2018-01-01 12:00:00
2 2018-01-01 12:00:00
dtype: datetime64[ns]
dtype: datetime64[us]
When rounding near a daylight savings time transition, use ``ambiguous`` or
``nonexistent`` to control how the timestamp should be re-localized.
Expand All @@ -1933,15 +1933,15 @@ def strftime(self, date_format: str) -> npt.NDArray[np.object_]:
_floor_example = """>>> rng.floor('h')
DatetimeIndex(['2018-01-01 11:00:00', '2018-01-01 12:00:00',
'2018-01-01 12:00:00'],
dtype='datetime64[ns]', freq=None)
dtype='datetime64[us]', freq=None)
**Series**
>>> pd.Series(rng).dt.floor("h")
0 2018-01-01 11:00:00
1 2018-01-01 12:00:00
2 2018-01-01 12:00:00
dtype: datetime64[ns]
dtype: datetime64[us]
When rounding near a daylight savings time transition, use ``ambiguous`` or
``nonexistent`` to control how the timestamp should be re-localized.
Expand All @@ -1960,15 +1960,15 @@ def strftime(self, date_format: str) -> npt.NDArray[np.object_]:
_ceil_example = """>>> rng.ceil('h')
DatetimeIndex(['2018-01-01 12:00:00', '2018-01-01 12:00:00',
'2018-01-01 13:00:00'],
dtype='datetime64[ns]', freq=None)
dtype='datetime64[us]', freq=None)
**Series**
>>> pd.Series(rng).dt.ceil("h")
0 2018-01-01 12:00:00
1 2018-01-01 12:00:00
2 2018-01-01 13:00:00
dtype: datetime64[ns]
dtype: datetime64[us]
When rounding near a daylight savings time transition, use ``ambiguous`` or
``nonexistent`` to control how the timestamp should be re-localized.
Expand Down
66 changes: 33 additions & 33 deletions pandas/core/arrays/datetimes.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -912,13 +912,13 @@ def tz_convert(self, tz) -> Self:
DatetimeIndex(['2014-08-01 09:00:00+02:00',
'2014-08-01 10:00:00+02:00',
'2014-08-01 11:00:00+02:00'],
dtype='datetime64[ns, Europe/Berlin]', freq='h')
dtype='datetime64[us, Europe/Berlin]', freq='h')
>>> dti.tz_convert(None)
DatetimeIndex(['2014-08-01 07:00:00',
'2014-08-01 08:00:00',
'2014-08-01 09:00:00'],
dtype='datetime64[ns]', freq='h')
dtype='datetime64[us]', freq='h')
""" # noqa: E501
tz = timezones.maybe_get_tz(tz)

Expand Down Expand Up @@ -1009,7 +1009,7 @@ def tz_localize(
>>> tz_naive
DatetimeIndex(['2018-03-01 09:00:00', '2018-03-02 09:00:00',
'2018-03-03 09:00:00'],
dtype='datetime64[ns]', freq='D')
dtype='datetime64[us]', freq='D')
Localize DatetimeIndex in US/Eastern time zone:
Expand All @@ -1018,15 +1018,15 @@ def tz_localize(
DatetimeIndex(['2018-03-01 09:00:00-05:00',
'2018-03-02 09:00:00-05:00',
'2018-03-03 09:00:00-05:00'],
dtype='datetime64[ns, US/Eastern]', freq=None)
dtype='datetime64[us, US/Eastern]', freq=None)
With the ``tz=None``, we can remove the time zone information
while keeping the local time (not converted to UTC):
>>> tz_aware.tz_localize(None)
DatetimeIndex(['2018-03-01 09:00:00', '2018-03-02 09:00:00',
'2018-03-03 09:00:00'],
dtype='datetime64[ns]', freq=None)
dtype='datetime64[us]', freq=None)
Be careful with DST changes. When there is sequential data, pandas can
infer the DST time:
Expand Down Expand Up @@ -1179,12 +1179,12 @@ def normalize(self) -> Self:
DatetimeIndex(['2014-08-01 10:00:00+05:30',
'2014-08-01 11:00:00+05:30',
'2014-08-01 12:00:00+05:30'],
dtype='datetime64[ns, Asia/Calcutta]', freq='h')
dtype='datetime64[us, Asia/Calcutta]', freq='h')
>>> idx.normalize()
DatetimeIndex(['2014-08-01 00:00:00+05:30',
'2014-08-01 00:00:00+05:30',
'2014-08-01 00:00:00+05:30'],
dtype='datetime64[ns, Asia/Calcutta]', freq=None)
dtype='datetime64[us, Asia/Calcutta]', freq=None)
"""
new_values = normalize_i8_timestamps(self.asi8, self.tz, reso=self._creso)
dt64_values = new_values.view(self._ndarray.dtype)
Expand Down Expand Up @@ -1308,7 +1308,7 @@ def month_name(self, locale=None) -> npt.NDArray[np.object_]:
0 2018-01-31
1 2018-02-28
2 2018-03-31
dtype: datetime64[ns]
dtype: datetime64[us]
>>> s.dt.month_name()
0 January
1 February
Expand All @@ -1318,7 +1318,7 @@ def month_name(self, locale=None) -> npt.NDArray[np.object_]:
>>> idx = pd.date_range(start="2018-01", freq="ME", periods=3)
>>> idx
DatetimeIndex(['2018-01-31', '2018-02-28', '2018-03-31'],
dtype='datetime64[ns]', freq='ME')
dtype='datetime64[us]', freq='ME')
>>> idx.month_name()
Index(['January', 'February', 'March'], dtype='str')
Expand All @@ -1329,7 +1329,7 @@ def month_name(self, locale=None) -> npt.NDArray[np.object_]:
>>> idx = pd.date_range(start="2018-01", freq="ME", periods=3)
>>> idx
DatetimeIndex(['2018-01-31', '2018-02-28', '2018-03-31'],
dtype='datetime64[ns]', freq='ME')
dtype='datetime64[us]', freq='ME')
>>> idx.month_name(locale="pt_BR.utf8") # doctest: +SKIP
Index(['Janeiro', 'Fevereiro', 'Março'], dtype='str')
"""
Expand Down Expand Up @@ -1376,7 +1376,7 @@ def day_name(self, locale=None) -> npt.NDArray[np.object_]:
0 2018-01-01
1 2018-01-02
2 2018-01-03
dtype: datetime64[ns]
dtype: datetime64[us]
>>> s.dt.day_name()
0 Monday
1 Tuesday
Expand All @@ -1386,7 +1386,7 @@ def day_name(self, locale=None) -> npt.NDArray[np.object_]:
>>> idx = pd.date_range(start="2018-01-01", freq="D", periods=3)
>>> idx
DatetimeIndex(['2018-01-01', '2018-01-02', '2018-01-03'],
dtype='datetime64[ns]', freq='D')
dtype='datetime64[us]', freq='D')
>>> idx.day_name()
Index(['Monday', 'Tuesday', 'Wednesday'], dtype='str')
Expand All @@ -1397,7 +1397,7 @@ def day_name(self, locale=None) -> npt.NDArray[np.object_]:
>>> idx = pd.date_range(start="2018-01-01", freq="D", periods=3)
>>> idx
DatetimeIndex(['2018-01-01', '2018-01-02', '2018-01-03'],
dtype='datetime64[ns]', freq='D')
dtype='datetime64[us]', freq='D')
>>> idx.day_name(locale="pt_BR.utf8") # doctest: +SKIP
Index(['Segunda', 'Terça', 'Quarta'], dtype='str')
"""
Expand Down Expand Up @@ -1610,7 +1610,7 @@ def isocalendar(self) -> DataFrame:
0 2000-12-31
1 2001-12-31
2 2002-12-31
dtype: datetime64[ns]
dtype: datetime64[us]
>>> datetime_series.dt.year
0 2000
1 2001
Expand Down Expand Up @@ -1638,7 +1638,7 @@ def isocalendar(self) -> DataFrame:
0 2000-01-31
1 2000-02-29
2 2000-03-31
dtype: datetime64[ns]
dtype: datetime64[us]
>>> datetime_series.dt.month
0 1
1 2
Expand Down Expand Up @@ -1667,7 +1667,7 @@ def isocalendar(self) -> DataFrame:
0 2000-01-01
1 2000-01-02
2 2000-01-03
dtype: datetime64[ns]
dtype: datetime64[us]
>>> datetime_series.dt.day
0 1
1 2
Expand Down Expand Up @@ -1696,7 +1696,7 @@ def isocalendar(self) -> DataFrame:
0 2000-01-01 00:00:00
1 2000-01-01 01:00:00
2 2000-01-01 02:00:00
dtype: datetime64[ns]
dtype: datetime64[us]
>>> datetime_series.dt.hour
0 0
1 1
Expand Down Expand Up @@ -1724,7 +1724,7 @@ def isocalendar(self) -> DataFrame:
0 2000-01-01 00:00:00
1 2000-01-01 00:01:00
2 2000-01-01 00:02:00
dtype: datetime64[ns]
dtype: datetime64[us]
>>> datetime_series.dt.minute
0 0
1 1
Expand Down Expand Up @@ -1753,7 +1753,7 @@ def isocalendar(self) -> DataFrame:
0 2000-01-01 00:00:00
1 2000-01-01 00:00:01
2 2000-01-01 00:00:02
dtype: datetime64[ns]
dtype: datetime64[us]
>>> datetime_series.dt.second
0 0
1 1
Expand Down Expand Up @@ -1781,7 +1781,7 @@ def isocalendar(self) -> DataFrame:
0 2000-01-01 00:00:00.000000
1 2000-01-01 00:00:00.000001
2 2000-01-01 00:00:00.000002
dtype: datetime64[ns]
dtype: datetime64[us]
>>> datetime_series.dt.microsecond
0 0
1 1
Expand Down Expand Up @@ -1809,7 +1809,7 @@ def isocalendar(self) -> DataFrame:
0 2000-01-01 00:00:00.000000000
1 2000-01-01 00:00:00.000000001
2 2000-01-01 00:00:00.000000002
dtype: datetime64[ns]
dtype: datetime64[us]
>>> datetime_series.dt.nanosecond
0 0
1 1
Expand Down Expand Up @@ -1981,7 +1981,7 @@ def isocalendar(self) -> DataFrame:
0 2018-02-27
1 2018-02-28
2 2018-03-01
dtype: datetime64[ns]
dtype: datetime64[us]
>>> s.dt.is_month_start
0 False
1 False
Expand Down Expand Up @@ -2043,7 +2043,7 @@ def isocalendar(self) -> DataFrame:
>>> idx = pd.date_range('2017-03-30', periods=4)
>>> idx
DatetimeIndex(['2017-03-30', '2017-03-31', '2017-04-01', '2017-04-02'],
dtype='datetime64[ns]', freq='D')
dtype='datetime64[us]', freq='D')
>>> idx.is_quarter_start
array([False, False, True, False])
Expand Down Expand Up @@ -2085,7 +2085,7 @@ def isocalendar(self) -> DataFrame:
>>> idx = pd.date_range('2017-03-30', periods=4)
>>> idx
DatetimeIndex(['2017-03-30', '2017-03-31', '2017-04-01', '2017-04-02'],
dtype='datetime64[ns]', freq='D')
dtype='datetime64[us]', freq='D')
>>> idx.is_quarter_end
array([False, True, False, False])
Expand Down Expand Up @@ -2118,7 +2118,7 @@ def isocalendar(self) -> DataFrame:
0 2017-12-30
1 2017-12-31
2 2018-01-01
dtype: datetime64[ns]
dtype: datetime64[us]
>>> dates.dt.is_year_start
0 False
Expand All @@ -2129,7 +2129,7 @@ def isocalendar(self) -> DataFrame:
>>> idx = pd.date_range("2017-12-30", periods=3)
>>> idx
DatetimeIndex(['2017-12-30', '2017-12-31', '2018-01-01'],
dtype='datetime64[ns]', freq='D')
dtype='datetime64[us]', freq='D')
>>> idx.is_year_start
array([False, False, True])
Expand All @@ -2143,7 +2143,7 @@ def isocalendar(self) -> DataFrame:
1 2022-01-03
2 2023-01-02
3 2024-01-01
dtype: datetime64[ns]
dtype: datetime64[us]
>>> dates.dt.is_year_start
0 True
Expand All @@ -2155,7 +2155,7 @@ def isocalendar(self) -> DataFrame:
>>> idx = pd.date_range("2020-10-30", periods=4, freq="BYS")
>>> idx
DatetimeIndex(['2021-01-01', '2022-01-03', '2023-01-02', '2024-01-01'],
dtype='datetime64[ns]', freq='BYS-JAN')
dtype='datetime64[us]', freq='BYS-JAN')
>>> idx.is_year_start
array([ True, True, True, True])
Expand Down Expand Up @@ -2188,7 +2188,7 @@ def isocalendar(self) -> DataFrame:
0 2017-12-30
1 2017-12-31
2 2018-01-01
dtype: datetime64[ns]
dtype: datetime64[us]
>>> dates.dt.is_year_end
0 False
Expand All @@ -2199,7 +2199,7 @@ def isocalendar(self) -> DataFrame:
>>> idx = pd.date_range("2017-12-30", periods=3)
>>> idx
DatetimeIndex(['2017-12-30', '2017-12-31', '2018-01-01'],
dtype='datetime64[ns]', freq='D')
dtype='datetime64[us]', freq='D')
>>> idx.is_year_end
array([False, True, False])
Expand Down Expand Up @@ -2236,7 +2236,7 @@ def isocalendar(self) -> DataFrame:
>>> idx = pd.date_range("2012-01-01", "2015-01-01", freq="YE")
>>> idx
DatetimeIndex(['2012-12-31', '2013-12-31', '2014-12-31'],
dtype='datetime64[ns]', freq='YE-DEC')
dtype='datetime64[us]', freq='YE-DEC')
>>> idx.is_leap_year
array([ True, False, False])
Expand All @@ -2245,7 +2245,7 @@ def isocalendar(self) -> DataFrame:
0 2012-12-31
1 2013-12-31
2 2014-12-31
dtype: datetime64[ns]
dtype: datetime64[us]
>>> dates_series.dt.is_leap_year
0 True
1 False
Expand Down Expand Up @@ -2379,7 +2379,7 @@ def std(
>>> idx = pd.date_range("2001-01-01 00:00", periods=3)
>>> idx
DatetimeIndex(['2001-01-01', '2001-01-02', '2001-01-03'],
dtype='datetime64[ns]', freq='D')
dtype='datetime64[us]', freq='D')
>>> idx.std()
Timedelta('1 days 00:00:00')
"""
Expand Down
Loading
Loading