diff --git a/src/pendulum/datetime.py b/src/pendulum/datetime.py index 96aff25b..361c6deb 100644 --- a/src/pendulum/datetime.py +++ b/src/pendulum/datetime.py @@ -825,43 +825,93 @@ def _end_of_hour(self) -> Self: """ return self.set(minute=59, second=59, microsecond=999999) + def _first_instant(self, year: int, month: int, day: int) -> Self: + """ + Return the earliest instant of the given local date. + """ + return self._local_instant(year, month, day, 0, 0, 0, 0, latest=False) + + def _last_instant(self, year: int, month: int, day: int) -> Self: + """ + Return the latest instant of the given local date. + """ + return self._local_instant(year, month, day, 23, 59, 59, 999999, latest=True) + + def _local_instant( + self, + year: int, + month: int, + day: int, + hour: int, + minute: int, + second: int, + microsecond: int, + latest: bool, + ) -> Self: + # Do not reuse self.fold: if the wall time is repeated (or skipped) + # by a DST change, only one fold gives the earliest (or latest) + # instant that still falls on the given date. + candidates = [ + self.__class__.create( + year, + month, + day, + hour, + minute, + second, + microsecond, + tz=self.tz, + fold=fold, + ) + for fold in (0, 1) + ] + on_date = [ + dt for dt in candidates if (dt.year, dt.month, dt.day) == (year, month, day) + ] or candidates + + def instant(dt: Self) -> datetime.datetime: + # Same-tzinfo comparisons ignore the offset, so compare in UTC terms. + return dt.replace(tzinfo=None) - (dt.utcoffset() or datetime.timedelta()) + + return (max if latest else min)(on_date, key=instant) + def _start_of_day(self) -> Self: """ Reset the time to 00:00:00. """ - return self.at(0, 0, 0, 0) + return self._first_instant(self.year, self.month, self.day) def _end_of_day(self) -> Self: """ Reset the time to 23:59:59.999999. """ - return self.at(23, 59, 59, 999999) + return self._last_instant(self.year, self.month, self.day) def _start_of_month(self) -> Self: """ Reset the date to the first day of the month and the time to 00:00:00. """ - return self.set(self.year, self.month, 1, 0, 0, 0, 0) + return self._first_instant(self.year, self.month, 1) def _end_of_month(self) -> Self: """ Reset the date to the last day of the month and the time to 23:59:59.999999. """ - return self.set(self.year, self.month, self.days_in_month, 23, 59, 59, 999999) + return self._last_instant(self.year, self.month, self.days_in_month) def _start_of_year(self) -> Self: """ Reset the date to the first day of the year and the time to 00:00:00. """ - return self.set(self.year, 1, 1, 0, 0, 0, 0) + return self._first_instant(self.year, 1, 1) def _end_of_year(self) -> Self: """ Reset the date to the last day of the year and the time to 23:59:59.999999. """ - return self.set(self.year, 12, 31, 23, 59, 59, 999999) + return self._last_instant(self.year, 12, 31) def _start_of_decade(self) -> Self: """ @@ -869,7 +919,7 @@ def _start_of_decade(self) -> Self: and the time to 00:00:00. """ year = self.year - self.year % YEARS_PER_DECADE - return self.set(year, 1, 1, 0, 0, 0, 0) + return self._first_instant(year, 1, 1) def _end_of_decade(self) -> Self: """ @@ -878,7 +928,7 @@ def _end_of_decade(self) -> Self: """ year = self.year - self.year % YEARS_PER_DECADE + YEARS_PER_DECADE - 1 - return self.set(year, 12, 31, 23, 59, 59, 999999) + return self._last_instant(year, 12, 31) def _start_of_century(self) -> Self: """ @@ -887,7 +937,7 @@ def _start_of_century(self) -> Self: """ year = self.year - 1 - (self.year - 1) % YEARS_PER_CENTURY + 1 - return self.set(year, 1, 1, 0, 0, 0, 0) + return self._first_instant(year, 1, 1) def _end_of_century(self) -> Self: """ @@ -896,7 +946,7 @@ def _end_of_century(self) -> Self: """ year = self.year - 1 - (self.year - 1) % YEARS_PER_CENTURY + YEARS_PER_CENTURY - return self.set(year, 12, 31, 23, 59, 59, 999999) + return self._last_instant(year, 12, 31) def _start_of_week(self) -> Self: """ diff --git a/tests/datetime/test_start_end_of.py b/tests/datetime/test_start_end_of.py index 1937e74d..3c4d6180 100644 --- a/tests/datetime/test_start_end_of.py +++ b/tests/datetime/test_start_end_of.py @@ -323,3 +323,48 @@ def test_end_of_on_date_after_transition(): assert d.end_of("day").offset == 3600 assert d.end_of("month").offset == 3600 assert d.end_of("year").offset == 3600 + + +def _from_utc(tz, *args): + # Like pendulum.now(tz): fold is 0 for an unambiguous time. + return pendulum.datetime(*args, tz="UTC").in_timezone(tz) + + +def test_start_of_day_skipped_midnight_with_fold_0(): + # Santiago skipped 2022-09-11 00:00-01:00; the day starts at 01:00. + d = _from_utc("America/Santiago", 2022, 9, 11, 15) + assert d.fold == 0 + + start = d.start_of("day") + assert_datetime(start, 2022, 9, 11, 1, 0, 0, 0) + assert start.offset == -3 * 3600 + + +def test_start_of_month_skipped_midnight_with_fold_0(): + # Asuncion skipped 2023-10-01 00:00-01:00. + d = _from_utc("America/Asuncion", 2023, 10, 15, 15) + assert d.fold == 0 + + start = d.start_of("month") + assert_datetime(start, 2023, 10, 1, 1, 0, 0, 0) + assert start.offset == -3 * 3600 + + +def test_start_of_day_repeated_midnight_with_fold_1(): + # Havana repeated 2012-11-04 00:00-01:00; the day starts at the first 00:00. + d = pendulum.datetime(2012, 11, 4, 12, tz="America/Havana") + assert d.fold == 1 + + start = d.start_of("day") + assert_datetime(start, 2012, 11, 4, 0, 0, 0, 0) + assert start.offset == -4 * 3600 + + +def test_end_of_day_repeated_last_hour_with_fold_0(): + # Santiago repeated 2023-04-01 23:00-24:00; the day ends in the second pass. + d = _from_utc("America/Santiago", 2023, 4, 1, 15) + assert d.fold == 0 + + end = d.end_of("day") + assert_datetime(end, 2023, 4, 1, 23, 59, 59, 999999) + assert end.offset == -4 * 3600