Standard library conversions¶

Most classes have an equivalent in the Python standard library. Use the to_stdlib() method to convert to the standard library equivalent, or pass the standard library object directly to the constructor:

>>> from datetime import *
>>> from whenever import *
>>> py_dt = datetime(2025, 4, 19, 15, 30, tzinfo=timezone.utc)
>>> instant = Instant(py_dt)
>>> instant.to_stdlib()
datetime.datetime(2025, 4, 19, 15, 30, tzinfo=datetime.timezone.utc)

whenever class	`datetime` equivalent	to `datetime`
`Instant`	`datetime` with `UTC`	`to_stdlib()`
`ZonedDateTime`	`datetime` with `ZoneInfo`	`to_stdlib()`
`OffsetDateTime`	`datetime` with `timezone`	`to_stdlib()`
`PlainDateTime`	`datetime` (naive)	`to_stdlib()`

`Date`	`date`	`to_stdlib()`
`Time`	`time`	`to_stdlib()`
`YearMonth`	N/A	N/A
`MonthDay`	N/A	N/A

`TimeDelta`	`timedelta`	`to_stdlib()`
`ItemizedDelta`	N/A	N/A
`ItemizedDateDelta`	N/A	N/A

Note

There are some exceptions where the conversion is not exact; see the individual method documentation for details.
Converting to the standard library is not always lossless. Nanoseconds will be truncated to microseconds.
The constructor also accepts subclasses, so you can also ingest types from pendulum and arrow libraries.

FAQ

Why no drop-in replacement for datetime?

There are no Python equivalents for the following classes:

ItemizedDelta and ItemizedDateDelta cannot be converted to timedelta because they may contain calendar units, and because they store their components in unnormalized form, unlike timedelta.
YearMonth and MonthDay cannot be converted because there is no direct equivalent in the standard library.