Python datetime pitfalls, and what libraries are (not) doing about it

Original Article ↗ Hacker News Discussion ↗

Handling dates and times in software turns out to be far more complex than “just use UTC,” especially once daylight saving time, changing time zone laws, and future human-facing events like meetings or contracts are involved. Commenters debate how Python’s `datetime` module and alternatives should represent time—UTC instants, local “wall clock” times, fixed offsets, or full IANA time zones—and whether libraries should allow ambiguous or non-existent times at all. Many conclude that no single model fits every use case, so robust libraries need multiple explicit types and clear trade-offs rather than one magic timestamp abstraction.

UTC vs local time & future datetimes

  • Many argue “store everything in UTC” works well for past events and machine-centric timestamps.
  • Others stress this fails for future human-scheduled times (meetings, appointments, contracts).
  • Key point: future wall-clock times should usually be stored as (local datetime + IANA timezone), not pre-converted UTC, because timezone/DST rules can change.
  • There’s no universal rule: sometimes users intend a fixed UTC instant, sometimes “local wall time” at a place.

DST, time zones, and human expectations

  • DST and timezone policy are political and changeable; you cannot predict future rules.
  • Recurring events (“every Monday 10:00”, “1:1 every two weeks at 1 PM”) should not shift an hour across DST; that requires modeling local time and zones explicitly.
  • Cross-continent meetings suffer temporary misalignment when DST transitions occur on different dates; calendars typically choose one reference zone.

Data formats and epochs (ISO 8601, Unix time, etc.)

  • ISO 8601 / RFC 3339 help with string formatting but don’t solve timezone/DST semantics or location.
  • US-style MM/DD/YYYY and tools like Excel are seen as major sources of bugs.
  • Unix epoch seconds (or integer micro/nanoseconds) are popular for internal representation, but pre-1970 support and leap seconds are tricky.

Leap seconds

  • Some libraries (e.g., general-purpose ones, including those discussed) ignore leap seconds; specialized ones (e.g., astronomy-focused) handle them.
  • Opinions differ: some see ignoring leap seconds as acceptable for most apps; others note this breaks precise duration/instant math and parsing of “23:59:60”.

Library design: types and behavior

  • Strong support for distinct types:
    • Instant/UTC-only,
    • ZonedDateTime (IANA zones),
    • OffsetDateTime (fixed offset),
    • Local/naive date-times for wall-clock or recurring “alarm” use cases.
  • Combining naive and zoned data in one type (as in some JS and Python libs) is widely criticized.
  • Debate over representing nonexistent times during DST gaps:
    • Some favor disallowing or erroring on invalid local times.
    • Others prefer documented, deterministic “best-effort” mappings, even if surprising.

“Local time” concept

  • Some argue system “local time” is a historical mistake except for UI and libc-compat; better to always specify explicit time zones or locations.
  • Others note normal users and devices still need a notion of local wall-clock time for alarms, cron-like tasks, and “4pm at the cafe” semantics.