mxDateTime - Date/time types for Python

mxDateTime - Date and Time types for Python

Interface ( DateTime : DateTimeDelta : RelativeDateTime ) : Arithmetic : Submodules ( ISO : ARPA : Feasts ) : Examples : C API : Structure : Download & Installation : Support : Copyright : History : Home

Version 1.0.1

Introduction

These types were created to provide a consistent way of transfering date and time data between Python and databases. Apart from handling date before the Unix epoch (1.1.1970) they also correctly work with dates beyond the Unix time limit (currently with Unix time value being encoded using 32bit integers, the limit is reached in 2038) and thus is Year 2000 and Year 2038 safe.

After some discussions on the db-sig list about what the date type DateTime should be capable of doing and what not, we decided to use the following internal format:

Absolute date: This is a C long defined as being the number of days in the Gregorian calendar since the day before January 1 in the year 1 (01.01.0001), thus 01.01.0001 corresponds to 1.
Absolute time: This is a C double defined as the number of seconds since midnight (0:00:00.00) of the day expressed by the above value.

The epoch used by the module is January 1st of the year 1 at midnight (0:00:00.00). This date corresponds to absolute day 1 and absolute time 0. Dates before 01.01.0001 are not supported (this is a little difficult to handle, since the year 0 was omitted by the Romans).

For the purpose of storing absolute time values and time spans, the package provides a second type called DateTimeDelta. The internal representation for this type is seconds and stored in a signed C double.

As of version 0.9.1, a third object type is available: RelativeDateTime. This object is currently implemented in Python and may be used to store relative time deltas (see below for an exact description). It's main purpose is providing an intuitive way to calculate e.g. the "first of next month".

Designing the types wasn't as easy as expected, since many criteria had to be taken into account. Here are some of them and their implementation:

Time Zones, Daylight Savings Time (DST) and Leap Seconds

Time zones are among the most difficult to handle issues when it comes to implementing and using types for date and time. We chose to move the time zone handling functionality out of the C implementation and into Python. This means that the types know nothing about the time zones of the values they store and calculations are done using the raw values.

If you need to store and use these informations in calculations, you can "subclass" the types to implement your ideas rather than having to stick to what the C implementation defines. The included ODMG submodule is an example of how this can be done.

Leap seconds are not supported either. You can implement classes respecting these by "subclassing" DateTime and DateTimeDelta and then overriding the calculation methods with methods that work on Unix ticks values (if the underlying C lib knows about leap seconds).

Conversion from and to other formats

For the purpose of converting the stored values to Unix ticks (number of seconds since the Unix epoch; the C lib also uses this representation) we assume that the values are given in local time. This assumption had to be made because the C lib provides no standard way to convert a broken down date/time value in any other way into a ticks value. Conversion from stored UTC values to ticks only works if your C lib provides the necessary mechanisms (see the notes for gmticks() below). Fortunately many C libs have a working mktime() or timegm() API, so the situation is not all that bad.

Conversions to COM dates and tuples are done without any assumption on the time zone. The raw values are used.

Conversion from other formats to DateTime instances is always done by first calculating the corresponding absolute time and date values (which are also used as basis for calculations).

Rounding errors

The internal representation of date/times behaves much like floats do in Python, i.e. rounding errors can occur when doing calculations. There is a special compare function included (cmp()) in the package that allows you to compare two date/time values using a given accuracy, e.g. cmp(date1,date2,0.5) will allow 12:00:00.5 and 12:00:01.0 to compare equal.

Special care has been taken to prevent these rounding errors from occurring for COM dates. If you create a DateTime instance using a COM date, then the value returned by the .COMDate() method is guaranteed to be exactly the same as the one used for creation. The same is true for creation using absolute time and absolute date and broken down values.

Immutability

One other thing to keep in mind when working with DateTime and DateTimeDelta instances is that they are immutable (like tuples). Once an instance is created you can not change its value. Instead, you will have to create a new instance with modified values. The advantage of having immutable objects is that they can be used as dictionary keys.

Interaction with other types

DateTime and DateTimeDelta instances can be compared and hashed, making them compatible to the dictionary implementation Python uses (they can be used as keys). The copy protocol, simple arithmetic and pickleing are also supported (ee below for details).

String formats

DateTime and DateTimeDelta instances know how to output themselves as ISO8601-strings. The format is very simple: YYYY-MM-DD HH:MM:SS.ss for DateTime instances and [-][DD:]HH:MM:SS.ss for DateTimeDelta instances (the DD-part (days) is only given if the absolute delta value is greater than 24 hours). Customized conversion to strings can be done using the strftime-methods or the included submodules.

String parsing is supported through the strptime() constructor which implements a very strict parsing scheme and the included submodules (e.g. ISO and ARPA), which allow a little more freedom.

Speed and Memory

