Python datetime isoformat() method

The datetime.isoformat() method in Python’s datetime module returns a string representing the date and time in ISO 8601 format.

ISO 8601 Format

Different cultures around the world have their own conventions for formatting dates. For example, the United States typically uses the month-day-year format (01-05-2024), while many European countries use the day-month-year format (05-01-2024). These variations can lead to miscommunication, especially in international contexts.

To address this, the International Organization for Standardization (ISO) created the ISO 8601 standard. This standard establishes a clear and unambiguous date and time format, with components arranged from most significant to least:

YYYY-MM-DDTHH:MM:SS.mmmmmm

Syntax

datetime.isoformat(sep=’T’, timespec=’auto’)

Parameters

Parameter	Condition	Description
sep	Optional	A one-character separator, placed between the date and time portions of the result. Default value is ‘T’.
timespec	Optional	specifies the number of additional components of the time to include. It accepts the following values: ‘auto’ (default): Same as ‘seconds’ if microsecond is 0, same as ‘microseconds’ otherwise. ‘hours’: Include the hour in the two-digit HH format. ‘minutes’: Include hour and minute in HH:MM format. ‘seconds’: Include hour, minute, and second in HH:MM:SS format. ‘milliseconds’: Include full time, but truncate fractional second part to milliseconds. HH:MM:SS.sss format. ‘microseconds’: Include full time in HH:MM:SS.ffffff format.

Return Value

The method returns a string representing the datetime object in ISO 8601 format. The precision of the time part is determined by the timespec argument.

Getting the Current Time in ISO 8601 format

Python’s datetime module makes it easy to get the current time in ISO 8601 format. Simply use the now() method within the module to retrieve a datetime object representing the current local date and time. Then, call the isoformat() method directly on this object.

from datetime import datetime

# Get the current date and time
dt = datetime.now()

# Print the datetime object in ISO 8601 format
print(dt.isoformat())
# Output: 2024-03-06T19:21:41.129147

Converting Specific Date and Time to ISO 8601 Format

To get the ISO 8601 format representation of a specific date and time, you can instantiate a datetime object by specifying the year, month, day, hour, minute, second, and microsecond. And then use the isoformat() method.

from datetime import datetime

# Example datetime with microseconds
dt = datetime(2023, 4, 5, 12, 30, 45, 123456)

# Print the datetime object in ISO 8601 format
print(dt.isoformat())
# Output: 2023-04-05T12:30:45.123456

Specifying a separator

The sep parameter specifies the separator character used to separate the date and time within the ISO 8601 formatted string. By default, this separator is the letter ‘T’. However, it can be changed to any other character based on your requirement.

from datetime import datetime

# Example datetime
dt = datetime(2023, 4, 5, 12, 30, 45)

print(dt.isoformat())         # Output: 2023-04-05T12:30:45 (Default )
print(dt.isoformat(sep=' '))  # Output: 2023-04-05 12:30:45
print(dt.isoformat(sep='_'))  # Output: 2023-04-05_12:30:45

Specifying timespec for different precisions

The timespec parameter specifies the number of additional components of the time to include. By adjusting this parameter, you can customize whether the output includes only hours, hours and minutes, seconds, or even milliseconds and microseconds.

The timespec parameter accepts the following values:

‘auto’ (default): Same as ‘seconds’ if microsecond is 0, same as ‘microseconds’ otherwise.
‘hours’: Include the hour in the two-digit HH format.
‘minutes’: Include hour and minute in HH:MM format.
‘seconds’: Include hour, minute, and second in HH:MM:SS format.
‘milliseconds’: Include full time, but truncate fractional second part to milliseconds. HH:MM:SS.sss format.
‘microseconds’: Include full time in HH:MM:SS.ffffff format.

from datetime import datetime

# Example datetime with microseconds
dt = datetime(2023, 4, 5, 12, 30, 45, 123456)

# Default (auto) behavior includes microseconds if present
print(dt.isoformat())  # Output: '2023-04-05T12:30:45.123456'

# Specifying different levels of precision
print(dt.isoformat(timespec='hours'))         # Output: '2023-04-05T12'
print(dt.isoformat(timespec='minutes'))       # Output: '2023-04-05T12:30'
print(dt.isoformat(timespec='seconds'))       # Output: '2023-04-05T12:30:45'
print(dt.isoformat(timespec='milliseconds'))  # Output: '2023-04-05T12:30:45.123'
print(dt.isoformat(timespec='microseconds'))  # Output: '2023-04-05T12:30:45.123456'