datetimeparse Reference

Date and time parsing based on cmdparser.

This module contains various classes suitable for use in cmdparser parse trees which parse combinations of dates and times, including some natural language phrases which express relative times. The parsing is intended to be as broad as possible, but quite specific to the English language.

Class Reference

class cmdparser.datetimeparse.AfterToken(name)

Subtree matching phrases which are synonyms of “in the future”.

class cmdparser.datetimeparse.AgoToken(name, token=None)

Simple token which matches synonyms of “ago”.

class cmdparser.datetimeparse.DateDelta(delta=None, months=0)

Represents a relative offset in calendar dates.

This class is a wrapper around datetime.timedelta which adds calendar month offsets in addition to the days and seconds represented by timedelta. This allows any arbitrary calendar offset to be represented.

Instances of this class may be combined with other DateDelta instances, timedelta instances and datetime instances in the same way that timedelta instances can.

The behaviour of month offsets towards the end of the month is as follows: the month is adjusted without changing the day of the month, and if this yields an invalid date then ValueError will be raised. If the date is valid then the time delta is then applied to this new date. This behaviour may not be ideal in all cases, but is at least unambiguous.

class cmdparser.datetimeparse.DateSubtree(name)

A subtree representing an unambiguous calendar day.

This subtree accepts standard date specifications, but also phrases such as 23rd of March and Thursday next week. Two slight subtleties should be noted - if omitted, the current week/year are assumed as appropriate, and phrases of the form (last|this|next) <weekday> use what I consider to be the most common interpretation in English-speaking nations - specifically, a synonym for <weekday> (last|this|next) week.

These interpretations will likely trip some people up, as this library doesn’t have the context to decide if the future or past dates are more likely. However, they’re sufficiently useful and common that I think it would be more annoying to fail to support them at all.

class cmdparser.datetimeparse.DateTimeSubtree(name)

A subtree matching a specific point in time.

This subtree attempts to parse specifications of a date and time, either absolute or relative to the current time (as returned by datetime.datetime.now()). The converted value is a datetime instance.

class cmdparser.datetimeparse.OffsetSubtree(name)

A subtree matching a period of a single unit.

This subtree matches simple clauses of the form N units where a unit may be a second, minute, hour, day, week, month or year. The converted value is a DateDelta representing the specified length of time.

This subtree is typically only used indirectly via RelativeTimeSubtree.

class cmdparser.datetimeparse.PastCalendarPeriodSubtree(name)

A subtree matching a date range in the past.

Examples of matched phrases include last month, january 2011 and week of 2012-03-22. Aside from calendar periods, arbitrary periods can be specified in the form between <date> and <date> or various synonymous phrases - in this form, the start date is inclusive and the end date is exclusive.

This subtree doesn’t attempt to match dates in the future, although neither does it have any special checks to avoid matching future dates (for example, if a calendar date is specified any valid date will match). Only dates are permitted - times of day will fail to match.

The converted value is a 2-tuple (start, end) of datetime.date instances, where start is inclusive and end is exclusive.

class cmdparser.datetimeparse.RelativeTimeSubtree(name)

A subtree matching a relative time.

This subtree matches times relative to a fixed point in time - for example, phrases such as 2 hours ago and in 3 days and 5 minutes. Its converted value is a DateDelta instance.

class cmdparser.datetimeparse.StrptimeToken(name, time_formats)

Matches one of a set of strftime() format strings.

Matches command arguments against the specified list of strftime() format strings in turn, converting the value to that returned by time.strptime().

Any combination of date and time specifiers can be put into the format, subject to the same restrictions as time.strptime(), and the only additional feature this class implements is to allow variations where - is replaced by / (or vice versa) and/or : is replaced by . (or vice versa). So, if the time format "%Y-%m-%d" is provided then implicitly "%Y/%m/%d" will also match.

class cmdparser.datetimeparse.TimeSubtree(name)

A subtree representing a time of day.

Examples of phrases accepted include now and 3:15pm.