Comparing the types to time-module based routines is not really possible, since the used strategies differ. You can compare them to tuple-based date/time classes though: DateTime[Delta] are much faster on creation, use less storage and are faster to convert to the supported other formats than any equivalent tuple-based implementation written in Python.

Creation of time-module values using time.mktime() is much slower than doing the same thing with DateTime(). The same holds for the reverse conversion (using time.localtime()).

The storage size of ticks (floats, which the time module uses) is about 1/3 of the size a DateTime instance uses. This is mainly due to the fact that DateTime instances cache the broken down values for fast access.

To summarize: DateTime[Delta] are faster, but also use more memory than traditional time-module based techniques.

Interface

The package provides three data structures for working with date and time values. These are:

DateTime for referring to absolute date/time values,
DateTimeDelta for date/time spans and
RelativeDateTime for representing variable date/time spans (these are the TABs of date/time calculation)

DateTime Constructors

Several constructors are available in the module DateTime:

DateTimeFromAbsDateTime(absdate,abstime): Returns a new DateTime instance for the given absolute date and time. This interface can be used by classes written in Python which implement other calendars than the Gregorian, for example.
DateTime(year,month=1,day=1,hour=0,minute=0,second=0.0): Constructs a DateTime instance from the given values. Year always has to be a positive integer if given. The entry for day can be negative to indicate days counted in reverse order, that is the last day becomes -1, the day before that -2, and so on, e.g. DateTime(1997,12,-2) gives the 30.12.1997 (this is useful especially for months). Note that although the above makes it look like this function can handle keywords, it currently cannot.
Timestamp(year,month,day,hour=0,minute=0,second=0.0): Is just another name binding for DateTime().
Date(year,month,day): Is just another name binding for DateTime().
mktime(year,month,day,hour,minute,second,dow,doy,dst): Alias for DateTime() that excepts additional arguments to be call compatible with time.mktime(). Note that the arguments dow,doy and dst are not used in any way. You should only use this contructor for porting applications from time module based functions to DateTime.
localtime(ticks=time.time()): Constructs a DateTime instance from the ticks value (this is what time.time() returns; see the time module for details). The instance will hold the associated local time. If ticks is not given, the current time is used.
now(): Just another name binding for localtime().
gmtime(ticks=time.time()): Constructs a DateTime instance from the ticks value (this is what time.time() returns; see the time module for details). The instance will hold the associated UTC time. If ticks is not given, the current time is used. gmticks() is the inverse of this function.
utctime(ticks=time.time()): Alias for gmtime().
today(hour=0,minute=0,second=0.0): Returns a DateTime instance for the current date (in local time) at the given time (defaults to midnight). E.g. today(14,00) is today at 1400 hours.
DateTimeFromAbsDays(days): Constructs a DateTime instance from the days since the epoch value.
DateTimeFromCOMDate(comdate): Constructs a DateTime instance from the comdate value. This is used in the COM mechanism I'm told and repesents the date/time difference between 30.12.1899 and the represented date/time, with time being encoded as fraction of a whole day, thus 0.5 corresponds to 12:00:00.00. Special care is taken that the resulting instance's method COMDate() returns exactly the same value as the one used for constructing it -- even though the internal representation is more accurate.
strptime(string,format_string[,default]): Parse the given string using the format string and construct a DateTime instance from the found value. If default is given (must be a DateTime instance), it's entries are used as default values. Otherwise, 01.01.0001 0:00:00.00 is used. An Error is raised if the underlying C parsing function strptime() fails. Note: This function is relatively new, you may not have access to this constructor on your platform. For further information on the format, please refer to the Unix manpage (it is very similar to that of strftime() which is documented in the Python library reference for the time module).

DateTime Instance Methods

A DateTime instance has the following methods:

tuple(): Returns the instances value as time.localtime() tuple. DST is set assuming local time. It can also be -1, meaning that the information is not available.
absvalues(): Returns the instances value as tuple (absdate, abstime).
ticks(offset=0.0,dst=-1): Returns a float repesenting the instances value in ticks (see above). The conversion routine assumes that the stored date/time value is given in local time. The given value for DST is used by the conversion (0 = DST off, 1 = DST on, -1 = unkown) and offset is subtracted from the resulting value. The method raises an OverflowError exception if the objects value does not fit into the system's ticks range.
Note: On some platforms the C lib's mktime() function that this method uses does not allow setting DST to an arbitrary value. The module checks for this and raises a SystemError in case setting DST to 0 or 1 does not result in valid results.
gmticks(offset=0.0): Returns a float repesenting the instances value in ticks (see above). The conversion routine assumes that the stored date/time value is given in UTC time. offset is subtracted from the resulting value. The method raises an OverflowError exception if the objects value does not fit into the system's ticks range.
Note: This method is not available on all platforms. Use the helper function gmticks(datetime) for a more portable way of handling conversion from UTC to ticks.
COMDate(): Returns a float float repesenting the instances value as COM date (see above).
strftime(format_string="%c"): Format the instances value as indicated by the format string. This is the same function as the one in the time module. For further information please refer to the manpage or the Python reference manual. Note: strftime() and strptime() try to be the inverse of each other. The output from strftime() given to strptime() together with the format string passed to strftime() will in most cases give you a DateTime instance referring to the same date and time. Note that time zone information is not available. Use the instance variable tz instead.
Format(format_string="%c"): This is just an alias for strftime() to make the type compatible to other date/time types.

