Python Datetime Module

The Datetime module allows us to work with date and time objects. It provides three additional data types: date, time and datetime.

import datetime

date()

datetime.date(year: int, month: int, day: int)

The date method return a date object with the year, month and day attributes:

from datetime import date
# Create a date object
obj = date(2022, 12, 1)
# Access year attribute
obj.year

2022

obj.month

12

obj.day

1

time()

datetime.time(hour: int, minute: int, second: int)

The time method return a time object with the hour, minute, second, microsecond and tzinfo attributes:

from datetime import time
# Create a time object
obj = time(10, 20, 33)
# Access hour attribute
obj.hour

10

obj.second

33

obj.microsecond

0

datetime()

datetime.datetime(year, month, day, hour, minute, second)

The datetime returns an object with both, the date and time objects attributes:

from datetime import datetime
# Create a datetime object with date and time
obj = datetime(2024, 12, 1, 15, 35, 59)
# Access year attribute
obj.year

2024

obj.month

12

obj.day

1

obj.hour

15

obj.second

59

now() and today()

now and today methods return a datetime object with system’s exact day and time:

from datetime import datetime
# Get current date and time
now = datetime.now()
now

datetime.datetime(2022, 7, 23, 19, 56, 49, 589806)

Because the object returned is a datetime, we can access both, date and time attributes:

now.date()

datetime.date(2022, 7, 23)

now.time()

datetime.time(19, 56, 49, 589806)

now.year

2022

now.month

7

now.day

23

now.hour

19

now.minute

56

now.second

49

now.microsecond

589806

Additionally, now can take a timezone object as an optional parameter:

from datetime import datetime, timezone
# Get current UTC time
datetime.now(timezone.utc)

datetime.datetime(2022, 7, 24, 0, 20, 8, 265634, tzinfo=datetime.timezone.utc)

If a timezone parameter is not specified, now will default to the system timezone.

strftime() and strptime()

You can easily transform between strings and datetime objects with the strftime and strptime methods.

strftime()

strftime allow us to create human formatted strings out of a Python datetime object:

from datetime import datetime
# Get current datetime for formatting examples
now = datetime.now()
now

datetime.datetime(2022, 7, 23, 20, 31, 19, 751479)

# Format datetime as day-month-year with abbreviated month
now.strftime("%d-%b-%Y")

'23-Jul-2022'

# Format datetime as day-month-year with numeric month
now.strftime("%d-%m-%Y")

'23-07-2022'

# Format datetime as month/day/year
now.strftime("%m/%d/%Y")

'07/23/2022'

# Format datetime with date and time
now.strftime("%b/%d/%Y - %H:%M:%S")

'Jul/23/2022 - 20:31:19'

You may find the strings passed to strftime to be a little strange, but it is pretty easy to understand its meaning. For example, %m/%d/%Y will return the month, day, and year separated by / (07/23/2022).

strptime()

The strptime method creates a datetime object from a string.

This method accepts two parameters:

obj.strptime(datetime_string, format)

• A string representing a datetime object.
• The python format code equivalent to that string.

from datetime import datetime

# Parse string to datetime object
datetime_str = '12-Jul-2023'
datetime.strptime(datetime_str, '%d-%b-%Y')

datetime.datetime(2023, 7, 12, 0, 0)

# Parse string with date and time
datetime_str = 'Jul/12/2023 - 14:38:37'
datetime.strptime(datetime_str, "%b/%d/%Y - %H:%M:%S")

datetime.datetime(2023, 7, 12, 14, 38, 37)

Format Codes

timedelta()

The timedelta object represents the difference between two dates or times.

from datetime import datetime

# Create two datetime objects
date_1 = datetime.strptime('12-Jul-2023', '%d-%b-%Y')
date_2 = datetime.strptime('01-Jan-2024', '%d-%b-%Y')

# Calculate difference (returns timedelta)
difference = date_2 - date_1
difference

datetime.timedelta(days=173)

# Get number of days from timedelta
difference.days

173

timedelta can add days, seconds and microseconds to a datetime object:

from datetime import datetime, timedelta

# Get current datetime for timedelta operations
now = datetime.now()
now

datetime.datetime(2022, 7, 23, 21, 25, 2, 341081)

# Add 10 days and 15 seconds to current datetime
now + timedelta(days=10, seconds=15)

datetime.datetime(2022, 8, 2, 21, 25, 17, 341081)

And can subtract days, seconds and microseconds to a datetime object:

from datetime import datetime, timedelta

# Get current datetime for subtraction example
now = datetime.now()
now

datetime.datetime(2022, 7, 23, 21, 25, 2, 341081)

# Subtract 10 days and 15 seconds from current datetime
now - timedelta(days=10, seconds=15)

datetime.datetime(2022, 7, 13, 21, 59, 41, 100883)

Relevant links

• Cheatsheet: String Formatting
• Blog: Python Data Types
• str()
• format()
• print()