Skip to content

Commit 0e8ff31

Browse files
mroeschkemroeschke
authored
DOC: Clarify DST rounding behavior in Timestamp/DatetimeIndex (#44357)
1 parent 2cc1227 commit 0e8ff31

File tree

3 files changed

+154
-0
lines changed

3 files changed

+154
-0
lines changed

‎pandas/_libs/tslibs/nattype.pyx

+54
Original file line numberDiff line numberDiff line change
@@ -792,6 +792,13 @@ timedelta}, default 'raise'
792792
------
793793
ValueError if the freq cannot be converted
794794
795+
Notes
796+
-----
797+
If the Timestamp has a timezone, rounding will take place relative to the
798+
local ("wall") time and re-localized to the same timezone. When rounding
799+
near daylight savings time, use ``nonexistent`` and ``ambiguous`` to
800+
control the re-localization behavior.
801+
795802
Examples
796803
--------
797804
Create a timestamp object:
@@ -826,6 +833,17 @@ timedelta}, default 'raise'
826833
827834
>>> pd.NaT.round()
828835
NaT
836+
837+
When rounding near a daylight savings time transition, use ``ambiguous`` or
838+
``nonexistent`` to control how the timestamp should be re-localized.
839+
840+
>>> ts_tz = pd.Timestamp("2021-10-31 01:30:00").tz_localize("Europe/Amsterdam")
841+
842+
>>> ts_tz.round("H", ambiguous=False)
843+
Timestamp('2021-10-31 02:00:00+0100', tz='Europe/Amsterdam')
844+
845+
>>> ts_tz.round("H", ambiguous=True)
846+
Timestamp('2021-10-31 02:00:00+0200', tz='Europe/Amsterdam')
829847
""",
830848
)
831849
floor = _make_nat_func(
@@ -863,6 +881,13 @@ timedelta}, default 'raise'
863881
------
864882
ValueError if the freq cannot be converted.
865883
884+
Notes
885+
-----
886+
If the Timestamp has a timezone, flooring will take place relative to the
887+
local ("wall") time and re-localized to the same timezone. When flooring
888+
near daylight savings time, use ``nonexistent`` and ``ambiguous`` to
889+
control the re-localization behavior.
890+
866891
Examples
867892
--------
868893
Create a timestamp object:
@@ -897,6 +922,17 @@ timedelta}, default 'raise'
897922
898923
>>> pd.NaT.floor()
899924
NaT
925+
926+
When rounding near a daylight savings time transition, use ``ambiguous`` or
927+
``nonexistent`` to control how the timestamp should be re-localized.
928+
929+
>>> ts_tz = pd.Timestamp("2021-10-31 03:30:00").tz_localize("Europe/Amsterdam")
930+
931+
>>> ts_tz.floor("2H", ambiguous=False)
932+
Timestamp('2021-10-31 02:00:00+0100', tz='Europe/Amsterdam')
933+
934+
>>> ts_tz.floor("2H", ambiguous=True)
935+
Timestamp('2021-10-31 02:00:00+0200', tz='Europe/Amsterdam')
900936
""",
901937
)
902938
ceil = _make_nat_func(
@@ -934,6 +970,13 @@ timedelta}, default 'raise'
934970
------
935971
ValueError if the freq cannot be converted.
936972
973+
Notes
974+
-----
975+
If the Timestamp has a timezone, ceiling will take place relative to the
976+
local ("wall") time and re-localized to the same timezone. When ceiling
977+
near daylight savings time, use ``nonexistent`` and ``ambiguous`` to
978+
control the re-localization behavior.
979+
937980
Examples
938981
--------
939982
Create a timestamp object:
@@ -968,6 +1011,17 @@ timedelta}, default 'raise'
9681011
9691012
>>> pd.NaT.ceil()
9701013
NaT
1014+
1015+
When rounding near a daylight savings time transition, use ``ambiguous`` or
1016+
``nonexistent`` to control how the timestamp should be re-localized.
1017+
1018+
>>> ts_tz = pd.Timestamp("2021-10-31 01:30:00").tz_localize("Europe/Amsterdam")
1019+
1020+
>>> ts_tz.ceil("H", ambiguous=False)
1021+
Timestamp('2021-10-31 02:00:00+0100', tz='Europe/Amsterdam')
1022+
1023+
>>> ts_tz.ceil("H", ambiguous=True)
1024+
Timestamp('2021-10-31 02:00:00+0200', tz='Europe/Amsterdam')
9711025
""",
9721026
)
9731027

‎pandas/_libs/tslibs/timestamps.pyx

+54
Original file line numberDiff line numberDiff line change
@@ -1462,6 +1462,13 @@ timedelta}, default 'raise'
14621462
------
14631463
ValueError if the freq cannot be converted
14641464
1465+
Notes
1466+
-----
1467+
If the Timestamp has a timezone, rounding will take place relative to the
1468+
local ("wall") time and re-localized to the same timezone. When rounding
1469+
near daylight savings time, use ``nonexistent`` and ``ambiguous`` to
1470+
control the re-localization behavior.
1471+
14651472
Examples
14661473
--------
14671474
Create a timestamp object:
@@ -1496,6 +1503,17 @@ timedelta}, default 'raise'
14961503
14971504
>>> pd.NaT.round()
14981505
NaT
1506+
1507+
When rounding near a daylight savings time transition, use ``ambiguous`` or
1508+
``nonexistent`` to control how the timestamp should be re-localized.
1509+
1510+
>>> ts_tz = pd.Timestamp("2021-10-31 01:30:00").tz_localize("Europe/Amsterdam")
1511+
1512+
>>> ts_tz.round("H", ambiguous=False)
1513+
Timestamp('2021-10-31 02:00:00+0100', tz='Europe/Amsterdam')
1514+
1515+
>>> ts_tz.round("H", ambiguous=True)
1516+
Timestamp('2021-10-31 02:00:00+0200', tz='Europe/Amsterdam')
14991517
"""
15001518
return self._round(
15011519
freq, RoundTo.NEAREST_HALF_EVEN, ambiguous, nonexistent
@@ -1535,6 +1553,13 @@ timedelta}, default 'raise'
15351553
------
15361554
ValueError if the freq cannot be converted.
15371555
1556+
Notes
1557+
-----
1558+
If the Timestamp has a timezone, flooring will take place relative to the
1559+
local ("wall") time and re-localized to the same timezone. When flooring
1560+
near daylight savings time, use ``nonexistent`` and ``ambiguous`` to
1561+
control the re-localization behavior.
1562+
15381563
Examples
15391564
--------
15401565
Create a timestamp object:
@@ -1569,6 +1594,17 @@ timedelta}, default 'raise'
15691594
15701595
>>> pd.NaT.floor()
15711596
NaT
1597+
1598+
When rounding near a daylight savings time transition, use ``ambiguous`` or
1599+
``nonexistent`` to control how the timestamp should be re-localized.
1600+
1601+
>>> ts_tz = pd.Timestamp("2021-10-31 03:30:00").tz_localize("Europe/Amsterdam")
1602+
1603+
>>> ts_tz.floor("2H", ambiguous=False)
1604+
Timestamp('2021-10-31 02:00:00+0100', tz='Europe/Amsterdam')
1605+
1606+
>>> ts_tz.floor("2H", ambiguous=True)
1607+
Timestamp('2021-10-31 02:00:00+0200', tz='Europe/Amsterdam')
15721608
"""
15731609
return self._round(freq, RoundTo.MINUS_INFTY, ambiguous, nonexistent)
15741610

@@ -1606,6 +1642,13 @@ timedelta}, default 'raise'
16061642
------
16071643
ValueError if the freq cannot be converted.
16081644
1645+
Notes
1646+
-----
1647+
If the Timestamp has a timezone, ceiling will take place relative to the
1648+
local ("wall") time and re-localized to the same timezone. When ceiling
1649+
near daylight savings time, use ``nonexistent`` and ``ambiguous`` to
1650+
control the re-localization behavior.
1651+
16091652
Examples
16101653
--------
16111654
Create a timestamp object:
@@ -1640,6 +1683,17 @@ timedelta}, default 'raise'
16401683
16411684
>>> pd.NaT.ceil()
16421685
NaT
1686+
1687+
When rounding near a daylight savings time transition, use ``ambiguous`` or
1688+
``nonexistent`` to control how the timestamp should be re-localized.
1689+
1690+
>>> ts_tz = pd.Timestamp("2021-10-31 01:30:00").tz_localize("Europe/Amsterdam")
1691+
1692+
>>> ts_tz.ceil("H", ambiguous=False)
1693+
Timestamp('2021-10-31 02:00:00+0100', tz='Europe/Amsterdam')
1694+
1695+
>>> ts_tz.ceil("H", ambiguous=True)
1696+
Timestamp('2021-10-31 02:00:00+0200', tz='Europe/Amsterdam')
16431697
"""
16441698
return self._round(freq, RoundTo.PLUS_INFTY, ambiguous, nonexistent)
16451699