DateTime Instance Variables

To make life easier, the instances also provide a more direct interface to their stored values:

hour, minute, second

Return the indicated values in their standard ranges. Note that in a future release, leap seconds may also be considered and thus either hour has a range of 0-24 or second a range of 0-60.

year, month, day

Return the indicated values in their standard 1-based ranges.

dst

Integer indicating whether DST is active (1) or not (0) or cannot be determined (-1). The value is calculated assuming that the stored value is local time.

tz

Returns the time zone string, assuming local time, or "???" if the information is not available.

day_of_week

Returns the day of the week; Monday is returned as 0.

day_of_year

Returns the day of the year; 1.1. is returned as 1.

days_in_month

Returns the number of days in the object's month.

iso_week

Returns a tuple (year,isoweek,isoday) signifying the ISO week notation for the date the object points to. Note: isoday 1 is Monday.

is_leapyear

Returns 1 iff the instances value points to a leap year in the Gregorian calendar.

yearoffset

Returns the absolute date of the 31.12. in the year before the instance's year.

absdays

Returns the absolute date and time of the object converted to a Python float representing absolute days (days since the epoch). The value is calculated using a 86400.0 seconds/day basis and does not account for leap seconds. This value is handy if you need the date/time value stored in one number. By using a Python float, which is mapped to a C double internally, the accuracy should give a fairly large range of valid dates.

absdate

Returns the absolute date as used by the instance.

abstime

Returns the absolute time as used by the instance.

DateTimeDelta Constructors

Several constructors are available:

DateTimeDelta(delta_days,delta_seconds=0.0)

Returns a new DateTimeDelta instance for the given time delta. The delta_seconds can be given as float. The internal value is calculated using the formula 86400.0*days + seconds. Keep this in mind when passing negative values to the constructor.

TimeDelta(hour=0.0,minute=0.0,second=0.0)

Constructs a DateTimeDelta instance from the given values. The internal value is calculated using the formula hours * 3600 + minutes * 60 + seconds. Keep this in mind when passing negative values to the constructor. The constructor allows usage of keywords, e.g. Time(seconds=1.5) works.

Time(hour,minute=0.0,second=0.0)

Is just another name binding for TimeDelta.

DateTimeDeltaFromSeconds(seconds)

Constructs a DateTimeDelta instance from the given seconds value. It can be given as float.

DateTimeDeltaFromDays(days)

Constructs a DateTimeDelta instance from the given days value. It can be given as float. The internal value is calculated using a 86400.0 seconds/day basis.

DateTimeDelta Instance Methods

A DateTimeDelta instance has the following methods:

absvalues()

Return a (absdays, absseconds) tuple. The absseconds part is normalized in such way that it is always smaller than 86400.0. The values can be used do date/time calculations. Both values are signed.

tuple()

Returns the instance's value as (day,hour,minute,second) tuple. The values are the same those returned by the attributes of the same name.

strftime(format_string)

Format the instance's value as indicated by the format string. This is the same function as the one in the time module. For further information please refer to the manpage or the Python reference manual. Since some descriptors don't make any sense for date/time deltas these return undefined values. Only the fields hour, minute, seconds and day are set according to the objects value (the descriptors %d %H %M %S %I %p %X work as expected). Negative values show up positive -- you'll have to provide your own way of showing the sign (the seconds instance variable is signed).

DateTimeDelta Instance Variables

To make life easier, the instances also provide a more direct interface to their stored values:

day, hour, minute, second

Return the indicated values in their standard ranges. The values are negative for negative time deltas.

days, hours, minutes, seconds

Return the internal value of the object expressed as float in the resp. units, e.g. TimeDelta(12,00,00).days == 0.5.

RelativeDateTime Constructors

These constructors are avaiable:

RelativeDateTime(years=0,months=0,days=0, year=0,month=0,day=0, hours=0,minutes=0,seconds=0, hour=None,minute=None,second=None)

Returns a RelativeDateTime instance for the specified relative time. The constructor handles keywords, so you'll only have to give those parameters which should be changed when you add the relative to an absolute DateTime instance. Absolute values passed to the constructor will override delta values of the same type.

