parser¶
This module offers a generic date/time string parser which is able to parse most known formats to represent a date and/or time.
This module attempts to be forgiving with regards to unlikely input formats, returning a datetime object even for dates which are ambiguous. If an element of a date/time stamp is omitted, the following rules are applied: - If AM or PM is left unspecified, a 24-hour clock is assumed, however, an hour
on a 12-hour clock (0 <= hour <= 12
) must be specified if AM or PM is specified.
- If a time zone is omitted, a timezone-naive datetime is returned.
If any other elements are missing, they are taken from the
datetime.datetime
object passed to the parameter default
. If this
results in a day number exceeding the valid number of days per month, the
value falls back to the end of the month.
Additional resources about date/time string formats can be found below:
- A summary of the international standard date and time notation
- W3C Date and Time Formats
- Time Formats (Planetary Rings Node)
- CPAN ParseDate module
- Java SimpleDateFormat Class
-
dateutil.parser.
parse
(timestr, parserinfo=None, **kwargs)[source]¶ Parse a string in one of the supported formats, using the
parserinfo
parameters.Parameters: - timestr – A string containing a date/time stamp.
- parserinfo – A
parserinfo
object containing parameters for the parser. IfNone
, the default arguments to theparserinfo
constructor are used.
The
**kwargs
parameter takes the following keyword arguments:Parameters: - default – The default datetime object, if this is a datetime object and not
None
, elements specified intimestr
replace elements in the default object. - ignoretz – If set
True
, time zones in parsed strings are ignored and a naivedatetime
object is returned. - tzinfos –
Additional time zone names / aliases which may be present in the string. This argument maps time zone names (and optionally offsets from those time zones) to time zones. This parameter can be a dictionary with timezone aliases mapping time zone names to time zones or a function taking two parameters (
tzname
andtzoffset
) and returning a time zone.The timezones to which the names are mapped can be an integer offset from UTC in minutes or a
tzinfo
object.>>> from dateutil.parser import parse >>> from dateutil.tz import gettz >>> tzinfos = {"BRST": -10800, "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', -10800)) >>> 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 if
ignoretz
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 and YMD. 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. If
True
, the first number is taken to be the year, otherwise the last number is taken to be the year. If this 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 is January 1, 2047 at 8:21:00AM”.
- fuzzy_with_tokens –
If
True
,fuzzy
is automatically set to True, and the parser will return a tuple where the first element is the parseddatetime.datetime
datetimestamp and the second element is a tuple containing the portions of the string which were ignored:>>> from dateutil.parser import parse >>> parse("Today is January 1, 2047 at 8:21:00AM", fuzzy_with_tokens=True) (datetime.datetime(2011, 1, 1, 8, 21), (u'Today is ', u' ', u'at '))
Returns: Returns a
datetime.datetime
object or, if thefuzzy_with_tokens
option isTrue
, returns a tuple, the first element being adatetime.datetime
object, the second a tuple containing the fuzzy tokens.Raises: - ValueError – Raised for invalid or unknown string format, if the provided
tzinfo
is not in a valid format, or if an invalid date would be created. - OverflowError – Raised if the parsed date exceeds the largest valid C integer on your system.
-
class
dateutil.parser.
parserinfo
(dayfirst=False, yearfirst=False)[source]¶ Class which handles what inputs are accepted. Subclass this to customize the 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 YDM and YMD. Default isFalse
. - yearfirst – Whether to interpret the first value in an ambiguous 3-integer date
(e.g. 01/05/09) as the year. If
True
, the first number is taken to be the year, otherwise the last number is taken to be the year. Default isFalse
.
-
AMPM
= [(u'am', u'a'), (u'pm', u'p')]¶
-
HMS
= [(u'h', u'hour', u'hours'), (u'm', u'minute', u'minutes'), (u's', u'second', u'seconds')]¶
-
JUMP
= [u' ', u'.', u',', u';', u'-', u'/', u"'", u'at', u'on', u'and', u'ad', u'm', u't', u'of', u'st', u'nd', u'rd', u'th']¶
-
MONTHS
= [(u'Jan', u'January'), (u'Feb', u'February'), (u'Mar', u'March'), (u'Apr', u'April'), (u'May', u'May'), (u'Jun', u'June'), (u'Jul', u'July'), (u'Aug', u'August'), (u'Sep', u'Sept', u'September'), (u'Oct', u'October'), (u'Nov', u'November'), (u'Dec', u'December')]¶
-
PERTAIN
= [u'of']¶
-
TZOFFSET
= {}¶
-
UTCZONE
= [u'UTC', u'GMT', u'Z']¶
-
WEEKDAYS
= [(u'Mon', u'Monday'), (u'Tue', u'Tuesday'), (u'Wed', u'Wednesday'), (u'Thu', u'Thursday'), (u'Fri', u'Friday'), (u'Sat', u'Saturday'), (u'Sun', u'Sunday')]¶
- dayfirst – Whether to interpret the first value in an ambiguous 3-integer date
(e.g. 01/05/09) as the day (