parser.isoparser

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

Classes

isoparser(self,sep=None)

Functions

_takes_ascii(f)
_takes_ascii(f)
class isoparser(sep=None)
__init__(sep=None)
Parameters:sep

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'.

isoparse(dt_str)

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:

Common:

  • YYYY
  • YYYY-MM or YYYYMM
  • YYYY-MM-DD or YYYYMMDD

Uncommon:

  • 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 datetime.date.isocalendar().

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.

Caution

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 dateutil.tz.tzoffset objects, with the exception of UTC, which will be represented as dateutil.tz.tzutc. Time zone offsets equivalent to UTC (such as +00:00) will also be represented as dateutil.tz.tzutc.

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.

Warning

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_isodate(datestr)

Parse the date portion of an ISO string.

Parameters:datestr – The string portion of an ISO string, without a separator
Returns:Returns a datetime.date object
parse_isotime(timestr)

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.

Parameters:
  • tzstr – A string representing an ISO time zone offset
  • zero_as_utc – Whether to return dateutil.tz.tzutc for zero-offset zones
Returns:

Returns dateutil.tz.tzoffset for offsets and dateutil.tz.tzutc for Z and (if zero_as_utc is specified) offsets equivalent to UTC.

_parse_isodate(dt_str)
_parse_isodate_common(dt_str)
_parse_isodate_uncommon(dt_str)
_calculate_weekdate(year, week, day)

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

This function is effectively the inverse of datetime.date.isocalendar().

Parameters:
  • 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:

Returns a datetime.date

_parse_isotime(timestr)
_parse_tzstr(tzstr, zero_as_utc=True)