--- myst: html_meta: description: >- Converting between whenever types and their standard library equivalents with to_stdlib() and the constructors, how a datetime with a ZoneInfo is resolved, and which types have no stdlib counterpart. --- # Standard library conversions ```{eval-rst} .. currentmodule:: whenever ``` 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: ```python >>> 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 | {mod}`datetime` equivalent | *to* {mod}`datetime` | *from* {mod}`datetime` | |:---------------------------|:-------------------------------------------------------------|:----------------------------------|:--------------------------------------------------------------------| | {class}`Instant` | {class}`~datetime.datetime` with {data}`~datetime.UTC` | {meth}`~Instant.to_stdlib` | `Instant(py_datetime)` | | {class}`ZonedDateTime` | {class}`~datetime.datetime` with {class}`~zoneinfo.ZoneInfo` | {meth}`~ZonedDateTime.to_stdlib` [^system-tz] | `ZonedDateTime(py_datetime, disambiguation=, offset_mismatch=)` | | {class}`OffsetDateTime` | {class}`~datetime.datetime` with {class}`~datetime.timezone` | {meth}`~OffsetDateTime.to_stdlib` | `OffsetDateTime(py_datetime)` | | {class}`PlainDateTime` | {class}`~datetime.datetime` (naive) | {meth}`~PlainDateTime.to_stdlib` | `PlainDateTime(py_datetime)` | | | | | | | {class}`Date` | {class}`~datetime.date` | {meth}`~Date.to_stdlib` | `Date(py_date)` | | {class}`Time` | {class}`~datetime.time` | {meth}`~Time.to_stdlib` | `Time(py_time)` | | {class}`YearMonth` | N/A | N/A | N/A | | {class}`MonthDay` | N/A | N/A | N/A | | {class}`IsoWeekDate` | the {meth}`~datetime.date.isocalendar` result, a named tuple, not a type | via {meth}`~IsoWeekDate.date` | via `Date(py_date)` | | | | | | | {class}`TimeDelta` | {class}`~datetime.timedelta` | {meth}`~TimeDelta.to_stdlib` | `TimeDelta(py_timedelta)` | | {class}`ItemizedDelta` | N/A | N/A | N/A | | {class}`ItemizedDateDelta` | N/A | N/A | N/A | [^system-tz]: A system time zone without a time zone ID converts to a fixed-offset `datetime`; see the admonition below. ```{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 are **floored** to microseconds. ``` The declared standard library type's own fields are the contract. A field the target cannot hold raises {exc}`ValueError`: a `time` with a `tzinfo`, an aware `datetime` for {class}`PlainDateTime`, and a naive one for {class}`Instant`, {class}`OffsetDateTime`, and {class}`ZonedDateTime`. ```{warning} Subclasses of the standard library types are accepted and read through the standard library attributes, so data those attributes cannot represent is lost. `pandas.Timestamp` and `pandas.Timedelta` carry nanoseconds; `pendulum.Duration` carries months and years (and folds them into 30-day days). Passing one of these emits a {class}`~whenever.WheneverWarning`. Convert explicitly instead: `Instant.from_timestamp(ts.value, unit="nanosecond")` for a `pandas.Timestamp`, `TimeDelta(nanoseconds=td.value)` for a `pandas.Timedelta`, and an {class}`~whenever.ItemizedDelta` built from the `pendulum.Duration`'s components. A `datetime` given to {class}`Date` is the same case: it is a `date` subclass whose time is dropped, so it warns; call `.date()` first. A subclass that adds no data, such as freezegun's `FakeDatetime`, passes silently. ``` ```{admonition} Converting a datetime with a ZoneInfo :class: note {class}`~whenever.ZonedDateTime` reads such a datetime as local fields, the offset its {class}`~zoneinfo.ZoneInfo` computes for them, and a time zone ID. An ISO string with an offset and a time zone ID carries the same three things, so both go through the same {ref}`resolution flow `. The constructor accepts `offset_mismatch=` and `disambiguation=`, and raises {exc}`~whenever.InvalidOffsetError` by default when the standard library's rules and *whenever*'s own rules disagree. A local time in a gap is the exception: under [PEP 495](https://peps.python.org/pep-0495/) the datetime still names one instant, which its `fold` selects, and *whenever* takes that instant without applying `disambiguation=`. {class}`~zoneinfo.ZoneInfo` subclasses are accepted. `timezone.utc`, pytz, and dateutil tzinfos are rejected with {exc}`ValueError`, because they carry no time zone ID: use `OffsetDateTime()` or `Instant()` for those. `fold` is read through the offset on aware datetimes and set by `to_stdlib()`, so both occurrences of a repeated local time round-trip. On naive datetimes and on `time`, `fold` is ignored. `to_stdlib()` hands the time zone ID to the standard library, which resolves it on its own search path. A system time zone without a time zone ID gives a fixed-offset {class}`~datetime.timezone` instead. ``` ```{admonition} FAQ :class: hint {ref}`faq-why-not-dropin` ``` There are no Python equivalents for the following classes: - {class}`ItemizedDelta` and {class}`ItemizedDateDelta` cannot be converted to {class}`~datetime.timedelta` because they may contain calendar units, and because they are itemized: every component is kept as given, unlike {class}`~datetime.timedelta`. - {class}`YearMonth` and {class}`MonthDay` cannot be converted because there is no direct equivalent in the standard library. {class}`IsoWeekDate` has a named tuple, not a type, in the standard library: go through `.date()`.