Exceptions and warnings

Warnings

exception whenever.TimeZoneUnawareArithmeticWarning

Bases: PotentialDstBugWarning

Raised when exact-time arithmetic is performed on a PlainDateTime without timezone context.

A PlainDateTime carries no timezone information. When you add or subtract exact time units (hours, minutes, seconds) or measure the difference between two PlainDateTime values, the computation treats every hour as equal. This warning is always emitted because there is no way to know whether a timezone transition falls in the interval–if one does, the result may be off by an hour or more.

For example, adding 2 hours to 2023-03-26 01:30 (Amsterdam) gives 03:30, but clocks jumped from 02:00 to 03:00 that morning, so only 1 real hour has passed.

The typical fix is to call assume_tz() first so the timezone is known, then perform the arithmetic on the resulting ZonedDateTime. Suppress this warning with the ignore_timezone_unaware_arithmetic_warning() context manager (or Python’s standard warning filters) if you: (a) explicitly accept potentially incorrect results, (b) know no transitions occur in the interval, or (c) are working with clock times not representing a real-world timezone (e.g. a simulation).

exception whenever.DaysNotAlways24HoursWarning

Bases: PotentialDstBugWarning

Raised when a TimeDelta operation assumes that calendar days are always exactly 24 hours long.

Due to DST transitions, a calendar day in a specific timezone can be 23 or 25 hours (or even other lengths in rare cases). When you add days using exact-time arithmetic (i.e. treating each day as 86,400 seconds), the result may be off by the length of the DST transition.

The typical fix is to use calendar-based arithmetic (e.g. ItemizedDelta) instead of exact-time shifts when the number of calendar days matters. Suppress this warning with the ignore_days_not_always_24h_warning() context manager (or Python’s standard warning filters) if 24-hour days are intentional.

exception whenever.PotentiallyStaleOffsetWarning

Bases: PotentialDstBugWarning

Raised when an operation on an OffsetDateTime may result in a datetime with an incorrect UTC offset.

A fixed UTC offset (e.g. +02:00) carries no timezone rules–it doesn’t know about DST, historical offset changes, or future policy decisions that could change which offset a region observes. After shifting, rounding, or replacing fields of an OffsetDateTime, the original offset is preserved verbatim. If the region has since changed its rules, the preserved offset may be wrong, silently producing a timestamp that is off by the difference.

The typical fix is to work with ZonedDateTime instead, which always keeps the offset in sync with the timezone rules. Alternatively, suppress this warning with the ignore_potentially_stale_offset_warning() context manager (or Python’s standard warning filters) when the fixed offset is intentional and correct.

exception whenever.PotentialDstBugWarning

Bases: UserWarning

Base class for warnings about potential DST-related bugs in user code.

This is not raised directly, but serves as the parent for DaysNotAlways24HoursWarning, PotentiallyStaleOffsetWarning, and TimeZoneUnawareArithmeticWarning. You can catch or filter all DST-related warnings at once by targeting this class.

Exceptions

exception whenever.RepeatedTime

Bases: ValueError

A datetime is repeated in a timezone, e.g. because of DST

exception whenever.SkippedTime

Bases: ValueError

A datetime is skipped in a timezone, e.g. because of DST

exception whenever.InvalidOffsetError

Bases: ValueError

A string has an invalid offset for the given zone

exception whenever.TimeZoneNotFoundError

Bases: ValueError

A timezone with the given ID was not found