Functions

parser.parse(parserinfo=None,**kwargs)[source]

Parse a string in one of the supported formats, using theparserinfo parameters.

Parameters:

• timestr – A string containing a date/time stamp.

• parserinfo – Aparserinfo object containing parameters for the parser.IfNone, the default arguments to theparserinfoconstructor are used.

The**kwargs parameter takes the following keyword arguments:

Parameters:

• default – The default datetime object, if this is a datetime object and notNone, elements specified intimestr replace elements in thedefault object.

• ignoretz – If setTrue, time zones in parsed strings are ignored and a naivedatetime object is returned.

• tzinfos –

  Additional time zone names / aliases which may be present in thestring. This argument maps time zone names (and optionally offsetsfrom those time zones) to time zones. This parameter can be adictionary with timezone aliases mapping time zone names to timezones or a function taking two parameters (tzname andtzoffset) and returning a time zone.

  The timezones to which the names are mapped can be an integeroffset from UTC in seconds or atzinfo object.

   >>> from dateutil.parser import parse >>> from dateutil.tz import gettz >>> tzinfos = {"BRST": -7200, "CST": gettz("America/Chicago")} >>> parse("2012-01-19 17:21:00 BRST", tzinfos=tzinfos) datetime.datetime(2012, 1, 19, 17, 21, tzinfo=tzoffset(u'BRST', -7200)) >>> parse("2012-01-19 17:21:00 CST", tzinfos=tzinfos) datetime.datetime(2012, 1, 19, 17, 21,                   tzinfo=tzfile('/usr/share/zoneinfo/America/Chicago'))

  This parameter is ignored ifignoretz is set.

• dayfirst – Whether to interpret the first value in an ambiguous 3-integer date(e.g. 01/05/09) as the day (True) or month (False). Ifyearfirst is set toTrue, this distinguishes between YDM andYMD. If set toNone, this value is retrieved from the currentparserinfo object (which itself defaults toFalse).

• yearfirst – Whether to interpret the first value in an ambiguous 3-integer date(e.g. 01/05/09) as the year. IfTrue, the first number is taken tobe the year, otherwise the last number is taken to be the year. Ifthis is set toNone, the value is retrieved from the currentparserinfo object (which itself defaults toFalse).

• fuzzy – Whether to allow fuzzy parsing, allowing for string like “Today isJanuary 1, 2047 at 8:21:00AM”.

• fuzzy_with_tokens –

  IfTrue,fuzzy is automatically set to True, and the parserwill return a tuple where the first element is the parseddatetime.datetime datetimestamp and the second element isa tuple containing the portions of the string which were ignored:

  >>>fromdateutil.parserimportparse>>>parse("Today is January 1, 2047 at 8:21:00AM",fuzzy_with_tokens=True)(datetime.datetime(2047, 1, 1, 8, 21), (u'Today is ', u' ', u'at '))

Returns:

Returns adatetime.datetime object or, if thefuzzy_with_tokens option isTrue, returns a tuple, thefirst element being adatetime.datetime object, the seconda tuple containing the fuzzy tokens.

Raises:

• ParserError – Raised for invalid or unknown string formats, if the providedtzinfo is not in a valid format, or if an invalid date wouldbe created.

• OverflowError – Raised if the parsed date exceeds the largest valid C integer onyour system.

parser.isoparse(dt_str)

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

An ISO-8601 datetime string consists of a date portion, followedoptionally by a time portion - the date and time portions are separatedby a single character separator, which isT in the officialstandard. Incomplete date formats (such asYYYY-MM) maynot becombined with a time portion.

Supported date formats are:

Common:

• YYYY

• YYYY-MM

• YYYY-MM-DD orYYYYMMDD

Uncommon:

• YYYY-Www orYYYYWww - ISO week (day defaults to 0)

• YYYY-Www-D orYYYYWwwD - ISO week and day

The ISO week and day numbering follows the same logic asdatetime.date.isocalendar().

Supported time formats are:

• hh

• hh:mm orhhmm

• hh:mm:ss orhhmmss

• hh:mm:ss.ssssss (Up to 6 sub-second digits)

Midnight is a special case forhh, as the standard supports both00:00 and 24:00 as a representation. The decimal separator can beeither a dot or a comma.

Caution

Support for fractional components other than seconds is part of theISO-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 asdateutil.tz.tzoffset objects,with the exception of UTC, which will be represented asdateutil.tz.tzutc. Time zone offsets equivalent to UTC (suchas+00:00) will also be represented asdateutil.tz.tzutc.

Parameters:

dt_str – A string or stream containing only an ISO-8601 datetime string

Returns:

Returns adatetime.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 beconsidered a stable part of the contract. Any valid ISO-8601 stringthat parses correctly with the default settings will continue toparse correctly in future versions, but invalid strings thatcurrently fail (e.g.2017-01-01T00:00+00:00:00) are notguaranteed to continue failing in future versions if they encodea valid date.

New in version 2.7.0.

Classes

classdateutil.parser.parserinfo(dayfirst=False,yearfirst=False)[source]

Class which handles what inputs are accepted. Subclass this to customizethe language and acceptable values for each parameter.

Parameters:

• dayfirst – Whether to interpret the first value in an ambiguous 3-integer date(e.g. 01/05/09) as the day (True) or month (False). Ifyearfirst is set toTrue, this distinguishes between YDMand YMD. Default isFalse.

• yearfirst – Whether to interpret the first value in an ambiguous 3-integer date(e.g. 01/05/09) as the year. IfTrue, the first number is takento be the year, otherwise the last number is taken to be the year.Default isFalse.

AMPM=[('am','a'),('pm','p')]

HMS=[('h','hour','hours'),('m','minute','minutes'),('s','second','seconds')]

JUMP=['','.',',',';','-','/',"'",'at','on','and','ad','m','t','of','st','nd','rd','th']

MONTHS=[('Jan','January'),('Feb','February'),('Mar','March'),('Apr','April'),('May','May'),('Jun','June'),('Jul','July'),('Aug','August'),('Sep','Sept','September'),('Oct','October'),('Nov','November'),('Dec','December')]

PERTAIN=['of']

TZOFFSET={}

UTCZONE=['UTC','GMT','Z','z']

WEEKDAYS=[('Mon','Monday'),('Tue','Tuesday'),('Wed','Wednesday'),('Thu','Thursday'),('Fri','Friday'),('Sat','Saturday'),('Sun','Sunday')]

ampm(name)[source]

convertyear(year,century_specified=False)[source]

Converts two-digit years to year within [-50, 49]range of self._year (current local time)

hms(name)[source]

jump(name)[source]

month(name)[source]

pertain(name)[source]

tzoffset(name)[source]

utczone(name)[source]

validate(res)[source]

weekday(name)[source]

Warnings and Exceptions

classdateutil.parser.ParserError[source]

Exception subclass used for any failure to parse a datetime string.

This is a subclass ofValueError, and should be raised any timeearlier versions ofdateutil would have raisedValueError.

New in version 2.8.1.

classdateutil.parser.UnknownTimezoneWarning[source]

Raised when the parser finds a timezone it cannot parse into a tzinfo.

New in version 2.7.0.