# The Python datetime module

The datetime module is a module in Python standard library that allows us to work with dates and times easily. Inside the module we can find a few classes, but the most used ones are datetime and timedelta.

This usually means that we work with the datetime class inside the datetime module—somewhat confusing, but you'll see datetime.datetime fairly often when reading Python code.

# What is a datetime object?

Put simply, a datetime object is one that stores information about a specific point in time. Information such as year, month, day, hour, minute, and second. With all that information, we can use a datetime object to refer to one particular moment in time. For example:

import datetime

today = datetime.datetime(year=2019, month=12, day=23, hour=11, minute=49, second=30)
print(today)  # 2019-12-23 11:49:30

In addition to storing data about the specific point in time, it also has methods that help us interact with or process that data in a way that makes sense.

For example, given two datetime objects you can compare them to see which one is further into the future.

import datetime

today = datetime.datetime(year=2019, month=12, day=23, hour=11, minute=49, second=30)
tomorrow = datetime.datetime(year=2019, month=12, day=24, hour=11, minute=49, second=30)
print(today > tomorrow)  # False

Here we would print False because today is in the past, relative to tomorrow. This is how we can compare two dates, for example to tell whether something happened in the past.

# How to get today's date

Because getting today's date is so common, the datetime class comes with a method you can use to get a new datetime object for today's date:

import datetime

# 2019-12-23 11:54:13.151509

You can also use datetime.datetime.today() to get the current time and date, but it can sometimes be less precise. Also, it doesn't allow us to give it timezone information (more on that later!)

Notice that when we're doing this, we get microseconds as well as the other time measures. This can be unnecessary, but when dealing with computers it can sometimes be useful.

# How to display dates

You can print dates or convert them to strings by using the built-in str() function, so that they'll be shown in this format:

import datetime

# 2019-12-23 11:54:13.151509

Sometimes you may want more flexibility regarding how you print a date out. Maybe you only want to print out the date portion. Or maybe just "hours and minutes".

You can do this by using .strftime(), which stands for "string format time".

import datetime

today = datetime.datetime.now()

# 2019-12-23

# 11:54

Doing this does not modify the today object at all, it just creates a string representing the date or time as dictated by the provided "format string".

This is a good reference for all the different things you can pass to strftime: https://strftime.org/ (opens new window).

# How to parse dates

Very similarly to printing dates with a specific format, we can read in dates with a specific format.

For example, let's say your user gives you a string describing today's date: 23-12-2019. Clearly this string is in the format "day-month-year". In Python datetime format: "%d-%m-%Y".

We can use .strptime to parse a date string into a datetime object:

import datetime

user_date = input("Enter today's date: ")
# Assume they entered 23-12-2019

today = datetime.datetime.strptime(user_date, "%d-%m-%Y")
print(today)  # 2019-12-23 00:00:00

The same format strings as we used for strftime can be used in strptime.

# What is a timestamp?

A timestamp is the number of seconds that have passed since 1st January, 1970, at midnight[1].

We use timestamps because it's easier to work with a single number (albeit a large one) than with many numbers each describing a different measurement.

The timestamp for "2nd January, 1970, at midnight" would be 86400: the number of seconds in one day.

To get a timestamp you can call the timestamp() method of any datetime object:

import datetime

today = datetime.datetime.now()
print(today.timestamp())  # 1577104357.558527

Because it is so common to get the timestamp of right now, we can use the time module to get it more easily:

import time

print(time.time())  # 1577104492.7515678

  1. Why does Unix time start at 1970-01-01? (opens new window) ↩︎