Using Python datetime to Work With Dates and Times

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.

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, you import 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 little later on how 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 as integers, 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.

Using Strings to Create Python datetime Instances

Another way to create date instances is to use .fromisoformat(). To use this method, you provide a string with the date in the ISO 8601 format that you learned about earlier. 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)
 5datetime.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")
 3datetime.datetime(2020, 3, 13, 14, 39, 1, 350918)
 4>>> dateparser.parse("morgen")
 5datetime.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, you import 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 section, 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 can skip ahead to 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.

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.

Using relativedelta in Your PyCon Countdown

First, replace the plain subtraction operator with relativedelta. With the subtraction operator, your timedelta object couldn’t count intervals of time larger than a day. However, relativedelta allows you to show the years, months, and days remaining:

 1# pyconcd.py
 2
 3from dateutil import parser, tz
 4from dateutil.relativedelta import relativedelta
 5from datetime import datetime
 6
 7PYCON_DATE = parser.parse("May 12, 2021 8:00 AM")
 8PYCON_DATE = PYCON_DATE.replace(tzinfo=tz.gettz("America/New_York"))
 9now = datetime.now(tz=tz.tzlocal())
10
11countdown = relativedelta(PYCON_DATE, now)
12print(f"Countdown to PyCon US 2021: {countdown}")

The only change that you made in this code was to replace line 11 with countdown = relativedelta(PYCON_DATE, now). The output from this script should tell you that PyCon US 2021 will happen in about one year and one month, depending on when you run the script.

However, that output isn’t very pretty since it looks like the signature of relativedelta(). You can build up some prettier output by replacing line 11 in the previous code with the code below:

11def time_amount(time_unit: str, countdown: relativedelta) -> str:
12    t = getattr(countdown, time_unit)
13    return f"{t} {time_unit}" if t != 0 else ""
14
15countdown = relativedelta(PYCON_DATE, now)
16time_units = ["years", "months", "days", "hours", "minutes", "seconds"]
17output = (t for tu in time_units if (t := time_amount(tu, countdown)))
18print("Countdown to PyCon US 2021:", ", ".join(output))

This code requires Python 3.8 because it uses the new walrus operator. You can make this script work on older versions of Python by using a traditional for loop in place of line 17.

In this code, you define time_amount(), which takes two arguments, the unit of time and the relativedelta instance from which the time units should be retrieved. If the amount of time is not equal to zero, then time_amount() returns a string with the amount of time and the time unit. Otherwise, it returns an empty string.

You use time_amount() in the comprehension on line 17. That line creates a generator storing the non-empty strings returned from time_amount(). It uses the walrus operator to assign the return value of time_amount() to t and includes t only if it is True.

Finally, line 18 prints the final output using .join() on the generator. Next, you’ll take a look at including the PyCon date in the output from your script.

Showing the PyCon Date in Your PyCon Countdown

Earlier, you learned about creating datetime instances using .strptime(). This method uses a special mini-language within Python to specify how the date string is formatted.

Python datetime has an additional method called .strftime() that allows you to format a datetime instance to a string. In a sense, it’s the reverse operation of parsing using .strptime(). You can differentiate between the two methods by remembering that the p in .strptime() stands for parse, and the f in .strftime() stands for format.

In your PyCon countdown, you can use .strftime() to print output to let the user know the date on which PyCon US will start. Remember, you can find the formatting codes that you want to use on strftime.org. Now add this code on line 18 of your PyCon countdown script:

18pycon_date_str = PYCON_DATE.strftime("%A, %B %d, %Y at %H:%M %p %Z")
19print(f"PyCon US 2021 will start on:", pycon_date_str)
20print("Countdown to PyCon US 2021:", ", ".join(output))

In this code, line 18 uses .strftime() to create a string representing the starting date of PyCon US 2021. The output includes the weekday, month, day, year, hour, minute, AM or PM, and time zone:

Wednesday, May 12, 2021 at 08:00 AM EDT

On line 19, you print this string for the user to see with some explanatory text. The last line prints the amount of time remaining until the PyCon start date. Next, you’ll finish your script to make it easier for other people to reuse.

Finalizing Your PyCon Countdown

The final step that you’ll want take is to follow Python best practices and put the code that produces output into a main() function. You can check out the full, final code after applying all these changes:

 1# pyconcd.py
 2
 3from dateutil import parser, tz
 4from dateutil.relativedelta import relativedelta
 5from datetime import datetime
 6
 7PYCON_DATE = parser.parse("May 12, 2021 8:00 AM")
 8PYCON_DATE = PYCON_DATE.replace(tzinfo=tz.gettz("America/New_York"))
 9
10def time_amount(time_unit: str, countdown: relativedelta) -> str:
11    t = getattr(countdown, time_unit)
12    return f"{t} {time_unit}" if t != 0 else ""
13
14def main():
15    now = datetime.now(tz=tz.tzlocal())
16    countdown = relativedelta(PYCON_DATE, now)
17    time_units = ["years", "months", "days", "hours", "minutes", "seconds"]
18    output = (t for tu in time_units if (t := time_amount(tu, countdown)))
19    pycon_date_str = PYCON_DATE.strftime("%A, %B %d, %Y at %H:%M %p %Z")
20    print(f"PyCon US 2021 will start on:", pycon_date_str)
21    print("Countdown to PyCon US 2021:", ", ".join(output))
22
23if __name__ == "__main__":
24    main()

In this code, you move print() and the code used for the generator into main(). On line 23, you use the guard clause to make sure that main() only runs when this file is executed as a script. This allows other people to import your code and reuse PYCON_DATE, for instance, if they’d like.

Now you can modify this script as much as you want. One neat thing to do might be to allow the user to change the time zone associated with now by passing a command-line argument. You could also change the PYCON_DATE to something closer to home, say PyCon Africa or EuroPython.

To get even more excited about PyCon, check out Real Python at PyCon US 2019 and How to Get the Most Out of PyCon!