‎pandas/core/arrays/datetimelike.py

+46
Original file line numberDiff line numberDiff line change
@@ -1636,6 +1636,13 @@ def strftime(self, date_format: str) -> npt.NDArray[np.object_]:
16361636
------
16371637
ValueError if the `freq` cannot be converted.
16381638
1639+
Notes
1640+
-----
1641+
If the timestamps have a timezone, {op}ing will take place relative to the
1642+
local ("wall") time and re-localized to the same timezone. When {op}ing
1643+
near daylight savings time, use ``nonexistent`` and ``ambiguous`` to
1644+
control the re-localization behavior.
1645+
16391646
Examples
16401647
--------
16411648
**DatetimeIndex**
@@ -1659,6 +1666,19 @@ def strftime(self, date_format: str) -> npt.NDArray[np.object_]:
16591666
1 2018-01-01 12:00:00
16601667
2 2018-01-01 12:00:00
16611668
dtype: datetime64[ns]
1669+
1670+
When rounding near a daylight savings time transition, use ``ambiguous`` or
1671+
``nonexistent`` to control how the timestamp should be re-localized.
1672+
1673+
>>> rng_tz = pd.DatetimeIndex(["2021-10-31 03:30:00"], tz="Europe/Amsterdam")
1674+
1675+
>>> rng_tz.floor("2H", ambiguous=False)
1676+
DatetimeIndex(['2021-10-31 02:00:00+01:00'],
1677+
dtype='datetime64[ns, Europe/Amsterdam]', freq=None)
1678+
1679+
>>> rng_tz.floor("2H", ambiguous=True)
1680+
DatetimeIndex(['2021-10-31 02:00:00+02:00'],
1681+
dtype='datetime64[ns, Europe/Amsterdam]', freq=None)
16621682
"""
16631683

16641684
_floor_example = """>>> rng.floor('H')
@@ -1673,6 +1693,19 @@ def strftime(self, date_format: str) -> npt.NDArray[np.object_]:
16731693
1 2018-01-01 12:00:00
16741694
2 2018-01-01 12:00:00
16751695
dtype: datetime64[ns]
1696+
1697+
When rounding near a daylight savings time transition, use ``ambiguous`` or
1698+
``nonexistent`` to control how the timestamp should be re-localized.
1699+
1700+
>>> rng_tz = pd.DatetimeIndex(["2021-10-31 03:30:00"], tz="Europe/Amsterdam")
1701+
1702+
>>> rng_tz.floor("2H", ambiguous=False)
1703+
DatetimeIndex(['2021-10-31 02:00:00+01:00'],
1704+
dtype='datetime64[ns, Europe/Amsterdam]', freq=None)
1705+
1706+
>>> rng_tz.floor("2H", ambiguous=True)
1707+
DatetimeIndex(['2021-10-31 02:00:00+02:00'],
1708+
dtype='datetime64[ns, Europe/Amsterdam]', freq=None)
16761709
"""
16771710

16781711
_ceil_example = """>>> rng.ceil('H')
@@ -1687,6 +1720,19 @@ def strftime(self, date_format: str) -> npt.NDArray[np.object_]:
16871720
1 2018-01-01 12:00:00
16881721
2 2018-01-01 13:00:00
16891722
dtype: datetime64[ns]
1723+
1724+
When rounding near a daylight savings time transition, use ``ambiguous`` or
1725+
``nonexistent`` to control how the timestamp should be re-localized.
1726+
1727+
>>> rng_tz = pd.DatetimeIndex(["2021-10-31 01:30:00"], tz="Europe/Amsterdam")
1728+
1729+
>>> rng_tz.ceil("H", ambiguous=False)
1730+
DatetimeIndex(['2021-10-31 02:00:00+01:00'],
1731+
dtype='datetime64[ns, Europe/Amsterdam]', freq=None)
1732+
1733+
>>> rng_tz.ceil("H", ambiguous=True)
1734+
DatetimeIndex(['2021-10-31 02:00:00+02:00'],
1735+
dtype='datetime64[ns, Europe/Amsterdam]', freq=None)
16901736
"""
16911737

16921738

0 commit comments

Comments
 (0)