Python datetime

Summary: in this tutorial, you’ll learn how to use the Python datetime module to manipulate dates and times.

Introduction to the Python datetime module #

The datetime is a built-in module that provides classes for manipulating dates and times.

To manipulate dates, you use the date class. For example, the following example creates a new date object with year, month, and day:

from datetime import date

d = date(1999, 12, 31)
print(d)
print(type(d))Copy

Output:

1999-12-31
<class 'datetime.date'>Copy

How it works.

First, import the date class from the datetime module:

from datetime import dateCopy

Second, create a new date object with three integers year, month, and day:

d = date(1999, 12, 31)Copy

Note that if you use integers that are not valid for years, months, and days, you’ll get a ValueError exception.

Third, display the date object and its type:

1999-12-31
<class 'datetime.date'>Copy

Getting the year, month, and day of a date object #

A date object has some useful properties such as year, day, and month:

from datetime import date

d = date(1999, 12, 31)
print(d.year, d.month, d.day)Copy

Output:

1999 12 31Copy

Getting the current date #

To get the current date, you use the today() class method:

from datetime import date

d = date.today()
print(d)Copy

Getting the weekday #

The weekday() returns the day of the week where Monday is zero, Tuesday is one, and so on. The isoweekday() also returns the day of the week but Monday is one, Tuesday is two, and so on. For example:

from datetime import date

d = date(1999, 12, 31)

print(d.weekday())
print(d.isoweekday())Copy

To get the day name based on a weekday, you can use the day_name() function of the calendar module. For example:

import calendar
from datetime import date

d = date(1999, 12, 27)

print(calendar.day_name[d.weekday()])  # Monday

print(d.weekday())  # 0
print(d.isoweekday())  # 1Copy

timedelta #

To represent the difference between two dates, you use the timedelta class. The following creates a new timedelta object:

from datetime import timedelta

delta = timedelta(days=7)
print(delta)Copy

Output:

7 days, 0:00:00Copy

Once having a timedelta object, you can add/subtract it to/from a date object. For example, the following uses a timedelta to add 7 days to a today date:

from datetime import timedelta, date


delta = timedelta(days=7)
next_week = date.today() + delta
print(next_week)Copy

Adding/subtracting two dates #

When you add or subtract two dates, you’ll get a timedelta object. For example, the following shows the number of days to the new year:

from datetime import date

next_year = date.today().year + 1
new_year = date(next_year, 1, 1)
day_to_new_year = new_year - date.today()

print(type(day_to_new_year))
print(day_to_new_year)Copy

How it works.

First, get the new year by adding one to the current year from today’s date:

next_year = date.today().year + 1Copy

Second, create a new date object with the new year date:

new_year = date(next_year, 1, 1)Copy

Third, subtract today’s date from the new year:

day_to_new_year = new_year - date.today()Copy

Finally, show the output:

print(type(day_to_new_year))
print(day_to_new_year)Copy

Output:

<class 'datetime.timedelta'>
93 days, 0:00:00Copy

Note that the number of days when you run the program is likely different.

To get the number of days only from a timedelta, you use the days property:

from datetime import date

next_year = date.today().year + 1
new_year = date(next_year, 1, 1)
day_to_new_year = new_year - date.today()

print(day_to_new_year.days)Copy

Output:

93Copy

Time #

To represent times, you use the time class from the datetime module. For example, the following creates a new time object with hour, minute, second, and microsecond:

from datetime import time


t = time(9, 30, 45, 500)
print(t)Copy

Output:

09:30:45.000500Copy

Like a date object, the time object has the hour, minute, second, and microsecond properties:

from datetime import time


t = time(9, 30, 45, 500)
print(t.hour, t.minute, t.second, t.microsecond)Copy

Output:

9 30 45 500Copy

datetime #

The datetime class represents both dates and times. The following creates a new datetime object with the year, month, day, hour, minute, second, and microsecond:

from datetime import datetime


dt = datetime(1999, 12, 31, 9, 30, 45, 500)
print(dt.date())Copy

Output:

1999-12-31 09:30:45.000500Copy

To get the current time, you use the now() method of the datetime() object:

from datetime import datetime, timedelta


current_time = datetime.now()
print(current_time)Copy

To get a date object out of the datetime object, you use the date() method:

from datetime import datetime


dt = datetime(1999, 12, 31, 9, 30, 45, 500)
print(dt.date())Copy

Output:

1999-12-31Copy

Similarly, the time() method returns the time object of the datetime object:

from datetime import datetime


dt = datetime(1999, 12, 31, 9, 30, 45, 500)
print(dt.time())Copy

Output:

09:30:45.000500Copy

Like date and time objects, you can add/subtract a timedelta to/from a datetime object. For example:

from datetime import datetime


current_time = datetime.now()
print(current_time)Copy

Output:

2000-01-01 14:30:45.000500Copy

In this example, we add 1 day and 5 hours to a datetime object.

To get the current in UTC, you use the utcnow() method:

from datetime import datetime


current_time = datetime.utcnow()
print(current_time)Copy

Formatting dates & times #

The date, time, and datetime objects have the strftime() method that formats date, time, and datetime. It accepts an argument (format):

strftime(format)Copy

The format argument contains directives for formatting dates and times. The following table shows the format directives:

For example, the following shows how to use the strftime() method to format a date time:

from datetime import datetime


dt = datetime(1999, 12, 31, 9, 30, 45)
s = dt.strftime('%B %m, %Y %I:%M %p')
print(s)Copy

Output:

December 12, 1999 09:30 AMCopy

Convert a string to date & time #

The strptime() is a class method of the datetime class, which parses a string with a given format to a datetime object:

strptime(date_string, format)Copy

For example:

from datetime import datetime


dt = datetime.strptime('August 13, 2022', '%B %d, %Y')
print(dt)Copy

Output:

2022-08-13 00:00:00Copy

Summary #

• Use the date class to represent dates.
• Use the time class to represent times.
• Use the datetime class to represent both dates and times.
• Use the timedelta class to represent a time delta.
• Use the strftime() method to format a date, a time, or a datetime object.
• Use the strptime() method to parse a string into a datetime object.