Working With TimeZones in Python

In this tutorial, we will learn how to work with timezone in Python.

After reading this article, you’ll learn:

• Handling of timezone by creating a timezone aware date and time.
• How to get the current time in a different timezone
• Get the current timezone name, UTC offset, and DST offset if DST is in effect
• How to convert UTC Datetime to a specific timezone
• Convert time from one timezone to another
• Mathematical operations on two timezone-aware and timezone naive objects
• Learn the tzinfo implementation modules namely pytz, ZoneInfo, and their methods.

What is timezone in Python?

A time zone represents the standardized time depending on which part of the world is being considered.

In simple terms, timezone refers to the local time of a region. UTC (Coordinated Universal Time) is the astronomical time based on earth’s rotation, is the standard against which the world’s region-based time is coordinated.

Note: UTC – Coordinated Universal Time is the common time standard across the world. So, in Python, to work with the timezone without any issues, it is recommended to use the UTC as your base timezone

For example, CT(Central Time) in North and South America is either 5 or 6 hours behind and represented as UTC-5 or UTC-6 based on the Day Light Saving. Below are a few examples.

UTC Offset	Locations	Name	Location
UTC +9	Japan, South Korea, and 5 more	JST	Tokyo
UTC +5:30	India	IST	India
UTC +1	The United Kingdom and 20 more	BST	London
UTC -10	Hawaii/USA and 2 more	HST	Honolulu

Python provides the datetime.tzinfo abstract base class which provides methods to handle timezone. But this class is an abstract base class and should not be instantiated directly. We need to define a subclass of tzinfo to capture information about a particular time zone.

The pytz library has implemented a timezone class for handling arbitrary fixed offsets from UTC and timezones. This library allows accurate and cross-platform timezone calculations and also solves the issue of ambiguous times at the end of daylight saving time.

pytz is a concrete implementation of the abstract base class tzinfo and is used to create timezone-aware datetime objects.

For example, The datetime.now() function returns the current local date-time without any timezone information. Using the pytz library, we can pass the timezone name to this function to get the current datetime in the given timezone.

We’ll use the following attributes and methods of the pytz module to work with timezone in Python.

• pytz.utc: Get the standard UTC timezone
• pytz.timezone('region'): Create the timezone object of a particular region
• pytz.astimezone(): Convert the time of a particular time zone into another time zone

Create Timezone Aware Datetime Object

In Python, a date object can be mentioned with or without timezones. Based on that, an object is known as Naive or Aware. A date object, by default, is naive. A datetime or time object is aware if it holds the timezone(tz) value.

Follow the below steps to create a timezone aware Datetime Object in Python: –

• Install pytz module if not installed using the pip install pytz command.
• Use the pytz.timezone('region_name') function to create the timezone object
• Use the datetime.now(timezone_obj) or datetime.datetime('timezone') function to create the timezone aware current datetime.

Example:

from datetime import datetime
import pytz

# current Datetime
unaware = datetime.now()
print('Timezone naive:', unaware)

# Standard UTC timezone aware Datetime
aware = datetime.now(pytz.utc)
print('Timezone Aware:', aware)

# US/Central timezone datetime
aware_us_central = datetime.now(pytz.timezone('US/Central'))
print('US Central DateTime', aware_us_central)

Output:

Timezone naive: 2021-07-09 13:22:02.256978
Timezone Aware: 2021-07-09 07:52:02.256978+00:00
US Central DateTime 2021-07-09 02:52:02.313026-05:00

• To get the UTC time we used the pytz.utc as a parameter to datetime.now() function. The offset at the end is +00:00 which is the standrad UTC offset.
• To get the CDT datetime, we used the ‘US/Central’ region to create a timezone. The offset at the end is -05:00 is the UTC offset of the CDT region

Refer to list all timezones in Python if you don’t know the exact name of the timezone to create a date and time in the right timezone.

To make the old/existing datetime timezone aware, use the following code.

from datetime import datetime
import pytz

unaware = datetime(2021, 6, 15, 8, 45, 17, 5)
print('Timezone naive:', unaware)

# Convert unaware Datetime to UTC timezone aware Datetime
aware = unaware.replace(tzinfo=pytz.UTC)
print(aware)

Note: The datetime.replace() method return the new datetime instance.

Format UTC DateTime to Get the timezone name

Extract the timezone name from UTC DateTime using the DateTime formatting in Python. Use the %Z directive to get the timezone name.

from datetime import datetime
import pytz

datetime_india = datetime.now(pytz.timezone('Asia/Kolkata'))
print("Formatted DateTime in IST : ", datetime_india.strftime('%Y:%m:%d %H:%M:%S %Z %z'))
# Output 2021:07:08 17:53:23 IST +0530

Note: IST is the timezone name

Create TimeZone Aware Datetime Object Using timezone class