RelativeDate(years=0,months=0,days=0,year=0,month=0,day=0)

Is another name binding for RelativeDateTime.

RelativeDateTime objects store the given settings (plural nouns meaning deltas, singular nouns absolute values) and apply them when used in calculations. Delta values will have the effect of changing the corresponding attribute of the involved absolute DateTime object accordingly, while absolute values overwrite the DateTime objects attribute value with a new one. The effective value of the object is thus determined at calculation time and depends on the context it is used in.
Adding and subtracting RelativeDateTime instances is supported with the following rules: deltas will be added together and right side absolute values override left side ones.
Adding RelativeDateTime instances to and subtracting RelativeDateTime instances from DateTime instances will return DateTime instances with the appropriate calculations applied, e.g. to get a DateTime instance for the first of next month, you'd call now() + RelativeDateTime(months=+1,day=01).
A few examples will probably make the intended usage clearer:
>>> from DateTime import * >>> print now() 1998-08-11 16:46:02.20 # add one month >>> print now() + RelativeDateTime(months=+1) 1998-09-11 16:46:24.59 # add ten months >>> print now() + RelativeDateTime(months=+10) 1999-06-11 16:47:03.07 # ten days from now >>> print now() + RelativeDateTime(days=+10) 1998-08-21 16:47:10.58 # first of next month >>> print now() + RelativeDateTime(months=+1,day=1) 1998-09-01 16:47:25.15 # first of this month, same time >>> print now() + RelativeDateTime(day=1) 1998-08-01 16:47:35.48 # first of this month at midnight >>> print now() + RelativeDateTime(day=1,hour=0,minute=0,second=0) 1998-08-01 00:00:00.00 # next year, first of previous month, same time >>> print now() + RelativeDateTime(years=+1,months=-1,day=1) 1999-07-01 16:48:31.87

RelativeDateTime Instance Methods

RelativeDateTime instances currently don't have any instance methods.

RelativeDateTime Instance Variables

The following attributes are exposed, but should not be written to directly (the objects are currently implemented in Python, but that could change in future releases).

year, month, day, hour, minute, second

Absolute values of the instance.

years, months, days, hours, minutes, seconds

Relative values of the instance.

The given values are only defined in case they were set at instance creation time.

Constants

The package defines these constants:

oneWeek, oneDay, oneHour, oneMinute, oneSecond

Are set to the indicated values wrapped into DateTimeDelta instances.

Error, RangeError

These are the exception objects. Exceptions will normally only be raised by functions, methods or arithmetic operations.

DateTimeType, DateTimeDelta

The type objects for the two types.

mxDateTimeAPI

The C API wrapped by a C object. See mxDateTime.h for details.

Helper functions

The package defines these additional functions:

cmp(obj1,obj2,accuracy=0.0)

Compares two DateTime[Delta] objects. If accuracy is given, then equality will result in case the absolute difference between the two values is less than or equal to accuracy.

gmticks(datetime)

Returns a ticks value for datetime assuming the stored value is given in UTC. Unfortunately, there is no portable way of converting broken down UTC values into ticks. The module will try to use datetime.gmticks() if it is available. If not, the module will revert to using datetime.ticks(time.timezone,0). See the notes on the datetime.ticks() method for further information on how this works.
In any case, you should check the correctness of the results on your target platforms to avoid wrong results or malfunctioning programs.

utcticks(datetime)

Alias for gmticks().

tz_offset(datetime)

Returns a DateTimeDelta instance representing the UTC offset for datetime assuming that the stored values refer to local time. If you subtract this value from datetime, you'll get UTC time. This function relies on the datetime.ticks() method, so the same comments as for gmtime() apply.

gm2local(datetime)

Convert a DateTime instance holding UTC time to a DateTime instance using local time. This function relies on the gmticks(), so the same comments apply.

utc2local(datetime)

Alias for gm2local().

local2gm(datetime)

Convert a DateTime instance holding local time to a DateTime instance using UTC time.

local2utc(datetime)

Alias for local2gm().

If you find any bugs, please report them to me so that I can fix them for the next release.

Date/Time Arithmetic

The three objects DateTime, DateTimeDelta and RelativeDateTime can be used to do simple date/time arithmetic. Addition and subtraction are supported and result in the expected results. In addition to handling arithmetic using only the two types, mixed arithmetic with numbers is also understood to a certain extent:

Argument 1 Argument 2 Result

DateTime object v DateTime object w

v - w
returns a DateTimeDelta object representing the time difference;
v + w
is not defined.

DateTime object v A number w

v - w
returns a new DateTime object with a date/time decremented by w days (floats can be used to indicate day fractions);
v + w
works accordingly;
Note: you can use the object oneDay to get similar effects in a more intuitive way.
v cmp w
Converts v to Unix ticks and returns the result of comparing the ticks value to the number w. Note: the ticks conversion assumes that the stored value is given in local time. Also note that the comparison will only yield correct results if the DateTime instance is placed on the left of the comparison operator (this is because of the coercion quirks mentioned above).

