This module offers a parser for ISO-8601 strings

It is intended to support all valid date, time and datetime formats per the ISO-8601 specification.

..versionadded:: 2.7.0

Module Contents




class isoparser(sep=None)

A single character that separates date and time portions. If None, the parser will accept any single character. For strict ISO-8601 adherence, pass 'T'.


Parse an ISO-8601 datetime string into a datetime.datetime.

An ISO-8601 datetime string consists of a date portion, followed optionally by a time portion - the date and time portions are separated by a single character separator, which is T in the official standard. Incomplete date formats (such as YYYY-MM) may not be combined with a time portion.

Supported date formats are:


  • YYYY


  • YYYY-Www or YYYYWww - ISO week (day defaults to 0)
  • YYYY-Www-D or YYYYWwwD - ISO week and day

The ISO week and day numbering follows the same logic as

Supported time formats are:

  • hh
  • hh:mm or hhmm
  • hh:mm:ss or hhmmss
  • hh:mm:ss.sss or hh:mm:ss.ssssss (3-6 sub-second digits)

Midnight is a special case for hh, as the standard supports both 00:00 and 24:00 as a representation.


Support for fractional components other than seconds is part of the ISO-8601 standard, but is not currently implemented in this parser.

Supported time zone offset formats are:

  • Z (UTC)
  • ±HH:MM
  • ±HHMM
  • ±HH

Offsets will be represented as objects, with the exception of UTC, which will be represented as Time zone offsets equivalent to UTC (such as +00:00) will also be represented as

Parameters:dt_str – A string or stream containing only an ISO-8601 datetime string
Returns:Returns a datetime.datetime representing the string. Unspecified components default to their lowest value.


As of version 2.7.0, the strictness of the parser should not be considered a stable part of the contract. Any valid ISO-8601 string that parses correctly with the default settings will continue to parse correctly in future versions, but invalid strings that currently fail (e.g. 2017-01-01T00:00+00:00:00) are not guaranteed to continue failing in future versions if they encode a valid date.

New in version 2.7.0.


Parse the date portion of an ISO string.

Parameters:datestr – The string portion of an ISO string, without a separator
Returns:Returns a object

Parse the time portion of an ISO string.

Parameters:timestr – The time portion of an ISO string, without a separator
Returns:Returns a datetime.time object
parse_tzstr(tzstr, zero_as_utc=True)

Parse a valid ISO time zone string.

See isoparser.isoparse() for details on supported formats.

  • tzstr – A string representing an ISO time zone offset
  • zero_as_utc – Whether to return for zero-offset zones

Returns for offsets and for Z and (if zero_as_utc is specified) offsets equivalent to UTC.

_calculate_weekdate(year, week, day)

Calculate the day of corresponding to the ISO year-week-day calendar.

This function is effectively the inverse of

  • year – The year in the ISO calendar
  • week – The week in the ISO calendar - range is [1, 53]
  • day – The day in the ISO calendar - range is [1 (MON), 7 (SUN)]

Returns a

_parse_tzstr(tzstr, zero_as_utc=True)