Real Python: Using Python datetime to Work With Dates and Times

Note:If you want to learn more about why time can be so complicated to deal with, then there are many great resources available on the web. Here are a few good places to start:

• Computerphile: The Problem With Time & Timezones
• Working With Time Zones: Everything You Wish You Didn’t Need to Know
• The Complexity of Time Data Programming

How Computers Count Time

Nearly all computers count time from an instant called the Unix epoch . This occurred on January 1, 1970, at 00:00:00 UTC. UTC stands for Coordinated Universal Time and refers to the time at a longitude of 0°. UTC is often also called Greenwich Mean Time , or GMT. UTC is not adjusted for daylight saving time, so it consistently keeps twenty-four hours in every day.

By definition, Unix time elapses at the same rate as UTC, so a one-second step in UTC corresponds to a one-second step in Unix time. You can usually figure out the date and time in UTC of any given instant since January 1, 1970, by counting the number of seconds since the Unix epoch, with the exception of leap seconds . Leap seconds are occasionally added to UTC to account for the slowing of the Earth’s rotation but are not added to Unix time.

Note:There’s an interesting bug associated with Unix time. Since many older operating systems are 32-bit, they store the Unix time in a 32-bit signed integer.

This means that at 03:14:07 on January 19, 2038, the integer will overflow, resulting in what’s known as the Year 2038 problem , or Y2038. Similar to the Y2K problem , Y2038 will need to be corrected to avoid catastrophic consequences for critical systems.

Nearly all programming languages, including Python , incorporate the concept of Unix time. Python’s standard library includes a module called time that can print the number of seconds since the Unix epoch:

>>> import time
>>> time.time()
1579718137.550164

In this example, youimport the time module and execute time() to print the Unix time, or number of seconds (excluding leap seconds) since the epoch.

In addition to Unix time, computers need a way to convey time information to users. As you saw in the last example, Unix time is nearly impossible for a human to parse. Instead, Unix time is typically converted to UTC, which can then be converted into a local time using time zone offsets .

The Internet Assigned Numbers Authority (IANA) maintains a database of all of the values of time zone offsets. IANA also releases regular updates that include any changes in time zone offsets. This database is often included with your operating system, although certain applications may include an updated copy.

The database contains a copy of all the designated time zones and how many hours and minutes they’re offset from UTC. So, during the winter, when daylight saving time is not in effect, the US Eastern time zone has an offset of -05:00, or negative five hours from UTC. Other regions have different offsets, which may not be integer hours. The UTC offset for Nepal, for example, is +05:45, or positive five hours and forty-five minutes from UTC.

How Standard Dates Can Be Reported

Unix time is how computers count time, but it would be incredibly inefficient for humans to determine the time by calculating the number of seconds from an arbitrary date. Instead, we work in terms of years, months, days, and so forth. But even with these conventions in place, another layer of complexity stems from the fact that different languages and cultures have different ways of writing the date.

For instance, in the United States, dates are usually written starting with the month, then the day, then the year. This means that January 31, 2020, is written as 01-31-2020 . This closely matches the long-form written version of the date.

However, most of Europe and many other areas write the date starting with the day, then the month, then the year. This means that January 31, 2020, is written as 31-01-2020 . These differences can cause all sorts of confusion when communicating across cultures.

To help avoid communication mistakes, the International Organization for Standardization (ISO) developed ISO 8601 . This standard specifies that all dates should be written in order of most-to-least-significant data. This means the format is year, month, day, hour, minute, and second:

YYYY-MM-DD HH:MM:SS

In this example, YYYY represents a four-digit year, and MM and DD are the two-digit month and day, starting with a zero if necessary. After that, HH , MM , and SS represent the two-digit hours, minutes, and seconds, starting with a zero if necessary.

The advantage of this format is that the date can be represented with no ambiguity. Dates written as DD-MM-YYYY or MM-DD-YYYY can be misinterpreted if the day is a valid month number. You’ll see a littlehow you can use the ISO 8601 format with Python datetime .

