Whenever

0.10.0 · active · verified Thu Apr 09

Whenever is a modern datetime library for Python, aiming to provide an intuitive and consistent API for working with dates and times, with a focus on correctness and ease of use. It is currently at version 0.10.0 and has an active development cadence with regular releases.

Warnings

breaking The `DateTimeDelta` and `DateDelta` classes were removed in version 0.10.0. They have been replaced by `ItemizedDelta` and `ItemizedDateDelta` respectively. The helper functions `years()`, `months()`, `weeks()`, `days()` for creating calendar deltas are also deprecated.
Fix: Migrate to `whenever.ItemizedDelta` or `whenever.ItemizedDateDelta`. For simple additions/subtractions, prefer using `add(years=X, months=Y)` methods directly on datetime objects, or `subtract()`.
breaking The `SystemDateTime` class was removed in version 0.9.0. Its functionality has been fully integrated into `ZonedDateTime`, which now serves as the canonical class for all timezone-aware datetimes, including those based on the system's local timezone.
Fix: Replace usages of `SystemDateTime` with `whenever.ZonedDateTime`. For example, `SystemDateTime.now()` becomes `whenever.ZonedDateTime.now()` (or `whenever.now()`), which defaults to the system's local timezone.
deprecated The top-level calendar delta helper functions (`whenever.years()`, `whenever.months()`, `whenever.weeks()`, `whenever.days()`) were deprecated in 0.10.0.
Fix: Instead of `whenever.now() + whenever.years(1)`, use the more explicit `whenever.now().add(years=1)`. For more complex deltas, use `whenever.ItemizedDelta` directly: `whenever.ItemizedDelta(years=1, months=2)`.
gotcha Be mindful of the distinction between `LocalDateTime`, `OffsetDateTime`, and `ZonedDateTime`. `LocalDateTime` is timezone-naive, `OffsetDateTime` has a fixed UTC offset, and `ZonedDateTime` is timezone-aware and handles Daylight Saving Time (DST) changes.
Fix: Always use `whenever.ZonedDateTime` for representing specific points in time across different geographic regions or when dealing with DST. Use `LocalDateTime` only when a date and time are sufficient without timezone context, or `OffsetDateTime` for fixed UTC offsets.

Install

pip install whenever Install stable version

Imports

ZonedDateTime
```
from whenever import ZonedDateTime
```
OffsetDateTime
```
from whenever import OffsetDateTime
```
LocalDateTime
```
from whenever import LocalDateTime
```
Date
```
from whenever import Date
```
Time
```
from whenever import Time
```
now
```
from whenever import now
```
today
```
from whenever import today
```
ItemizedDelta
```
from whenever import ItemizedDelta
```
DateTimeDelta and DateDelta were removed in 0.10.0, replaced by ItemizedDelta and ItemizedDateDelta.

Quickstart

This quickstart demonstrates how to get current datetimes in the local system timezone or a specified timezone, create a specific date, add durations using the new keyword arguments for flexible delta calculations, and calculate differences between datetimes.

import whenever

# Get the current datetime in the system's local timezone
local_now = whenever.now()
print(f"Local Now: {local_now}")

# Get current UTC datetime
utc_now = whenever.now('UTC')
print(f"UTC Now: {utc_now}")

# Get current datetime in a specific timezone
paris_now = whenever.now('Europe/Paris')
print(f"Paris Now: {paris_now}")

# Create a specific date
my_date = whenever.date(2023, 10, 27)
print(f"My Date: {my_date}")

# Add 2 years and 3 months to a datetime
# Use the new add method with keyword arguments
future_datetime = utc_now.add(years=2, months=3)
print(f"Future Datetime (UTC): {future_datetime}")

# Calculate difference between two datetimes using 'until'
delta = utc_now.until(future_datetime)
print(f"Delta: {delta}")

view raw JSON →