whenever

What it is and what it does

Whenever is a modern datetime library that addresses two core limitations of Python's standard library: it handles Daylight Saving Time correctly during arithmetic operations (e.g., adding hours across a DST boundary), and it uses distinct types to enforce type-safe distinction between naive and aware datetimes at compile time. The library provides three main types—Instant (UTC moments), ZonedDateTime (timezone-aware local times), and PlainDateTime (naive local times)—each with explicit semantics that prevent accidental mixing.

The package is available in two implementations: a Rust-backed version for performance and a pure-Python fallback for compatibility. It supports nanosecond precision, date arithmetic, common datetime formats (ISO8601, RFC3339, RFC2822), and integration with SQLAlchemy and Pydantic. The API is fully typed and follows semantic versioning; until version 1.0, minor releases may introduce breaking changes, though the type system helps identify necessary adjustments.

Use it for:

• Schedule events across DST transitions without silent hour-skipping bugs.
• Enforce type safety in APIs where functions must work only with aware or only with naive datetimes.
• Parse and format datetimes in standard formats (ISO8601, RFC2822) with full timezone awareness.
• Perform timezone conversions and comparisons with correct DST handling.
• Build datetime-heavy applications (e.g., scheduling, logging) where correctness is critical.
• Migrate from Arrow or Pendulum when DST correctness and type safety become requirements.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Whenever provides type-safe, DST-aware datetime handling for Python with explicit types that distinguish naive from aware datetimes, available as a Rust-backed or pure-Python implementation.

Yes. Whenever solves real, well-documented pitfalls in Python's datetime module—particularly DST arithmetic and type safety—that affect any application working with timezones. It has low install friction, active maintenance, no known vulnerabilities, and permissive licensing. The API is pre-1.0 and may change, but type checking will catch those changes. Install it if you work with timezones or need to prevent datetime mixing bugs; skip it only if you never cross timezone boundaries or can tolerate standard library footguns.

Install

whenever on PyPI

pip install whenever

uv add whenever

poetry add whenever

Installing whenever

Before you install

Low friction: pure Python wheel, only two runtime dependencies (tzdata, tzlocal). Actively maintained with a release 7 days ago and 2374 GitHub stars. Supports Python 3.10–3.15 and PyPy.

License in practice

MIT license (permissive). Binary wheels include Rust dependencies under similarly permissive licenses (MIT, Apache-2.0, others), with license details included in distributions.

Quickstart

pip install whenever

from whenever import Instant, ZonedDateTime, PlainDateTime

now = Instant.now()
party = PlainDateTime("2023-10-28 22:00").assume_tz("Europe/Amsterdam")
party_end = party.add(hours=6)  # DST-safe arithmetic

Requires Python 3.10 or later.

Verify before relying

• Whether the pure-Python fallback is automatically selected or requires explicit configuration.
• Performance comparison with standard library datetime for typical use cases.
• SQLAlchemy and Pydantic integration maturity beyond 'beta' status.

Package facts

Evidence: whenever-0.10.5-py3-none-any.whl

Keywords: datetime, typesafe, rust, date, time, timezone, utc, zoneinfo, tzdata, tzdb

Tags

More Software Development packages