Welcome to Whenever¶

Whenever is a Python library for working with dates and times.

Over two decades, Python’s datetime has accumulated pitfalls that trip up even experienced developers: arithmetic that silently ignores DST, and a type system that can’t distinguish between naive and aware datetimes. Popular alternatives like Arrow and Pendulum don’t fully address these issues either.

Whenever takes a different approach: a typesafe API built on well-established concepts from modern datetime libraries across languages—with exceptional performance via a Rust extension, and a pure Python option for environments that need it.

It’s designed to be:

Correct: Handles DST correctly in all arithmetic and fixes the most common pitfalls of Python’s standard datetime module.
Typesafe: Separate types for “aware” and plain datetimes make it impossible to accidentally mix them—modeled on proven concepts from modern datetime libraries in other languages.
Fast: In common operations, whenever is 10-100× faster than Pendulum and Arrow—and 2-4× as fast as the standard library.

A quick taste:

>>> from whenever import Instant, ZonedDateTime, PlainDateTime

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

# Explicit, type-safe conversions
>>> now.to_tz("Europe/Paris")
ZonedDateTime("2024-07-04 12:36:56+02:00[Europe/Paris]")

# DST-safe arithmetic; stdlib doesn't do this!
>>> zdt = ZonedDateTime("2023-10-28 22:00:00+02:00[Europe/Amsterdam]")
>>> zdt.add(hours=6)  # correctly accounts for the autumn clock change
ZonedDateTime("2023-10-29 03:00:00+01:00[Europe/Amsterdam]")

# Plain (naive) datetimes are a distinct type; impossible to mix with aware
>>> PlainDateTime("2024-07-04 15:30") < zdt  # caught by type checker!