Keeping sane when handling timezones — a quickstart guide with python
Handling time zones can be quite maddening at first. If you work developing software, chances are you’ll have to deal with timezones eventually, primarily if your project is used in multiple locations (states, countries…).
It’s really confusing for the human brain to compare dates and times in different time zones. If you ever took a flight to a destination at a different timezone, you have experienced how confusing it can be.
This short article aims to give you a quick start with the terminology, most used methods, and some tips and tricks.
Terminology
- Timezone: From Wikipedia, “A time zone is an area which observes a uniform standard time for legal, commercial and social purpose. All time zones are defined as offsets from Coordinated Universal Time (UTC).”
- Naive date time object: when a DateTime object does not contain timezone information, we call it “naive”, e.g. 2022–10–13 8:00. This data time has some limitations, as you won’t be able to run certain calculations without the timezone info.
- Aware date time object: if you have a DateTime object and the timezone info e.g. 2022–10–13 8:00 (GMT-3:00 BRT), then you can run calculations and easily convert this to other timezones.
- Time delta: a time period, like “4 hours and 15 minutes”.
Looking at a few examples
Flights are a perfect example to work on: you depart from a city that has a different timezone from the destination. Let’s see what that looks like:
Here’s a summary of each step:
- 1-timezones.py: Importing the modules we need in the rest of the code
- 2-timezones.py: Creating a new data class named City to save the city’s name and time zone info
- 3-timezones.py: Another data class for flight information. We’ll need the origin, destination, flight duration, and departure time. Note we’ll also need some calculation methods to display the arrival date at the correct timezone.
- 4-timezones.py: Putting everything together: initialize City objects for origin and destination, along with a Flight.
This code will output:
Note the flight took 4h15, but the local time when you left was 16:15, and 19:30 when you arrived 🤯
Databases
You’ll probably want to store date-time objects in the database at some point. When that happens make sure you save the timezone information as well, so you can adequately convert when needed.
Example in Postgres:
select created_at at time zone 'america/los_angeles'
from users;A few gotchas to avoid
Timezones are more than a single offset between UTC and the local time. They store information about a geographical area that might have had multiple offsets over the course of history.
Take Daylight Saving Time for example. The offset changes in a geographical area twice a year.
Gladly, pytz handles this for us, we have to make sure to use the correct method:
See the offset is incorrect for 2 reasons:
- Daylight Saving Time ended in this region on 2022–11–06. The offset should be UTC-4, not UTC-5.
- There is a 4-minute difference; As we mentioned earlier, the timezone represents a geographical area that might’ve had multiple timezones over time. If we don’t localize the date correctly, pytz won’t know the correct offset to use.
Do this instead:
Note the offset is correct when we use the localize method. Plus, the 4-minute difference is gone 🎉.
Conclusion
As long as you have a reference to the correct timezone and you localize/convert from one to another, python should manage timezones marvelously for you. Also, be aware to use the correct localize method from pytz to ensure you get the correct offset 🎉
A few references:
