to_datetime

Collection Note

This module is part of the ansible.builtin collection. To install the collection, use:

ansible-galaxy collection install ansible.builtin

Added in version 2.4.

Synopsis

• Using the input string attempt to create a matching Python C(datetime) object.
• Adding or Subtracting two datetime objects will result in a Python C(timedelta) object.

Parameters

Parameter	Defaults / Choices	Comments
_input str required		A string containing date time information.
format str		C(strformat) formatted string that describes the expected format of the input string.

Notes

Note

• For a full list of format codes for working with Python date format strings, see L(the Python documentation, https://docs.python.org/3/library/datetime.html#strftime-and-strptime-behavior).
• The timedelta object produced by the difference of two datetimes store the days, seconds, and microseconds of the delta. This results in the C(seconds) attribute being the total seconds of the minutes and hours of that delta. See L(datatime.timedelta, https://docs.python.org/3/library/datetime.html#timedelta-objects) for more information about how a timedelta works.

Examples

# Get total amount of seconds between two dates. Default date format is %Y-%m-%d %H:%M:%S but you can pass your own format
secsdiff: '{{ (("2016-08-14 20:00:12" | to_datetime) - ("2015-12-25" | to_datetime("%Y-%m-%d"))).total_seconds()  }}'

# Get remaining seconds after delta has been calculated. NOTE: This does NOT convert years and days to seconds. For that, use total_seconds()
{{ (("2016-08-14 20:00:12" | to_datetime) - ("2016-08-14 18:00:00" | to_datetime)).seconds  }}
# This expression evaluates to "7212". Delta is 2 hours, 12 seconds

# get amount of days between two dates. This returns only number of days and discards remaining hours, minutes, and seconds
{{ (("2016-08-14 20:00:12" | to_datetime) - ("2015-12-25" | to_datetime('%Y-%m-%d'))).days  }}

# difference between to dotnet (100ns precision) and iso8601 microsecond timestamps
# the date1_short regex replace will work for any timestamp that has a higher than microsecond precision
# by cutting off anything more precise than microseconds
vars:
  date1: '2022-11-15T03:23:13.6869568Z'
  date2: '2021-12-15T16:06:24.400087Z'
  date1_short: '{{ date1|regex_replace("([^.]+)(\.\d{6})(\d*)(.+)", "\1\2\4") }}' # shorten to microseconds
  iso8601format: '%Y-%m-%dT%H:%M:%S.%fZ'
  date_diff_isoed: '{{ (date1_short|to_datetime(iso8601format) - date2|to_datetime(iso8601format)).total_seconds() }}'

Return Values

Key	Data Type	Description	Returned
_value	raw	C(datetime) object from the represented value.