whenever 0.1.0

Overview

Whenever distinguishes these types of datetimes:

from whenever import (
    UTCDateTime, OffsetDateTime, ZonedDateTime, LocalDateTime, NaiveDateTime
)

and here’s how you can use them:

• UTCDateTime is always UTC: simple, fast, and unambiguous. It’s great if you’re storing when something happened (or will happen) regardless of location.

  py311_release_livestream = UTCDateTime(2022, 10, 24, hour=17)

  In >95% of cases, you should use this class over the others. The other classes are most often useful at the boundaries of your application.

• OffsetDateTime defines a local time with its UTC offset. This is great if you’re storing when something happened at a local time.

  from whenever import hours  # alias for timedelta(hours=...)
  
  # 9:00 in Salt Lake City, with the UTC offset at the time
  pycon23_started = OffsetDateTime(2023, 4, 21, hour=9, offset=hours(-6))

  It’s less suitable for future events, because the UTC offset may change (e.g. due to daylight savings time). For this reason, you cannot add/subtract a timedelta — the offset may have changed!

• ZonedDateTime accounts for the variable UTC offset of timezones, and is great for representing localized times in the past and future. Note that when the clock is set backwards, times occur twice. Use disambiguate to resolve these situations.

  # always at 11:00 in London, regardless of the offset
  changing_the_guard = ZonedDateTime(2024, 12, 8, hour=11, zone="Europe/London")
  
  # Explicitly resolve ambiguities when clocks are set backwards.
  # Default is "raise", which raises an exception
  night_shift = ZonedDateTime(2023, 10, 29, 1, 15, zone="Europe/London", disambiguate="later")

• LocalDateTime is a datetime in the system local timezone. This type is great for representing times related to the user’s system.

  print(f"Your timer will go off at {LocalDateTime.now() + hours(1)}.")

• NaiveDateTime has no timezone or UTC offset. Use this if you need a datetime type detached from the complexities of the real world.

  city_simulation_start = NaiveDateTime(1900, 1, 1, hour=0)

The pitfalls of datetime

Here are some of the issues with the standard library:

1. Can’t statically enforce aware datetimes. You can only annotate with datetime, which doesn’t distinguish between naive and aware.

   # 🧨 No easy way to enforce that it's aware, you only know at runtime
   def schedule_livestream(d: datetime) -> None: ...

2. Adding/subtracting timedelta doesn’t account for DST. You may think using timezoned datetimes solves this, but it doesn’t!

   # on the eve of changing the clock forward
   bedtime = datetime(2023, 3, 26, hour=22, tzinfo=ZoneInfo("Europe/Amsterdam"))
   # 🧨 6:00, but should be 7:00 due to DST
   bedtime + timedelta(hours=8)

3. The meaning of naive datetimes is inconsistent.

   d = datetime(1970, 1, 1, 0)  # a naive datetime
   
   # ⚠️ Treated as a local datetime here...
   d.timestamp()
   d.astimezone(UTC)
   
   # 🧨 ...but assumed UTC here.
   d.utctimetuple()
   email.utils.format_datetime(d)
   datetime.utcnow()

4. You aren’t prevented from creating non-existent datetimes, which creates subtle havoc once you perform basic operations.

   # ⚠️ No error that the datetime doesn't exist due to DST (clock set forward)
   d = datetime(2023, 3, 26, hour=2, minute=30, tzinfo=ZoneInfo("Europe/Amsterdam"))
   
   # 🧨 No UTC equivalent exists, so it just makes one up
   assert d.astimezone(UTC) == d  # False???

5. In the face of ambiguity, it guesses. When a datetime occurs twice (due to the clock being set backwards), the fold attribute resolves the ambiguity. However, it silently defaults to 0, negating the explicitness of the attribute.

   # 🧨 Code silently assumes you mean the first occurrence
   d = datetime(2023, 10, 29, 2, 30, tzinfo=ZoneInfo("Europe/Amsterdam"))

6. Equality between ambiguous datetimes is always False, even while the whole purpose of fold is to disambiguate them.

   # We carefully disembiguate a DST-ambiguous datetime with fold=1...
   x = datetime(2023, 10, 29, 2, 30, tzinfo=ZoneInfo("Europe/Amsterdam"), fold=1)
   
   # 🧨 But nonetheless comparisons with other timezones are *always* False
   y = d.astimezone(UTC)
   assert x == y  # False, even though they're the same time!

7. Equality behaves differently within the same timezone than between different timezones.

   # 🧨 In the same timezone, fold is ignored...
   before_dst = datetime(2023, 10, 29, 2, 30, tzinfo=ZoneInfo("Europe/Amsterdam"), fold=0)
   after_dst = before_dst_transition.replace(fold=1)
   before_dst == after_dst  # True -- even though they are one hour apart!
   
   # ⁉️ ...but between different timezones, it *is* accounted for!
   after_dst = after_dst.astimezone(ZoneInfo("Europe/Paris"))
   before_dst == after_dst  # False -- even though Paris has same DST behavior as Amsterdam!

8. Datetime inherits from date, which leads to unexpected behavior. This is widely considered a design flaw in the standard library.

   # 🧨 Breaks when you pass in a datetime, even though it's a date subclass!
   def is_future(dt: date) -> bool:
       return dt > date.today()
   
   # 🧨 Doesn't make sense
   datetime.today()

Why not…?

Versioning and compatibility policy

Whenever follows semantic versioning. Until the 1.0 version, the API may change with minor releases. Breaking changes will be announced in the changelog. Since the API is fully typed, your typechecker and/or IDE will help you adjust to any API changes.

Acknowledgements

This project is inspired by the following projects. Check them out!

• DateType

• Pendulum

• Noda Time

• Chrono

Contributing

Contributions are welcome! Please open an issue or pull request.

An example of setting up things and running the tests:

poetry install
pytest

⚠️ Note: The tests don’t run on Windows yet. This is because the tests use unix-specific features to set the timezone for the current process. It can be made to work on Windows too, but I haven’t gotten around to it yet.