Date and time handling in software has always been a pain point — because date-time math and timezones are hard! — and Python has has historically made some ill-advised choices in the past that catch even the most seasoned developers off-guard.

Author's Note

This post has generated quite a lot of feedback, and I have amended some of the examples and explanations below to better reflect the pitfalls that can arise. A few corrections have been made as well. Thanks to all those that wrote in! I really do appreciate it.

Naive Date-Time Objects Are a Menace

The biggest culprit in date-time related bugs has and always will be that Python allows the existence of timezone-naive date-time objects. If there's one thing you should be afraid of when dealing with dates, it's definitely timezone-naive dates.

Aware vs. Naive

A timezone-aware date-time object is one where a moment in time is paired with a timezone identifier; this is (most of the time) enough information to disambiguate one date-time from another, and to perform relative calculations between two or more timezone-aware date-time objects.

A timezone-naive date-time object is an object that contains a date and a time, but eschews any pretense of communicating an associated timezone. Which makes the whole thing completely useless.

It's like talking about distance without a unit: the only reason it kinda-sorta-sometimes works out is because you assume that everyone in the room is using the same system. Start mixing in folks that use kilometres with those that use miles, however, and you're going to end up crashing a very expensive spacecraft on the surface of Mars.

Epoch Timestamps

Epoch timestamps are, generally, a decent way to perform relative comparisons between two moments in time that satisfy the two following conditions:

1. Occurred after January 1st 1970 (and most likely before 2038).
2. Leap seconds don't matter¹.

With epochs, you can get the number of seconds between two events. What you do with those seconds afterwards is trickier (e.g. converting seconds to days/weeks/months/years), but the delta of integer seconds between those events is at least in the right ballpark to be useful.

In Python, the simplest way to get an epoch timestamp is by using the time module²:

>>> import time
>>> print(int(time.time())
1721069814

But it doesn't matter which language or operating system you use: pretty much everyone has agreed on what an epoch timestamp is, and we've also agreed on how to represent them. Standards! Sometimes they work.

Converting from Timestamps to datetime Objects

The zero-time for epoch is actually timezone-dependent since it is defined as the number of non-leap seconds that have elapsed since 1970-01-01T00:00:00 UTC.

But, it's just a counter! It doesn't matter where on the earth the computer (or very dedicated human) who generated the timestamp was in³.

The Python library actually calls the underlying time function from the standard C library, which (typically) implements the POSIX standard:

>>> import time
>>> import datetime
>>> datetime.datetime.fromtimestamp(time.time())
datetime.datetime(2024, 7, 15, 17, 10, 35, 561153)

The value returned by time.time() is, as I previously mentioned, relative to epoch (UTC), which does what you expect.

But datetime.datetime.now(), which is what many Python developers will reach for when needing the current date-time, returns a timezone-naive object that is in the timezone of your local system. This means that if you generate a timestamp from datetime.datetime.now().timestamp(), you may be in for a rough time.

If your operating system/container/whatever is set to use UTC as the local timezone, then you're probably okay. But when you run this code on a system whose timezone is set to a non-UTC timezone, then the result of datetime.datetime.fromtimestamp() will be a timezone-naive date-time object that has been converted to the system-local timezone!

Here's a more concrete example³, where my timezone is set to America/Toronto:

$ sudo systemsetup -gettimezone
Time Zone: America/Toronto

>>> import time
>>> import datetime
>>> now = datetime.datetime.now(); utcnow = datetime.datetime.utcnow()
>>> print(now)
datetime.datetime(2024, 7, 17, 11, 7, 32, 189510)
>>> print(utcnow)
datetime.datetime(2024, 7, 17, 15, 7, 32, 189532)

And if you try to convert the timestamp back to a date-time object:

>>> datetime.datetime.fromtimestamp(now.timestamp())
datetime.datetime(2024, 7, 17, 11, 7, 32, 189510)
>>> datetime.datetime.fromtimestamp(utcnow.timestamp())
datetime.datetime(2024, 7, 17, 15, 7, 32, 189532)

We get different results! This should not be surprising, since datetime.datetime.now() and datetime.datetime.utcnow() will produce different naive date-time objects if your local system time is not set to UTC.

This could have all been avoided had we assigned a timezone to those date-times in the first place. Be vigilant: Consider any timezone-naive object a menace to you and your sanity, and ensure that they don't infect your code.