Whenever¶

Type-safe datetimes for Python that get DST right. Rust or pure Python—your choice.

Do you cross your fingers every time you work with Python’s datetime—hoping that you didn’t mix naive and aware, or run into one of its other pitfalls?

bedtime = datetime(2023, 3, 25, 22, tzinfo=ZoneInfo("Europe/Paris"))
full_rest = bedtime + timedelta(hours=8)
# It returns 6am, but should be 7am—because we skipped an hour due to DST!

Whenever takes the guesswork out, bringing well-established concepts from modern datetime libraries in other languages to Python. Mixing up naive and aware becomes a type error instead of a bug you find in production, and DST is handled correctly in all arithmetic:

>>> from whenever import Instant, ZonedDateTime, PlainDateTime

# The same bedtime, DST-safe: you get your full eight hours
>>> bedtime = ZonedDateTime(2023, 3, 25, 22, tz="Europe/Paris")
>>> bedtime.add(hours=8)
ZonedDateTime("2023-03-26 07:00:00+02:00[Europe/Paris]")

# Explicit, type-safe conversions
>>> bedtime.to_tz("America/New_York")
ZonedDateTime("2023-03-25 17:00:00-04:00[America/New_York]")

# A moment in time, without timezone or calendar complexity
>>> Instant.now()
Instant("2024-07-04 10:36:56Z")

# Plain (naive) datetimes are a distinct type; impossible to mix with aware
>>> PlainDateTime(2023, 3, 26, 7) < bedtime  # caught by your type checker!

In short, it’s designed to be:

Correct: Smooths over the sharp edges of the standard library—DST first among them, but far from the only one.
Typesafe: Distinct types for exact and local time mean your type checker catches what would otherwise be a production bug.
Fast: In common operations, whenever is 10-100× faster than Pendulum and Arrow—and 2-4× as fast as the standard library. Rather not depend on a Rust extension? A pure Python version is available too.