How Time Should Be Stored in Your Program

Most developers who have worked with time have heard the advice to convert local time to UTC and store that value for later reference. In many cases, especially when you’re storing dates from the past, this is enough information to do any necessary arithmetic.

However, a problem can happen if a user of your program inputs a future date in their local time. Time zone and daylight saving time rules change fairly frequently, as you saw earlier with the 2007 change in daylight saving time for the United States and Canada. If the time zone rules for your user’s location change before the future date that they inputted, then UTC won’t provide enough information to convert back to the correct local time.

In this case, you need to store the local time, including the time zone, that the user inputted as well as the version of the IANA time zone database that was in effect when the user saved the time. This way, you’ll always be able to convert the local time to UTC. However, this approach won’t always allow you to convert UTC to the correct local time.

Creating Python datetime Instances

The three classes that represent dates and times in datetime have similar initializers . They can be instantiated by passing keyword arguments for each of the attributes, such as year , date , or hour . You can try the code below to get a sense of how each object is created:

>>> from datetime import date, time, datetime
>>> date(year=2020, month=1, day=31)
datetime.date(2020, 1, 31)
>>> time(hour=13, minute=14, second=31)
datetime.time(13, 14, 31)
>>> datetime(year=2020, month=1, day=31, hour=13, minute=14, second=31)
datetime.datetime(2020, 1, 31, 13, 14, 31)

In this code, you import the three main classes from datetime and instantiate each of them by passing arguments to the constructor. You can see that this code is somewhat verbose, and if you don’t have the information you need asintegers, these techniques can’t be used to create datetime instances.

Fortunately, datetime provides several other convenient ways to create datetime instances. These methods don’t require you to use integers to specify each attribute, but instead allow you to use some other information:

1. date.today() creates a datetime.date instance with the current local date.
2. datetime.now() creates a datetime.datetime instance with the current local date and time.
3. datetime.combine() combines instances of datetime.date and datetime.time into a single datetime.datetime instance.

These three ways of creating datetime instances are helpful when you don’t know in advance what information you need to pass into the basic initializers. You can try out this code to see how the alternate initializers work:

>>> from datetime import date, time, datetime
>>> today = date.today()
>>> today
datetime.date(2020, 1, 24)
>>> now = datetime.now()
>>> now
datetime.datetime(2020, 1, 24, 14, 4, 57, 10015)
>>> current_time = time(now.hour, now.minute, now.second)
>>> datetime.combine(today, current_time)
datetime.datetime(2020, 1, 24, 14, 4, 57)

In this code, you use date.today() , datetime.now() , and datetime.combine() to create instances of date , datetime , and time objects. Each instance is stored in a different variable:

1. today is a date instance that has only the year, month, and day.
2. now is a datetime instance that has the year, month, day, hour, minute, second, and microseconds.
3. current_time is a time instance that has the hour, minute, and second set to the same values as now .

On the last line, you combine the date information in today with the time information in current_time to produce a new datetime instance.

Warning: datetime also provides datetime.utcnow() , which returns an instance of datetime at the current UTC. However, the Python documentation recommends against using this method because it doesn’t include any time zone information in the resulting instance.

Using datetime.utcnow() may produce some surprising results when doing arithmetic or comparisons between datetime instances. In a, you’ll see how to assign time zone information to datetime instances.

Using Strings to Create Python datetime Instances

Another way to create date instances is to use .fromisoformat() . To use this method, you provide astring with the date in the ISO 8601 format that you learned about. For instance, you might provide a string with the year, month, and date specified:

2020-01-31

This string represents the date January 31, 2020, according to the ISO 8601 format. You can create a date instance with the following example:

>>> from datetime import date
>>> date.fromisoformat("2020-01-31")
datetime.date(2020, 1, 31)