Let’s see how create a timezone aware datetime object without pytz.

The datetime modules have the timezone class, which in turn is the subclass of the abstract base class tzinfo. Each instance created of the timezone class represents the offset of the timezone from the Coordinated Universal Time (UTC).

We can create an UTC-aware datetime object by assigning the timezone.utc

Syntax:

datetime.timezone(offset, name=None)

Here offset represents the difference between the local time and the UTC (Coordinated Universal Time). It can be a time delta object ranging from hours=-24 to +24.

Example:

from datetime import datetime, timezone, timedelta

# naive
naive = datetime.now()
print("Naive DateTime:", naive)

# UTC aware
UTC = datetime.now(timezone.utc)
print("UTC DateTime", UTC)

# Creating a datetime with JST (Japan) TimeZone
jst_dateTime = datetime.now(timezone(timedelta(hours=+9), 'JST'))
print("In JST::", jst_dateTime)

Note: we are setting the UTC offset using the timedelta class timedelta(hours=+9)

Get Current Time in Different Timezone

Using the pytz module we can get the current date and time of any timezone.

Syntax:

datetime.now(pytz.timezone('timezone name'))

Steps:

• Use the pytz.timezone('region_name') function to create the timezone object
• Use datetime.now(timezone_obj) function to get the current datetime of the given timezone.

Note: UTC – Coordinated Universal Time is the common time standard across the world. So, to work with the timezone without any issues, it is recommended to use the UTC as your base timezone.

In this example, we’ll see how to get the current datetime in the following timezones

USA: Get current Date and Time in the following TimeZones of United States

from datetime import datetime
import pytz

dt_us_central = datetime.now(pytz.timezone('America/Mexico_City'))
print("US Central DateTime:", dt_us_central.strftime("%Y:%m:%d %H:%M:%S %Z %z"))

dt_us_pacific = datetime.now(pytz.timezone('America/Tijuana'))
print("US Pacific timezone DateTime:", dt_us_pacific.strftime("%Y:%m:%d %H:%M:%S %Z %z"))

dt_us_eastern = datetime.now(pytz.timezone('America/New_York'))
print("US Eastern timezone DateTime:", dt_us_eastern.strftime("%Y:%m:%d %H:%M:%S %Z %z"))

dt_us_mountain = datetime.now(pytz.timezone('America/Chihuahua'))
print("US Mountain timezone DateTime:", dt_us_mountain.strftime("%Y:%m:%d %H:%M:%S %Z %z"))

Output:

US Central DateTime: 2021:07:08 08:37:34 CDT -0500
US Pacific timezone DateTime: 2021:07:08 06:37:34 PDT -0700
US Eastern timezone DateTime: 2021:07:08 09:37:34 EDT -0400
US Mountain timezone DateTime: 2021:07:08 07:37:34 MDT -0600

Other TimeZones

from datetime import datetime
import pytz

dt_japan = datetime.now(pytz.timezone('Asia/Tokyo'))
print("Japan DateTime:", dt_japan.strftime("%Y:%m:%d %H:%M:%S %Z %z"))

dt_brazil = datetime.now(pytz.timezone('America/Sao_Paulo'))
print("Brazil DateTime:", dt_brazil.strftime("%Y:%m:%d %H:%M:%S %Z %z"))

dt_uk = datetime.now(pytz.timezone('Europe/London'))
print("Uk DateTime:", dt_uk.strftime("%Y:%m:%d %H:%M:%S %Z %z"))

dt_germany = datetime.now(pytz.timezone('Europe/Berlin'))
print("Germany DateTime:", dt_germany.strftime("%Y:%m:%d %H:%M:%S %Z %z"))

dt_aus = datetime.now(pytz.timezone('Australia/Canberra'))
print("Australia Oceanic DateTime:", dt_aus.strftime("%Y:%m:%d %H:%M:%S %Z %z"))

dt_africa = datetime.now(pytz.timezone('Africa/Maputo'))
print("Central Africa: DateTime:", dt_africa.strftime("%Y:%m:%d %H:%M:%S %Z %z"))

Output:

Japan DateTime: 2021:07:09 12:02:38 JST +0900
Brazil DateTime: 2021:07:09 00:02:38 -03 -0300
Uk DateTime: 2021:07:09 04:02:38 BST +0100
Germany DateTime: 2021:07:09 05:02:38 CEST +0200
Australia Oceanic DateTime: 2021:07:09 13:02:38 AEST +1000
Central Africa: DateTime: 2021:07:09 05:02:38 CAT +0200

Also, see: Convert between timezones

Get TimeZone Information Using tzinfo

The datetime.tzinfo is an abstract base class containing information about the date or time object passed to them.

The tzinfo generally contains the following information: –

• The time zone name of a Datetime
• Offset from the UTC (Coordinated Universal Time)
• The DST(Daylight saving).

