{"id":2359,"library":"whenever","title":"Whenever","description":"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.","status":"active","version":"0.10.0","language":"en","source_language":"en","source_url":"https://github.com/ariebovenberg/whenever","tags":["datetime","timezone","time","date","calendar","modern-datetime"],"install":[{"cmd":"pip install whenever","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Provides robust timezone data and functionality, wrapping pytz and tzdata.","package":"pytz-works-for-all-timezones","optional":false}],"imports":[{"symbol":"ZonedDateTime","correct":"from whenever import ZonedDateTime"},{"symbol":"OffsetDateTime","correct":"from whenever import OffsetDateTime"},{"symbol":"LocalDateTime","correct":"from whenever import LocalDateTime"},{"symbol":"Date","correct":"from whenever import Date"},{"symbol":"Time","correct":"from whenever import Time"},{"symbol":"now","correct":"from whenever import now"},{"symbol":"today","correct":"from whenever import today"},{"note":"DateTimeDelta and DateDelta were removed in 0.10.0, replaced by ItemizedDelta and ItemizedDateDelta.","wrong":"from whenever import DateTimeDelta","symbol":"ItemizedDelta","correct":"from whenever import ItemizedDelta"}],"quickstart":{"code":"import whenever\n\n# Get the current datetime in the system's local timezone\nlocal_now = whenever.now()\nprint(f\"Local Now: {local_now}\")\n\n# Get current UTC datetime\nutc_now = whenever.now('UTC')\nprint(f\"UTC Now: {utc_now}\")\n\n# Get current datetime in a specific timezone\nparis_now = whenever.now('Europe/Paris')\nprint(f\"Paris Now: {paris_now}\")\n\n# Create a specific date\nmy_date = whenever.date(2023, 10, 27)\nprint(f\"My Date: {my_date}\")\n\n# Add 2 years and 3 months to a datetime\n# Use the new add method with keyword arguments\nfuture_datetime = utc_now.add(years=2, months=3)\nprint(f\"Future Datetime (UTC): {future_datetime}\")\n\n# Calculate difference between two datetimes using 'until'\ndelta = utc_now.until(future_datetime)\nprint(f\"Delta: {delta}\")","lang":"python","description":"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."},"warnings":[{"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()`.","message":"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.","severity":"breaking","affected_versions":">=0.10.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=0.9.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)`.","message":"The top-level calendar delta helper functions (`whenever.years()`, `whenever.months()`, `whenever.weeks()`, `whenever.days()`) were deprecated in 0.10.0.","severity":"deprecated","affected_versions":">=0.10.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}