In this code, you use date.fromisoformat() to create a date instance for January 31, 2020. This method is very useful because it’s based on the ISO 8601 standard. But what if you have a string that represents a date and time but isn’t in the ISO 8601 format?

Fortunately, Python datetime provides a method called .strptime() to handle this situation. This method uses a special mini-language to tell Python which parts of the string are associated with the datetime attributes.

To construct a datetime from a string using .strptime() , you have to tell Python what each of the parts of the string represents using formatting codes from the mini-language. You can try this example to see how .strptime() works:

 1 >>> date_string = "01-31-2020 14:45:37"
 2 >>> format_string = "%m-%d-%Y %H:%M:%S"

On line 1 , you create date_string , which represents the date and time January 31, 2020, at 2:45:37 PM. On line 2 , you create format_string , which uses the mini-language to specify how the parts of date_string will be turned into datetime attributes.

In format_string , you include several formatting codes and all of the dashes ( - ), colons ( : ), and spaces exactly as they appear in date_string . To process the date and time in date_string , you include the following formatting codes:

A complete listing of all of the options in the mini-language is outside the scope of this tutorial, but you can find several good references on the web, including in Python’s documentation and on a website called strftime.org .

Now that date_string and format_string are defined, you can use them to create a datetime instance. Here’s an example of how .strptime() works:

 3 >>> from datetime import datetime
 4 >>> datetime.strptime(date_string, format_string)
 5 datetime.datetime(2020, 1, 31, 14, 45, 37)

In this code, you import datetime on line 3 and use datetime.strptime() with date_string and format_string on line 4 . Finally, line 5 shows the values of the attributes in the datetime instance created by .strptime() . You can see that they match the values shown in the table above.

 1 >>> import dateparser
 2 >>> dateparser.parse("yesterday")
 3 datetime.datetime(2020, 3, 13, 14, 39, 1, 350918)
 4 >>> dateparser.parse("morgen")
 5 datetime.datetime(2020, 3, 15, 14, 39, 7, 314754)

Using dateutil to Add Time Zones to Python datetime

One reason that dateutil is so useful is that it includes an interface to the IANA time zone database. This takes the hassle out of assigning time zones to your datetime instances. Try out this example to see how to set a datetime instance to have your local time zone:

>>> from dateutil import tz
>>> from datetime import datetime
>>> now = datetime.now(tz=tz.tzlocal())
>>> now
datetime.datetime(2020, 1, 26, 0, 55, 3, 372824, tzinfo=tzlocal())
>>> now.tzname()
'Eastern Standard Time'

In this example, youimport tz from dateutil and datetime from datetime . You then create a datetime instance set to the current time using .now() .

You also pass the tz keyword to .now() and set tz equal to tz.tzlocal() . In dateutil , tz.tzlocal() returns a concrete instance of datetime.tzinfo . This means that it can represent all the necessary time zone offset and daylight saving time information that datetime needs.

You also print the name of the time zone using .tzname() , which prints 'Eastern Standard Time' . This is the output for Windows, but on macOS or Linux, your output might read 'EST' if you’re in the US Eastern time zone during the winter.

You can also create time zones that are not the same as the time zone reported by your computer. To do this, you’ll use tz.gettz() and pass the official IANA name for the time zone you’re interested in. Here’s an example of how to use tz.gettz() :

>>> from dateutil import tz
>>> from datetime import datetime
>>> London_tz = tz.gettz("Europe/London")
>>> now = datetime.now(tz=London_tz)
>>> now
datetime.datetime(2020, 1, 26, 6, 14, 53, 513460, tzinfo=tzfile('GB-Eire'))
>>> now.tzname()
'GMT'

In this example, you use tz.gettz() to retrieve the time zone information for London, United Kingdom and store it in London_tz . You then retrieve the current time, setting the time zone to London_tz .

