API

Parsing Strings

This module defines three functions for parsing strings.

zope.datetime.parse(string, local=True) → tuple

Parse a string containing some sort of date-time data into a tuple.

As a general rule, any date-time representation that is recognized and unambigous to a resident of North America is acceptable.(The reason for this qualification is that in North America, a date like: 2/1/1994 is interpreted as February 1, 1994, while in some parts of the world, it is interpreted as January 2, 1994.) A date/time string consists of two components, a date component and an optional time component, separated by one or more spaces. If the time component is omited, 12:00am is assumed. Any recognized timezone name specified as the final element of the date/time string will be used for computing the date/time value. (If you create a DateTime with the string ‘Mar 9, 1997 1:45pm US/Pacific’, the value will essentially be the same as if you had captured time.time() at the specified date and time on a machine in that timezone):

x = parse('1997/3/9 1:45pm')
# returns specified time, represented in local machine zone.

y = parse('Mar 9, 1997 13:45:00')
# y is equal to x

The function automatically detects and handles ISO8601 compliant dates (YYYY-MM-DDThh:ss:mmTZD).

The date component consists of year, month, and day values. The year value must be a one-, two-, or four-digit integer. If a one- or two-digit year is used, the year is assumed to be in the twentieth century. The month may an integer, from 1 to 12, a month name, or a month abreviation, where a period may optionally follow the abreviation. The day must be an integer from 1 to the number of days in the month. The year, month, and day values may be separated by periods, hyphens, forward, shashes, or spaces. Extra spaces are permitted around the delimiters. Year, month, and day values may be given in any order as long as it is possible to distinguish the components. If all three components are numbers that are less than 13, then a a month-day-year ordering is assumed.

The time component consists of hour, minute, and second values separated by colons. The hour value must be an integer between 0 and 23 inclusively. The minute value must be an integer between 0 and 59 inclusively. The second value may be an integer value between 0 and 59.999 inclusively. The second value or both the minute and second values may be ommitted. The time may be followed by am or pm in upper or lower case, in which case a 12-hour clock is assumed.

Parameters:

local (bool) – If no timezone can be parsed from the string, figure out what timezone it is in the local area on the given date and return that.

Returns:

This function returns a tuple (year, month, day, hour, minute, second, timezone_string).

Raises:
  • SyntaxError – If a string argument passed to the DateTime constructor cannot be parsed (for example, it is empty).
  • DateError – If the date components are invalid.
  • DateTimeError – If the time or timezone components are invalid.
  • TypeError – If the argument is not a string.
zope.datetime.parseDatetimetz(string, local=True)[source]

Parse the given string using parse().

Return a datetime.datetime instance.

zope.datetime.time(string) → float

Parse a string containing some sort of date-time data and return the value in seconds since the Epoch.

Returns:A floating point number representing the time in seconds since the Epoch (in UTC).
Raises:DateTimeError – If a timezone was parsed from the argument, but it wasn’t a known named or numeric timezone.

See also

parse() for the description of allowed input values.

The functions parse() and time() are both methods of an instance of the DateTimeParser class. This is an immutable, stateless class.

class zope.datetime.DateTimeParser[source]

Bases: object

parse(self, string, local=True)[source]

The same as parse().

time(self, string)[source]

The same as time().

localZone(ltm=None)[source]

Returns the time zone on the given date. The time zone can change according to daylight savings.

Formatting Strings

This module defines a few convenience functions for producing formatted date strings.

zope.datetime.iso8601_date(ts=None)[source]

Return an ISO 8601 formatted date string, required for certain DAV properties.

For example: ‘2000-11-10T16:21:09-08:00’

Parameters:ts (any) – A timestamp as returned by time.time() (float), seconds since the epoch (int) or any object which can be converted to int via a __int__ method returning number of seconds since the epoch. If not given, the current time will be used.
zope.datetime.rfc850_date(ts=None)[source]

Return an RFC 850 formatted date string.

For example, ‘Friday, 10-Nov-00 16:21:09 GMT’.

Parameters:ts (any) – A timestamp as returned by time.time() (float), seconds since the epoch (int) or any object which can be converted to int via a __int__ method returning number of seconds since the epoch.
zope.datetime.rfc1123_date(ts=None)[source]

Return an RFC 1123 format date string, required for use in HTTP Date headers per the HTTP 1.1 spec.

For example, ‘Fri, 10 Nov 2000 16:21:09 GMT’.

Parameters:ts (any) – A timestamp as returned by time.time() (float), seconds since the epoch (int) or any object which can be converted to int via a __int__ method returning number of seconds since the epoch.

Exceptions

This module defines an exception tree that it uses to report errors.

class zope.datetime.DateTimeError[source]

Bases: exceptions.Exception

The root exception for errors raised by this module.

class zope.datetime.DateError[source]

Bases: zope.datetime.DateTimeError

Invalid Date Components

class zope.datetime.TimeError[source]

Bases: zope.datetime.DateTimeError

Invalid Time Components

class zope.datetime.SyntaxError[source]

Bases: zope.datetime.DateTimeError

Invalid Date-Time String