DateTime object v DateTimeDelta object w

v - w
returns a new DateTimeDelta object with a date/time decremented by w's value;
v + w
works accordingly.

DateTime object v RelativeDateTime object w

v + w
returns a new DateTime object with a date/time adjusted according to w's settings;
v - w
works accordingly.

DateTimeDelta object v DateTime object w
No operations defined.

DateTimeDelta object v A number w

v - w
returns a new DateTimeDelta object with a time delta value decremented by w seconds (can be given as float to indicate fractions of a second);
v + w
works accordingly;
Note: you can use the object oneSecond to get similar effects in a more intuitive way;
v * w
returns a new DateTimeDelta object with a time delta value multiplied by w;
v / w
returns a new DateTimeDelta object with a time delta value divided by w;
v cmp w
Converts v to a signed float representing the delta in seconds and returns the result of comparing the seconds value to the number w.Note that the comparison will only yield correct results if the DateTimeDelta instance is placed on the left of the comparison operator (this is because of the coercion quirks mentioned above).

DateTimeDelta object v DateTimeDelta object w

v + w
returns a new DateTimeDelta object for the sum of the two time deltas ((v+w).seconds == v.seconds + w.seconds);
v - w
works accordingly;
v / w
returns a float equal to v.seconds / w.seconds.

Note: Operation and argument order are important because of the different ways arguments are coerced. Use parenthesis to make your intent clear or you will get unwanted results.
Due to a flaw in the C interface for coercion in the interpreter, it is not possible to do proper handling of mixed type arithmetic for types which don't coerce to a common type (without creating temporary objets all the time). The module uses a workaround, but unfortunately the order of the operands is lost along the way. Under normal circumstances you won't notice this defect, but be warned since e.g. oneDay - 1 == 1 - oneDay, yet oneDay - oneSecond != oneSecond - oneDay.

Submodules

The package provides additional features in form of the following submodules. All submodules are imported on request only.
ISO Submodule

The ISO submodule is intended to provide interfacing functions to ISO 8601 date and time representations . The most common format is:
YYYY-MM-DD HH:MM:SS[+-HH:MM]
Note that timezone information (in square brackets) is only interpreted by the ParseDateTimeUTC() constructor. All others ignore the given offset and store the time value as-is.
You can access the functions and symbols defined in the submodule through DateTime.ISO -- it is imported on demand.
The module defines these constructors and functions:

WeekTime(year,isoweek=1,isoday=1,hour=0,minute=0,second=0.0)

Returns a DateTime instance pointing to the given ISO week and day. isoday defaults to 1, which corresponds to Monday in the ISO numbering. Note that the resulting date can in fact lie in the year before the one given as parameter, e.g. Week(1998,1,1) results in 1997-12-29. The DateTime instance variable iso_week provides an inverse to this function.

Week(year,isoweek,isoday=1)

Alias for WeekTime().

DateTime(), Time(), TimeDelta()

Aliases for the constructors you find in DateTime. Just included for completeness, since these also use ISO style notation for their argument order.

ParseDateTime(isostring)

Returns a DateTime instance reflecting the given ISO date. A time part is optional and must be delimited from the date by a space or 'T'. Year must be given, month and day default to 1. For the time part, hour and minute must be given, while second defaults to 0.

ParseDateTimeGMT(isostring)

Same as ParseDateTime() except that timezone information is used to calculate and return the date/time value in UTC. Note: UTC is practically the same as GMT, the old time standard.

ParseDateTimeUTC(isostring)

Alias for ParseDateTimeGMT(). Note: UTC is practically the same as GMT, the old time standard.

ParseDate(isostring)

Returns a DateTime instance reflecting the given ISO date. Year must be given, month and day default to 1. A time part may not be included.

ParseWeek(isostring)

Returns a DateTime instance reflecting the given ISO date. Year must be given, week number and day are optional and default to 1. A time part may not be included.

ParseWeekTime(isostring)

Returns a DateTime instance reflecting the given ISO date. Year must be given, week number and day are optional and default to 1. A time part may not be included.

ParseTime(isostring)

Returns a DateTimeDelta instance reflecting the given ISO time. Hours and minutes must be given, seconds are optional and default to 0. Fractions of a second may also be used, e.g. '12:23:12.34'.

ParseTimeDelta(isostring)

Returns a DateTimeDelta instance reflecting the given ISO time as delta. Hours and minutes must be given, seconds are optional and default to 0. Fractions of a second may also be used, e.g. '12:23:12.34'. In addition to the ISO standard a sign may be prepended to the time, e.g. '-12:34'.