On Windows, this gives the tzinfo attribute the value tzfile('GB-Eire') . On macOS or Linux, the tzinfo attribute will look something like tzfile('/usr/share/zoneinfo/Europe/London) , but it might be slightly different depending on where dateutil pulls the time zone data from.

You also use tzname() to print the name of the time zone, which is now 'GMT' , meaning Greenwich Mean Time. This output is the same on Windows, macOS, and Linux.

In an earlier, you learned that you shouldn’t use .utcnow() to create a datetime instance at the current UTC. Now you know how to use dateutil.tz to supply a time zone to the datetime instance. Here’s an example modified from the recommendation in the Python documentation:

>>> from dateutil import tz
>>> from datetime import datetime
>>> datetime.now(tz=tz.UTC)
datetime.datetime(2020, 3, 14, 19, 1, 20, 228415, tzinfo=tzutc())

In this code, you use tz.UTC to set the time zone of datetime.now() to the UTC time zone. This method is recommended over using utcnow() because utcnow() returns a naive datetime instance, whereas the method demonstrated here returns an aware datetime instance.

Next, you’ll take a small detour to learn about naive vs aware datetime instances. If you already know all about this, then you canto improve your PyCon countdown with time zone information.

Comparing Naive and Aware Python datetime Instances

Python datetime instances support two types of operation, naive and aware. The basic difference between them is that naive instances don’t contain time zone information, whereas aware instances do. More formally, to quote the Python documentation:

An aware object represents a specific moment in time that is not open to interpretation. A naive object does not contain enough information to unambiguously locate itself relative to other date/time objects. ( Source )

This is an important distinction for working with Python datetime . An aware datetime instance can compare itself unambiguously to other aware datetime instances and will always return the correct time interval when used in arithmetic operations.

Naive datetime instances, on the other hand, may be ambiguous. One example of this ambiguity relates to daylight saving time. Areas that practice daylight saving time turn the clocks forward one hour in the spring and backward one hour in the fall. This typically happens at 2:00 AM local time. In the spring, the hour from 2:00 AM to 2:59 AM never happens , and in the fall, the hour from 1:00 AM to 1:59 AM happens twice !

Practically, what happens is that the offset from UTC in these time zones changes throughout the year. IANA tracks these changes and catalogs them in the different database files that your computer has installed. Using a library like dateutil , which uses the IANA database under the hood, is a great way to make sure that your code properly handles arithmetic with time.

Note:In Python, the difference between naive and aware datetime instances is determined by the tzinfo attribute. An aware datetime instance has the tzinfo attribute equal to a subclass of the datetime.tzinfo abstract base class.

Python provides one concrete implementation of tzinfo called timezone . However, timezone is limited to expressing fixed offsets from UTC that cannot change throughout the year, so it isn’t that useful when you need to account for changes such as daylight saving time.

dateutil also provides several concrete implementations of tzinfo in the tz module that you used earlier. You can check out the dateutil.tz documentation for more information.

This doesn’t mean that you always need to use aware datetime instances. But aware instances are crucial if you’re comparing times with each other, especially if you’re comparing times in different parts of the world.

>>> from datetime import datetime, timedelta
>>> now = datetime.now()
>>> now
datetime.datetime(2020, 1, 26, 9, 37, 46, 380905)
>>> tomorrow = timedelta(days=+1)
>>> now + tomorrow
datetime.datetime(2020, 1, 27, 9, 37, 46, 380905)

>>> yesterday = timedelta(days=-1)
>>> now + yesterday
datetime.datetime(2020, 1, 25, 9, 37, 46, 380905)

>>> delta = timedelta(days=+3, hours=-4)
>>> now + delta
datetime.datetime(2020, 1, 29, 5, 37, 46, 380905)

>>> from dateutil.relativedelta import relativedelta
>>> tomorrow = relativedelta(days=+1)
>>> now + tomorrow
datetime.datetime(2020, 1, 27, 9, 37, 46, 380905)

>>> delta = relativedelta(years=+5, months=+1, days=+3, hours=-4, minutes<