The tzinfo class provides the following method to get the timezone information: –

• tzinfo.tzname(dt): Returns the time zone name corresponding to the datetime object dt. This method returns the name that is used while creating the timezone object
• tzinfo.utcoffset(dt): This method returns the total offset from the UTC which should be a timedelta object. The values of the timedelta is positive if it is east of UTC and negative for the west of UTC. The total offset includes both timezone and the DST(Day light savings) values. The range of the timedelta is therfore between -timedelta(hours=24) to timedelta(hours=24)
• tzinfo.dst(dt): This method returns dst offset in the zones where dst is in effect. In other cases it will return only timedelta(0). The dst information is already part of the the utcoffset therefore the tz.utcoffset(dt) - tz.dst(dt) should return the standard offset of the timezone irrespective of the date and time but only on the geographic location.

Example:

from datetime import datetime
import pytz

# timezone: US Central Time
dt_us_central = datetime.now(pytz.timezone('America/Mexico_City'))
print("US Central DateTime:", dt_us_central.strftime("%Y:%m:%d %H:%M:%S %Z %z"))

# Get current TimeZone name
print(dt_us_central.tzname())

# Get UTC Offset
print(dt_us_central.utcoffset())

# Get the daylight saving time (DST offset) adjustment
print(dt_us_central.dst())

Our code produced the following information:

US Central DateTime: 2021:07:08 22:30:06 CDT -0500
TimeZone Name: CDT
UTC Offset -1 day, 19:00:00
DST: 1:00:00

The datetime modules have the timezone class, which in turn is the subclass of the abstract base class tzinfo

Converting Between Timezones

Use the datetime.astimezone() method to convert the datetime from one timezone to another. This method uses an instance of the datetime object and returns a new datetime of a given timezone.

import datetime
import pytz

# UTC timezone Datetime
dt_local = datetime.datetime.now(pytz.utc)
print("UTC DateTime:", dt_local.strftime("%Y:%m:%d %H:%M:%S %Z %z"))

# convert UTC timezone to 'US/Central'
dt_us_central = dt_local.astimezone(pytz.timezone('US/Central'))
print("US Central DateTime:", dt_us_central.strftime("%Y:%m:%d %H:%M:%S %Z %z"))

# Convert 'US/Central' timezone to US/Eastern
dt_us_eastern = dt_us_central.astimezone(pytz.timezone('America/New_York'))
print("US Eastern DateTime:", dt_us_eastern.strftime("%Y:%m:%d %H:%M:%S %Z %z"))

# Convert US/Eastern timezone to IST (India) timezone
dt_ind = dt_us_eastern.astimezone(pytz.timezone('Asia/Kolkata'))
print("India DateTime:", dt_ind.strftime("%Y:%m:%d %H:%M:%S %Z %z"))

Output:

UTC DateTime: 2021:07:09 07:19:02 UTC +0000
US Central DateTime: 2021:07:09 02:19:02 CDT -0500
US Eastern DateTime: 2021:07:09 03:19:02 EDT -0400
India DateTime: 2021:07:09 12:49:02 IST +0530

Working with Local Timezones

Note: To work with the timezone without any issues, it is recommended to use the UTC as your base timezone not a local time.

As already mentioned, we can convert a naive datetime to an aware datetime instance with a timezone value set to a local standardized value.

We can do it with one of the pytz methods called localize() .This method is used to convert a naive to local time. It accepts the two arguments, namely the datetime object to localize and an optional is_dst flag.

This flag is set to true if we want to localize and the daylight saving information and false if we want only the standard offset time and false otherwise.

As mentioned above the tzinfo has a method called dst() which will return the Daylight Saving Time(DST) information if the flag is set to true.

Let us see an example to show how we can set a local time zone and get the DST information.

from datetime import datetime

import pytz

fmt = '%Y-%m-%d %H:%M:%S %Z%z'

# Indian Standard Time
tz_india = pytz.timezone('Asia/Kolkata')
ist_local = tz_india.localize(datetime.now())
print("Indian Standard Time::", ist_local.strftime(fmt))

# Europe/Amsterdam Time
amdam_tz = pytz.timezone('Europe/Amsterdam')
dt = datetime(1983, 8, 3, 2, 0, 0)
cest_local = amdam_tz.localize(dt, is_dst=True)
print("Amsterdam with daylight saving time::", cest_local.strftime(fmt))

# Day Light Saving
print("Daylight saving time in amsterdam on 3/8/83::", cest_local.tzinfo.dst(cest_local))

Output

Indian Standard Time:: 2021-03-09 14:04:37 IST+0530 Amsterdam with daylight saving time:: 1983-08-03 02:00:00 CEST+0200 
Daylight saving time in amsterdam on 3/8/83:: 1:00:00