ParseAny(isostring)

Returns a DateTime[Delta] instance reflecting the given ISO date and/or time. All ISO formats supported by the module are understood by this constructor.

str(datetime)

Returns the datetime instance as standard ISO date string (omitting the seconds fraction and always adding timezone information). The function assumes that the stored value is given in local time and calculates the correct timezone offset accordingly.

strGMT(datetime)

Returns the datetime instance as ISO date string assuming it is given in UTC.

strUTC(datetime)

Alias for strGMT.

The parsing routines strip surrounding whitespace from the strings, but are strict in what they want to see. Additional characters are not allowed and will cause a ValueError to be raised.
Timezone information may be included, but will not be interpreted unless explicitly stated.
The parsing routines also understand the ISO 8601 date/time formats without seperating dashes and colons, e.g. '19980102T142020', and mixtures of both notations.
ISO 8601 string formats and DateTime[Delta] instances

DateTime and DateTimeDelta instances use a slightly enhanced ISO format for string represenation:
DateTime instances are converted to 'YYYY-MM-DD HH:MM:SS.ss' where the last ss indicate hundredths of a second (ISO doesn't define how to display these).
DateTimeDelta instances use '[-][DD:]HH:MM:SS.ss' as format, where DD: is only shown for deltas spanning more than one day (24 hours). The ss part has the same meaning as for DateTime instances: hundredths of a second. A minus is shown for negative deltas. ISO does not define relative time deltas, but the time representation is allowed to be 'HH:MM:SS'.

ARPA Submodule

The ARPA submodule is intended to provide interfacing functions to ARPA date representations. These are used throughout the Internet for passing around mails, postings, etc. The format is very simple:
[Day, ]DD Mon YYYY HH:MM[:SS] ZONE
where ZONE can be one of these: MDT, O, EDT, X, Y, CDT, UT, AST, GMT, PST, Z, V, CST, ADT, I, W, T, U, R, S, P, Q, N, EST, L, M, MST, K, H, E, F, G, D, PDT, B, C, UTC, A (the single letter ones being military time zones). Use of explicit time zone names other than UTC and GMT is depreciated, though. The better alternative is providing the offset from UTC being in effect at the given local time: +-HHMM (this is the offset you have to subtract from the given time in order to get UTC).
You can access the functions and symbols defined in the submodule through DateTime.ARPA -- it is imported on demand.
The module defines these constructors and functions:

ParseDateTime(arpastring)

Returns a DateTime instance reflecting the given ARPA date assuming it is local time (timezones are silently ignored).

ParseDateTimeGMT(arpastring)

Returns a DateTime instance reflecting the given ARPA date converting it to UTC (timezones are honored).

ParseDateTimeUTC(arpastring)

Alias for ParseDateTimeGMT(). Note: UTC is practically the same as GMT, the old time standard.

str(datetime,tz=DateTime.tz_offset(datetime))

Returns the datetime instance as ARPA date string. tz can be given as DateTimeDelta instance providing the time zone difference from datetime's zone to UTC. It defaults to DateTime.tz_offset(datetime) which assumes local time.

strGMT(datetime)

Returns the datetime instance as ARPA date string assuming it is given in UTC.

strUTC(datetime)

Alias for strGMT.

The parsing routines strip surrounding whitespace from the strings. Additional characters are allowed (because some mail apps add extra information to the date header).

Feasts Submodule

The Feasts submodule is intended to provide easy-to-use constructors for common moveable christian feasts that can be deduced from the date of Easter Sunday. The algorithm used to calculate Easter Sunday is based on the one presented in the Calendar FAQ by Claus Tondering, which in return is based on the algorithm of Oudin (1940) as quoted in "Explanatory Supplement to the Astronomical Almanac", P. Kenneth Seidelmann, editor.
The module defines these constructors and functions:

EasterSunday(year), Ostersonntag(year), DimanchePaques(year)

Returns a DateTime instance pointing to Easter Sunday in the given year at midnight.

The other feasts are deduced from this date and all use the same interface. The module defines these sets of constructors the return the corresponding DateTime instance for midnight of the implied day:

CarnivalMonday(year), Rosenmontag(year)

MardiGras(year)

AshWednesday(year), Aschermittwoch(year), MercrediCendres(year)

PalmSunday(year), Palmsonntag(year), DimancheRameaux(year)

EasterFriday(year), Karfreitag(year), LundiPaques(year)

EasterMonday(year), Ostermontag(year), LundiPaques(year)

Ascension(year), Himmelfahrt(year)

WhitSunday(year), Pfingstsonntag(year), DimanchePentecote(year)

WhitMonday(year), Pfingstmontag(year), LundiPentecote(year)

CorpusChristi(year), Frohnleichnam(year), FeteDieu(year)

Examples of Use

For an example of how to use the two types to develop other date/time classes (e.g. ones that support time zones or different calendars), see the included ODMG module. It defines types similar to those of the ODMG standard.
Here is a little countdown script:
#!/usr/local/bin/python -u """ Y2000.py - The year 2000 countdown. """ from DateTime import * from time import sleep while 1: d = Date(2000,1,1) - now() print 'Y2000... time left: %2i days %2i hours ' '%2i minutes %2i seconds\r' % \ (d.day,d.hour,d.minute,d.second), sleep(1)

This snippet demonstrates some of the possible string representations for DateTime instances:
>>> from DateTime import * >>> ISO.str(now()) '1998-06-14 11:08:27+0200' >>> ARPA.str(now()) 'Sun, 14 Jun 1998 11:08:33 +0200' >>> now().strftime() 'Sun Jun 14 11:08:51 1998' >>> str(now()) '1998-06-14 11:09:17.82'

More examples will eventually appear in the Examples subdirectory of the package.

Supported Data Types in the C-API

Please have look at the file mxDateTime.h for details. Interfacing is provided through a Python C object for ticks, struct tm, COM doubles, Python tuples and direct input either by giving absolute date/time or a broken down tuple. To access the module, do the following (note the similarities with Python's way of accessing functions from a module):
#include "mxDateTime.h" ... PyObject *v; /* Import the mxDateTime module */ if (mxDateTime_ImportModuleAndAPI()) goto onError; /* Access functions from the exported C API through mxDateTime */ v = mxDateTime.DateTime_FromAbsDateAndTime(729376, 49272.0); if (!v) goto onError; /* Type checking */ if (mxDateTime_Check(v)) printf("Works.\n"); Py_DECREF(v); ...

Package Structure

[DateTime] Doc/ Examples/ [mxDateTime] ARPA.py DateTime.py Feasts.py ISO.py ODMG.py

Names with trailing / are plain directories, ones with []-brackets are Python packages, ones with ".py" extension are Python submodules.
The package imports all symbols from the extension module and also registers the types so that they become compatible to the pickle and copy mechanisms in Python.

Installation

First, download the archive, unzip it to a directory on your Python path and then follow these steps (assuming you have already installed Python):
Windows:
Florent Heyworth (radbit.com) has kindly provided a compiled version of the C extension for Windows 95 which is included in the archive (version 1.0.1) -- no further steps or compilation are necessary.
If you intend to recompile the module yourself, he has also provided a batch file (win32mk.bat) and a make file (mxDateTime.mak) for VC50 which you can use. All you have to do is run 'win32mk c:\programs\python' from the mxDateTime subdirectory.
Unix:

run make -f Makefile.pre.in boot in the mxDateTime directory

Important: if you don't have the timegm() C API on your platform, edit the Setup file accordingly; if you don't know, try running make: the linker will tell you if it can't find the timegm symbol. The next Python release (1.5.2) will do the needed checking for you, until then you'll have to edit the file manually...

run make

get Python 1.5 or above running, and execute test.py (e.g. run python -uO test.py); it should not report any errors in form of assert exceptions.

give me feedback :-)

Please post any bug reports, questions etc. directly to me.

Support

I am currently planning to provide commercial support for this package through Python Professional Services Inc.. If you are interested in receiving information about this service or have suggestions regarding the form of support you would like to receive, please contact me.

What I'd like to hear from you...

Contributions of up-to-date compiled versions for WinXX are always welcome -- can't provide them myself, so I'm depending on some help from you...

Is there anything important still missing ?

Copyright & Disclaimer

© 1997,1998, Copyright by Marc-André Lemburg; All Rights Reserved. mailto: mal@lemburg.com
Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee or royalty is hereby granted, provided that the above copyright notice appear in all copies and that both the copyright notice and this permission notice appear in supporting documentation or portions thereof, including modifications, that you make.
THE AUTHOR MARC-ANDRE LEMBURG DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE !

History & Future

Things that still need to be done:

Provide a 100% compatible Python version of the mxDateTime implementation... unless the module becomes a standard in the Python world.
Provide some more examples.
Add a user-friendly date/time parsing submodule that tries to figure out the used format itself.

Things that changed from 1.0.0 to 1.0.1:

Added optional tz keyword parameter to ISO.str and ARPA.str.
Relaxed the ARPA string parsing routines even further. Additional characters and spaces are now allowed in several places.
Fixed the conversion routines for absolute date -> broken down values. There were reports of rounding errors occurring for e.g. Date(2000,12,30)+1 on WinNT which cause the broken down values to be showing out-of-range values (2001-00-00 in the example). Thanks to Amos Gingerich for reporting this.
Added a special constructor test to the test script that will verify the absolute date/time -> broken down and vice versa conversion routines. The script checks all dates between 1900-01-01 and 2100-12-31.

Things that changed from 0.9.2 to 1.0.0:

Changed the DateTime_AsTmStruct() C API. You now have to pass a pointer to a struct tm to be filled instead of receiving a malloc'ed struct as in previous versions. Your compiler will tell you since the signature changed.
Added gm2local() and local2gm(). Documented some aliases to the GMT functions with UTC in their name: UTC and GMT are practically the same. See the Calendar FAQ for more infos.
Changed the way other extensions import the C API. They now try to import it through the package rather than directly through mxDateTime.
This change was needed since there is no way in Python to make sure that C extensions are really only imported once: importing mxDateTime directly and indirectly through the DateTime package lead to two versions of the extensions being loaded. While this is not too serious at first sight (it may even be useful in some cases) it turns out to be a significant problem because the objects declared by the two versions are seen as being of different type (type checks in Python are done via comparing the address of type objects).
As a result, you no longer have to run 'make install' to install the C extension.

Things that changed from 0.9.1 to 0.9.2:

Documented (and changed) the tz_offset() helper function. It used to return an integer value in minutes. Now it returns a DateTimeDelta instance.
Updated the compiled PYD file to 0.9.1. Note: nothing changed in the C extension from 0.9.1 to 0.9.2.
Added some more tests to the test script. Be sure to read the warnings -- there could be problems with conversions between Unix ticks and the value of DateTime instances. Some C libs implement non-standard behaviour in mktime() which can could it to malfunction.

Things that changed from 0.9.0 to 0.9.1:

Changed the str()/repr() format of DateTime instances to always show (at least) 4-digits for years, filled with zeros if necessary.
Relaxed the grammar for ISO dates a little to allow single digit hours, minutes, seconds, days and months, as well as years with 3 digits (two digits are not allowed to prevent ambiguous notations like 98 for 1998).
Added some localizations to the functions in DateTime.py.
Added support for comparing DateTimeDelta instances with numbers: the seconds attribute will be used as basis for the comparison. Because of the coercion problems arising out of the current coercion scheme used by Python, the DateTimeDelta instances must always occur on the left side of the comparison operator to yield correct results. The same is true for comparing DateTime instances and numbers.
Added RelativeDateTime objects. These provide a way to store non-absolute time deltas in a convenient and intuitive way. As opposed to DateTimeDelta objects which store absolute deltas, RelativeDateTime objects span different amounts of time depending on the absolute DateTime object they are added to, e.g. adding one month can mean anything from 28 days to 31 days.
Reformatted the docstrings a little.
Documented submodule Feasts. Hope I got those names right...

Older history entries can be found in a seperate list.

© 1997, 1998, Copyright by Marc-André Lemburg; All Rights Reserved. mailto: mal@lemburg.com

Argument 1	Argument 2	Result
DateTime object v	DateTime object w	`v - w` returns a DateTimeDelta object representing the time difference; `v + w` is not defined.
DateTime object v	A number w	`v - w` returns a new DateTime object with a date/time decremented by `w` days (floats can be used to indicate day fractions); `v + w` works accordingly; Note: you can use the object oneDay to get similar effects in a more intuitive way. `v cmp w` Converts `v` to Unix ticks and returns the result of comparing the ticks value to the number `w`. Note: the ticks conversion assumes that the stored value is given in local time. Also note that the comparison will only yield correct results if the DateTime instance is placed on the left of the comparison operator (this is because of the coercion quirks mentioned above).
DateTime object v	DateTimeDelta object w	`v - w` returns a new DateTimeDelta object with a date/time decremented by `w`'s value; `v + w` works accordingly.
DateTime object v	RelativeDateTime object w	`v + w` returns a new DateTime object with a date/time adjusted according to `w`'s settings; `v - w` works accordingly.
DateTimeDelta object v	DateTime object w	No operations defined.
DateTimeDelta object v	A number w	`v - w` returns a new DateTimeDelta object with a time delta value decremented by `w` seconds (can be given as float to indicate fractions of a second); `v + w` works accordingly; Note: you can use the object oneSecond to get similar effects in a more intuitive way; `v * w` returns a new DateTimeDelta object with a time delta value multiplied by `w`; `v / w` returns a new DateTimeDelta object with a time delta value divided by `w`; `v cmp w` Converts `v` to a signed float representing the delta in seconds and returns the result of comparing the seconds value to the number `w`.Note that the comparison will only yield correct results if the DateTimeDelta instance is placed on the left of the comparison operator (this is because of the coercion quirks mentioned above).
DateTimeDelta object v	DateTimeDelta object w	`v + w` returns a new DateTimeDelta object for the sum of the two time deltas (`(v+w).seconds == v.seconds + w.seconds`); `v - w` works accordingly; `v / w` returns a float equal to `v.seconds / w.seconds`.