Introduction

These types were created to provide a consistent way of transferring 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 values being encoded using 32bit integers, the limit is reached in 2038) and thus is Year 2000 and Year 2038 safe.

The primary absolute date/time type DateTime uses 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 (0001-01-01, the Christian Epoch (CE)), thus the Gregorian date 0001-01-01 corresponds to absolute date 1. Note that the Julian Epoch lies two days before the Gregorian one.

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) in the Gregorian calendar. This date corresponds to absolute day 1 and absolute time 0. Dates before the Epoch are handled by extrapolating the calendars using negative years as basis (the year 1 BCE corresponds to the year 0, 2 BCE is represented as year -1 and so on).

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

To handle relative time deltas 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 data.

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 (provided the underlying C lib knows about leap seconds -- most don't and the POSIX standard even invorces not to use leap seconds).

Calendars

The module supports two calendars, the Gregorian (default and needed for most conversions) and the Julian, which is handy for dates prior to the year 1582 when the calendar was revised by Pope Gregory XIII.

Construction of Julian dates can be done using either the JulianDateTime() constructor or indirect through the .Julian() method of DateTime instances. To check which calendar a DateTime instance uses, query the calendar instance attribute.

Note that Julian dates output the Julian date through the instances date attributes and broken down values. Not all conversions are available on instances using the Julian calendar. Even though in the Julian calendar days start at noon (12:00:00.0), mxDateTime will use the Gregorian convention of using the date for the period from 00:00:00.0 to 23:59:59.99 of that day. (This may change in future versions, though.)

Both calendars use mathematical models as basis -- they do not account for the many inaccuracies that occurred during their usage history. For this reason, the .absdate values should be interpreted with care, esp. for dates using the Julian calendar. As a result of the mathematical models, the Epochs in the calendars differ by a few days. This was needed in order to synchronize the calendars in the switching year 1582 (I'm still not 100% sure whether this is correct or not: JulianDate(1,1,1) lies two days before Date(1,1,1)).

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.

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.

UTC and GMT

UTC (Universal Time Code) and GMT (Greenich Mean Time) are two names for more or less the same thing: they both refer to the international universal time which is used throughout the world to coordinate events in time regardeless of time zone, day light savings time or other local time alterations. See the Calendar FAQ for more infos.

The mx.DateTime package uses these two names interchangeably. Sometimes API only refer to one name for simplicity. The name preference (GMT or UTC) is often chosen according to common usage.

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.

Background and Sources on the Web

Here is a small list of links I used as starting points to find some of the date/time related information included in this package:

• The Calendar FAQ by Claus Tondering.
• The Calendar Links by Rudy Limeback.
• The Ecclesiastical Calendar by Marcos J. Montes.
• The Systems of Time page provided by the Time Service Dept., U.S. Naval Observatory, Washington, DC.
• The Calendar Conversion page by Scott E. Lee.
• For the interested reader, I also suggest A walk through time presented by the NIST Time and Frequency Division.

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

1. DateTime for referring to absolute date/time values,
2. DateTimeDelta for date/time spans and
3. 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. All of these return DateTime instances using the Gregorian calendar except for JulienDateTime() which returns instances using the Julian calendar.

DateTime(year,month=1,day=1,hour=0,minute=0,second=0.0)

Constructs a DateTime instance from the given values.

Assumes that the date is given in the Gregorian calendar (which it the one used in many countries today).

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.

GregorianDateTime(year,month=1,day=1,hour=0,minute=0,second=0.0)

Is just another name binding for DateTime().

JulianDateTime(year,month=1,day=1, hour=0,minute=0,second=0.0)

Constructs a DateTime instance from the given values assuming they are given in the Julian calendar.

The instance will use the Julian calendar for all date related methods and attributes.

Same comments as for DateTime().

JulianDate(year,month=1,day=1)

Is just another name binding for JulianDateTime(). The time part is set to 00:00:00.0.

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(). The time part is set to 00:00:00.0.

GregorianDate(year,month,day)

Is just another name binding for DateTime(). The time part is set to 00:00:00.0.

mktime(tuple)

Same as the DateTime() constructor accept that the interface used is compatible to the similar time.mktime() API. tuple has to be a 9-tuple (year,month,day,hour,minute,second,dow,doy,dst).

Note that the tuple elements 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.

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.

localtime(ticks)

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.

now()

Returns a new DateTime instance reflecting the current local time.

gmt()

Returns a new DateTime instance reflecting the current GMT time.

utc()

Alias for gmt().

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 (Christian) Epoch value.

DateTimeFromCOMDate(comdate)

Constructs a DateTime instance from the COM date 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, 0001-01-01 00:00:00.00 is used. An Error is raised if the underlying C parsing function strptime() fails.

Portability note: default does not work on Solaris. You will have to reassemble the correct DateTime instance yourself (knowing which parts the strptime() function parsed) if you intend to use default values. Solaris sets the defaults to 1900-01-01 00:00:00.00 and then overwrites them with the parsed values.

Note: Since this C API 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).

DateTimeFromMJD(mjd)

Constructs a DateTime instance from the given Modified Julian Day (MJD) value.

Since MJD values are given in UTC, the instance will represent UTC. See the Calendar FAQ for details.

Note: Usage of MJD notation is discouraged by the International Astronomical Union (IAU). Use JDN instead.

DateTimeFromTJD(tjd,tjd_myriad=current_myriad)

Constructs a DateTime instance from the given Truncated Julian Day (TJD) value as used by NASA and the U.S. Naval Observatory, that is TJD = (MJD - 40000) % 10000 or simply TJD = MJD % 10000. Some sources define TJD = MJD - 40000 making it non-periodic; this is not supported by this constructor.

tjd_myriad will default to the tjd_myriad current at package import time, if not given. It refers to the truncated part of the TDJ number. The current myriad (245) started on 1995-10-10 00:00:00.00 UTC and will last until 2023-02-24 23:59:59.99 UTC.

Since TJD values are always given in UTC, the instance will represent UTC.

Please note that usage of TJD is depreciated because of the information loss involved with truncating data: use MJD or JDN instead.

DateTimeFromJDN(jdn)

Constructs a DateTime instance from the given Julian Day Number (JDN).

Since JDN values are given in UTC, the instance will represent UTC. See the Calendar FAQ for details.

DateTimeFrom(*args,**kws)

Constructs a DateTime instance from the arguments.

This constructor can parse strings, handle numeric arguments and knows about the keywords year,month,day,hour,minute,second.

It uses type inference to find out how to interpret the arguments and makes use of the Parser module.

TimestampFrom(*args,**kws)

Alias for DateTimeFrom().

DateFromTicks(ticks)

Constructs a DateTime instance pointing to the local time date at 00:00:00.00 (midnight) indicated by the given ticks value. The time part is ignored.

TimestampFromTicks(ticks)

Constructs a DateTime instance pointing to the local date and time indicated by the given ticks value.

DateTime Instance Methods

A DateTime instance has the following methods. Note that the calendar setting of the instance effects all methods relying on date values.

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 a RangeError 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 representing 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 RangeError exception if the objects value does not fit into the system's ticks range.

gmtoffset()

Returns a DateTimeDelta instance representing the UTC offset for the instance assuming that the stored values refer to local time. This is also sometimes called timezone.

The UTC offset is defined as: local time - UTC time, e.g. it is negative in the US and positive in eastern Europe and Asia.

gmtime()

Assuming that the instance refers to local time, this method returns new DateTime instance holding the corresponding UTC value.

localtime()

Assuming that the instance refers to UTC time, this method returns new DateTime instance holding the corresponding local time value.

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.

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.

Gregorian()

Returns a DateTime instance pointing to the same point in time but using the Gregorian calendar.

Julian()

Returns a DateTime instance pointing to the same point in time but using the Julian calendar.

DateTime Instance Variables

To make life easier, the instances also provide a more direct interface to their stored values (these are all read-only). Note that the calendar setting of the instance effects all attributes referring to date 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 second has a range of 0-60.

year, month, day

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

date, time

Returns the ISO representation of the date part as string. The format is [-]YYYY-MM-DD.

time

Returns the ISO representation of the time part as string. The format is HH:MM:SS.ss with ss being the truncated fraction of the seconds value.

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.

mjd

Returns a float representing the instance's value in terms of Modified Julian Days (1858-11-17 00:00:00.00 UTC being Modified Julian Day 0).

It is assumed for the calculation that the stored value is given in UTC. Fractions indicate parts of the full day, e.g. 0.5 referrs to noon on the 17 November 1858.

See the Calendar FAQ or Systems of Time for details.

Note: Usage of MJD notation is discouraged by the International Astronomical Union (IAU). Use JDN instead.

tjd

Returns a float representing the instance's value in terms of Truncated Julian Days (TJD).

TJDs are calculated using 00:00 UTC on 1 January 4713 BC as epoch, counting the number of days as for the Julian Day Numbers and then omitting the myriad part (div 10000) from it. As a result the TJD will always have at most 4 digits. The divisor is available through the tjd_myriad attribute.

It is assumed for the calculation that the stored value is given in UTC. Fractions indicate parts of the full day.

Some people claim that this term is also known under the name Star Date. Remember ? ... "Captain's Log, Star Date 8143.65". I wonder which myriad these dates refer to.

tjd_myriad

Returns the truncated part of the TJD representation.

jdn

Returns a float representing the instance's value as Julian Day Number (Julian Day Number 0 starts at 12:00 UTC on 1 January 4713 BC and ends 24 hours later at noon on 2 January 4713 BC).

It is assumed for the calculation that the stored value is given in UTC. Fractions indicate parts of the full day, e.g. JDN 2451170.17393 referrs to Tue, 22 Dec 1998 16:10:27 UTC.

See the Calendar FAQ for details.

calendar

Calendar used by the instance. This can either be the constant Julian or Gregorian.

DateTimeDelta Constructors

Several constructors are available:

DateTimeDelta(days[,hours=0.0,minutes=0.0,seconds=0.0])

Returns a new DateTimeDelta instance for the given time delta.

The internal value is calculated using the formula days*86400.0 + hours*3600.0 + minutes*60.0 + 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.

DateTimeDeltaFrom(*args,**kws)

Constructs a DateTimeDelta instance from the arguments.

This constructor can parser strings, handle numeric arguments and knows about the keywords year,month,day,hour,minute,second.

It uses type inference to find out how to interpret the arguments and makes use of the Parser module.

TimeDeltaFrom(*args,**kws)

Constructs a DateTimeDelta instance from the arguments.

The interface is the same as for DateTimeDeltaFrom() with the exception that numeric arguments are interpreted without day part as for the TimeDelta() constructor.

TimeFrom(*args,**kws)

Alias for TimeDeltaFrom().

TimeFromTicks(ticks)

Constructs a DateTimeDelta instance pointing to the local time indicated by the given ticks value. The date part is ignored.

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. 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 (these are all read-only):

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, weekday=None,weeks=0)

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.

Do not pass arguments directly, always use the keyword notation !

Absolute values passed to the constructor will override delta values of the same type. Note that weeks is added to days so that the instances days values will be days + 7*weeks.

weekday must be a 2-tuple if given: (day_of_week, nth). The value is applied after all other calculations have been done resulting in moving the date to the nth weekday in the month that the date points to. Negative values for nth result in the ordering of the month's weekdays to be reversed, e.g. (Monday,-1) will move to the last Monday in that month. Setting nth to 0 results in the date's week to be used as reference, e.g (Tuesday,0) will move to Tuesday that week (which could lie in a different month). weekday is considered an absolute value, so multiplication or negation will not touch it.

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

Is another name binding for RelativeDateTime. Do not pass arguments directly, always use the keyword notation !

RelativeDateTimeFrom(*args,**kws)

Constructs a RelativeDateTime instance from the arguments.

This constructor can parse strings, handle numeric arguments and knows about the same keywords as the RelativeDateTime() constructor.

It uses type inference to find out how to interpret the arguments and makes use of the Parser module.

RelativeDateFrom(*args,**kws)

Is another name binding for RelativeDateTime().

Note that in future versions this constructor may explicitly ignore the time parts.

RelativeTimeFrom(*args,**kws)

Is another name binding for RelativeDateTime().

Note that in future versions this constructor may explicitly ignore the date parts.

RelativeDateTimeDiff(date1,date2)

Returns a RelativeDateTime instance representing the difference between date1 and date2 in relative terms. The following should hold: date2 + RelativeDateDiff(date1,date2) == date1 for all dates date1 and date2.

Note that due to the algorithm used by this function, not the whole range of DateTime instances is supported; there could also be a loss of precision

This constructor is still experimental. It is not fully debugged yet.

RelativeDateDiff(date1,date2)

Is another name binding for RelativeDateTimeDiff().

Age(date1,date2)

Is another name binding for RelativeDateTimeDiff().

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.

Multiplying RelativeDateTime instances with numbers will yield instances with scaled deltas (absolute values are not effected).

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).

Note that dates like Date(1999,1,30) + RelativeDateTime(months=+1) are not supported. The package currently interprets these constructions as Date(1999,2,1) + 30, thus giving the 1999-03-02 which may not be what you'd expect.

When providing both delta and absolute values for an entity the absolute value is set first and then the delta applied to the outcome.

In tests, RelativeDateTime instances are false in case they do not define any date or time alterations and true otherwise.

A few examples will probably make the intended usage clearer:

>>> from mx.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

# Last Sunday in October 1998
>>> print Date(1998) + RelativeDateTime(weekday=(Sunday,-1),month=10)
1998-10-25 00:00:00.00

# The result in ARPA notation:
>>> print ARPA.str(Date(1998) + RelativeDateTime(weekday=(Sunday,-1),month=10))
Sun, 25 Oct 1998 00:00:00 +0200

# Generic way of specifying "next tuesday":
>>> NextTuesday = RelativeDateTime(days=+6,weekday=(Tuesday,0))
	

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, weekday

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. RangeError is a subclass of Error.

DateTimeType, DateTimeDeltaType

The type objects for the two types.

Epoch

A DateTime instance pointing to the Christian Epoch, i.e. 0001-01-01 00:00:00.00.

mxDateTimeAPI

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

MaxDateTime, MinDateTime, MaxDateTimeDelta, MinDateTimeDelta

These constants define the accepted ranges for the basic types. The values depend on the ranges of C longs on your platform.

Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday

Weekdays encoded as integers. Monday maps to 0, Tuesday to 1 and so on.

Weekday

Mapping that maps weekdays to integers and integers to weekdays. Monday maps to 0, Tuesday to 1 and so on.

January, February, March, April, May, June, July, August, September, October, November, December

Months encoded as integers. January maps to 1, February to 2 and so on.

Month

Mapping that maps months to integers and integers to months. January maps to 1, February to 2 and so on.

Gregorian, Julian

The objects returned by calendar attribute of DateTime objects. Currently these are the strings 'Gregorian' and 'Julian', but this mught change in future versions: always use these objects for checking the calendar type.

POSIX

Constant stating the POSIX compatibility of the system w/r to Unix ticks.

If the system's time package uses POSIX time_t values (without counting leap seconds), it is set to 1. In case the system's ticks values include leap seconds and thus correctly represent the term "seconds since the epoch", the constant is set to 0.

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.

DEPRECIATED: Use the .gmticks() method instead.

utcticks(datetime)

Alias for gmticks().

DEPRECIATED: Use the .gmticks() method instead.

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.

DEPRECIATED: Use the .gmtoffset() method instead.

gm2local(datetime)

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

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.

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 ISO document is also available as PDF file). The most common format is:

YYYY-MM-DD HH:MM:SS[+-HH:MM]

Note: timezone information (+-HH:MM) 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.

Time zone information is parsed, but not evaluated.

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:

ParseDate(arpastring)

Returns a DateTime instance reflecting the given ARPA date. Any time part included in the string is silently ignored.

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 GMT using the 'GMT' timezone indicator.

Note: Most Internet software expects to find 'GMT' and not 'UTC'.

strUTC(datetime)

Returns the datetime instance as ARPA date string assuming it is given in UTC using the 'UTC' timezone indicator.

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), GoodFriday(year), Karfreitag(year), VendrediSaint(year)

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

• Ascension(year), Himmelfahrt(year)

• Pentecost(year), WhitSunday(year), Pfingstsonntag(year), DimanchePentecote(year)

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

• TrinitySunday(year)

• CorpusChristi(year), Fronleichnam(year), FeteDieu(year)

For further reading, have a look at the Ecclesiastical Calendar.

Parser Submodule

The Parser submodule provides constructors for DateTime[Delta] values taking a string as input. The module knows about quite a few different date and time formats and will try very hard to come up with a reasonable output given a valid input.

Date/time parsing is a very diffcult field of endeavour and that's why the exact definition of what the module can parse and what not is defined by implementation rather than a rigorous set of formats.

Note: The module still has experimental status. It is constantly being improved. This can also mean that some formats might be dropped again in favour of more general parsing regexps.

Things the module will recognize are the outputs of ISO, ARPA and the .strftime() method. Currently only English, German, French, Spanish and Portuguese month and day names are supported. Have a look at the source code (Parser.py) for a full list of compatible date/time formats.

The module defines these constructors and functions:

DateTimeFromString(text[, formats, defaultdate])

Returns a DateTime instance reflecting the date and time given in text. In case a timezone is given, the returned instance will point to the corresponding UTC time value. Otherwise, the value is set as given in the string.

formats may be set to a tuple of strings specifying which of the following parsers to use and in which order to try them. Default is to try all of them in the order given below:

• 'euro' - the European date parser
• 'us' - the US date parser
• 'altus' - the alternative US date parser (with '-' instead of '/')
• 'iso' - the ISO date parser
• 'altiso' - the alternative ISO date parser (without '-')
• 'lit' - the US literal date parser
• 'altlit' - the alternative US literal date parser
• 'eurlit' - the Eurpean literal date parser
• 'unknown' - if no date part is found, use defaultdate

defaultdate provides the defaults to use in case no date part is found. Most other parsers default to the current year January 1 if some of these date parts are missing.

If 'unknown' is not given in formats and the date/time cannot be parsed, a ValueError is raised.

DateFromString(text[, formats, defaultdate])

Returns a DateTime instance reflecting the date given in text. A possibly included time part is ignored; the time part is always set to 0:00:00.00.

formats and defaultdate work just like for DateTimeFromString().

DateTimeDeltaFromString(text)

Returns a DateTimeDelta instance reflecting the delta given in text. Defaults to 0:00:00:00.00 for parts that are not included in the textual representation or cannot be parsed.

TimeFromString(text)

Alias for DateTimeDeltaFromString().

TimeDeltaFromString(text)

Alias for DateTimeDeltaFromString().

RelativeDateTimeFromString(text)

Returns a RelativeDateTime instance reflecting the relative date and time given in text.

Defaults to wildcards (None or 0) for parts or values which are not included in the textual representation or cannot be parsed.

The format used in text must adhere to the following ISO-style syntax:

[YYYY-MM-DD] [HH:MM[:SS]]

with the usual meanings.

Values which should not be altered may be replaced with '*', '%', '?' or any combination of letters, e.g. 'YYYY'. Relative settings must be enclosed in parenthesis if given and should include a sign, e.g. '(+0001)' for the year part. All other settings are interpreted as absolute values.

Date and time parts are both optional as a whole. Seconds in the time part are optional too. Everything else (including the hyphens and colons) is mandatory.

RelativeDateFromString(text)

Same as RelativeDateTimeFromString(text) except that only the date part of text is taken into account.

RelativeTimeFromString(text)

Same as RelativeDateTimeFromString(text) except that only the time part of text is taken into account.

The parsing routines ignore surrounding whitespace. Additional characters and symbols are ignored.

NIST Submodule

The NIST submodule is useful when you are connected to the Internet and want access to the accurate world standard time, the NIST atomic clocks.

The module accesses a special service provided by NIST and other partner organizations, which allows anyone with Internet access to query the current UTC time. Of the three provided protocols, daytime, time and ntp, I chose the daytime protocol because of its simplicity and robustness.

Since access through the Internet can be slow, the module also provides a way to calibrate itself and then use the computer's clock without the need to go accross the Internet for every call to the current time constructors. The defaults are set in such a way that calibration occurrs without further interaction on part of the programmer. See the code for details.

The module defines these constructors and functions:

utctime(nist_lookup=0)

Returns the current UTC time as DateTime instance.

Works must like the standard DateTime.now(), but tries to use the NIST time servers as time reference -- not only the computer's builtin clock.

Note that the contructor may take several seconds to return in case no calibration was performed (see calibrate()). With calibration information, the computer's clock is used as reference and the offset to NIST time is compensated by the contructor.

In case the NIST service is not reachable, the contructor falls back to using either the calibrated (preferred) or uncalibrated computer's clock.

Setting nist_lookup to false (default) will cause the contructor to prefer the calibrated CPU time over the expensive Internet queries. If it is true, then Internet lookups are always tried first before using the local clock. A value of 2 will cause an Error (see below) to be raised in case the NIST servers are not reachable.

The constructor will use the received NIST information for auto calibration.

gmtime()

Alias for utctime().

localtime(nist_lookup=0)

Returns the current local time as DateTime instance.

Same notes as for utctime().

now()

Alias for localtime().

time_offset(iterations=10)

Returns the average offset of the computer's clock to the NIST time base in seconds.

If you add the return value to the return value of time.time(), you will have a pretty accurate time base to use in your applications.

Note that due to network latencies and the socket overhead, the calculated offset will include a small hopefully constant error.

iterations sets the number of queries done to the NIST time base. The average is taken over all queries.

calibrate(iterations=20)

Calibrates the localtime() and gmtime() functions supplied in this module (not the standard ones in DateTime !).

Uses the NIST time service as time base. The computer must have an active internet connection to be able to do calibration using the NIST servers.

iterations sets the number of round to be done.

Note: This function takes a few seconds to complete. For long running processes you should recalibrate every now and then because the system clock tends to drift (usually more than the hardware clock in the computer).

set_calibration(calibration_offset)

Sets the calibration to be use by localtime() and utctime().

This also sets the global calibrated to 1 and disables auto calibration.

reset_auto_calibration()

Enables and resets the auto calibration for a new round.

This does not clear possibly available calibration information, so the two time APIs will continue to revert to the calibrated clock in case no connection to the NIST servers is possible.

Auto calibration is on per default when the module is imported.

enable_auto_calibration()

Currently an alias for reset_auto_calibration().

disable_auto_calibration()

Turns auto calibration off.

The package defines these constants:

Error

This exception is raised by the contructors in case no connection to the NIST service was possible.

calibration

Current calibration offset (NIST - CPU time) in seconds.

calibrated

True in the global calibration contains valid information.

calibrating

If true, the module will Try to auto-calibrate itself whenever the NIST servers are reachable.

There's an example called AtomicClock.py in the Examples/ subdir which demonstrates how easy it is to turn your PC into a fairly accurate time piece.

For even better time accuracy, one would have to use NTP...

eGenix.com is providing commercial support for this package. If you are interested in receiving information about this service please see the eGenix.com Support Conditions.

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

• Is there anything important still missing ?

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

© 2000-2001, Copyright by eGenix.com Software GmbH, Langenfeld, Germany; All Rights Reserved. mailto: info@egenix.com

This software is covered by the eGenix.com Public License Agreement. The text of the license is also included as file "LICENSE" in the package's main directory.

By downloading, copying, installing or otherwise using the software, you agree to be bound by the terms and conditions of the eGenix.com Public License Agreement.

Things that still need to be done:

• Provide some more examples.

• Add timezone information to the parsing routines or maybe even to DateTime instances. This likely to cause some trouble with old code, but I think it's worth considering.

• Fix bugs in RelativeDateTime addition and RelativeDateTimeDiff().

• Add Carel Fellinger's age() function.

• Add DateTime string format validation APIs to the Parser module.

Things that changed from 2.0.2 to 2.0.3:

• Made the date/time parser case-insensitive and extended it to also parse many Eurpean literal date/time formats, such as 'Sonntag, der 6. November 1994, 08:49:37 GMT'

• Fixed a bug in TimeFromTicks(); thanks to Alex Martelli for finding this one.

• Added a new example numdate.py by J.J. Dukarm to the Examples directory which demonstrates writing date/time parsers using different more strict conventions. Thanks to JJD for this one !

• Fixed the Max/MinDateTime constant and the range checks in mxDateTime.c to 32-bit values. This allows mxDateTime to compile correctly on 64-bit platforms. Thanks to Trond Glomsrod for pointing this out.

• Made the date/time parser even more flexible and added support for partial date formats ('month/day', 'litmonth day', 'day.month.') as well as mixes of different formats. Another new supported format is 'MM-DD-YYYY' (note that the four year digits are important to distinguish this format from ISO).

• Added 'AM/PM' support to the Parser module.

• Made the C extension extra careful about float rounding bugs, so that dates like 2001-01-01 24:00:00 don't happen anymore. Chuck Esterbrook mentioned that 2.0.2 still had problems on Mandrake (sigh) with e.g. DateTime(2000,12,31)+1.

• Fixed the REs in DateTime.Parser to work with sre from Python 2.2 (group names have to be unique).

Things that changed from 2.0.0 to 2.0.2:

• Fixed two typos in the Locale submodule. Thanks to Raul Garcia Garcia for spotting these.

• Fixed a bug in the coercion code which surfaced due to the rich comparison changes in Python 2.1. Python 2.1 will now compare DateTime[Delta] objects to other objects without raising a TypeError.

Things that changed from 1.3.0 to 2.0.0:

• Fixed a bug in the Parser submodule that caused two digit years to not fail parsing.

• Added more verbose RangeError messages. They now include the value in question.

• Changed: The .calendar attributes of DateTime instances now always return the new constants Gregorian or Julian. They are currently still implemented as strings, but this might change in future versions.

• The module now checks the system's time functions for POSIX compatibility. In case it finds that the system does not use leap seconds in Unix ticks, it reverts to a simpler and faster method method for calculating the GMT ticks value from broken down values. This should significantly speed up processing on platforms that don't have timegm() and use POSIX ticks.

• Added the constants Julian, Gregorian and POSIX.

• Fixed a doc-bug: the constructor of DateTimeDelta objects has a different signature than what was previously documented -- strange enough, nobody seems to have noticed this. Perhaps everybody is using the Time() constructor instead ...

• Fixed a bug in Y2000.py: forgot to import sys. Thanks to Chad Netzer for finding this one.

• Changed: The C API eported by the C extension module is now searched under the import path 'mx.DateTime' first. The old path 'DateTime' is only used as fallback solution.

• Fixed a bug in the algorithm for .iso_weeks. It failed to calculate the right ISO week for a few dates. Thanks to Gregor Ottmann for finding this one.

• Fixed a bug that caused day_of_week to be wrong for negative dates (in case anyone cares: .iso_weeks/ISO.* now also work for negative dates).

• Changed the internal handling of the time.time() function. The reference is now set by the mxDateTime/__init__.py module which should hopefully solve some problems with using mxDateTime in PyApache setups.

• Added .time and .date attributes to DateTime objects.

• Fixed a bug in the calculation of weekdays for B.C. years. Thanks to Vadim Zeitlin for spotting this one.

• Fixed a bug in the __radd__ method of RelativeDateTime instances: the month part wasn't correctly handled. Thanks to Paul Epp for finding the bug.

• Added some extra checks to gmtime() calls which caused .gmticks() to sometimes seg fault on WinNT 4 SP4. Found by Gordon McMillan.

• Fixed a rounding bug in localtime() and gmtime(). Found by Vadim Chugunov.

• Fixed a doc-bug in the defintion of TJD. Thanks to Tadayoshi Funaba for spotting this one.

• Added fixes to make mxDateTime compile on OpenVMS. Thanks to Jean-François Piéronne for the patches. He also provided setup instructions (see the Installation section).

• Changed: The mktime() constructor was changed to reflect the Python 1.6 change in tuple argument handling. The constructor now only accepts a 9-tuple.

• Redesigned the internals of the Parser module. It now correctly parses RFC822/RFC1123, RFC850/RFC1036, ANSI C's asctime() format, ISO format and probably a dozen more alternative formats. Thanks to Skip Montanaro for bugging me to fix it ;-)

• Added parsers for RelativeDateTime() string representations.

• Added __nonzero__ method to RelativeDateTime instances: they are considered false in case they do not define any date or time alterations.

• The Parser API will now include the original string in RangeError messages which occurred during parsing. Thanks to Skip Montanaro for suggesting this.

• Added gmt(), utc(), datetime.gmtime() and datetime.localtime(); the conversion support is not 100% robust during DST switching hours, but they work just fine at all other times.

• Added optional faster native API for querying the current system time. See Setup.in or mxDateTime.c for details on how to enable it. The speedup is not tremendous, so it may not be worthwhile the trouble -- unlike time.time() integers, DateTime instances are broken down to the various date/time values at construction time and this consumes quite a few cycles.

• Added GregorianDateTime() and GregorianDate() as aliases for DateTime() and Date() for completeness.

• Added workaround for rounding bug on Linux Mandrake. Thanks to John Janecek for bringing this up.

• Moved the package under a new top-level package 'mx'. It is part of the eGenix.com mx BASE distribution.

Things that changed from 1.2.0 to 1.3.0:

• Added a set of new constructors needed to ease use of mxDateTime for DB API 2.0 compliant database modules: DateFromTicks, TimestampFromTicks, TimeFromTicks.

• Changed: The seconds part is no longer rounded prior to applying the strftime() C API. It is now truncated per default. This means that datetime.strftime() will now always display the seconds integral part as shown when using str(datetime). Thanks to Shawn Dyer for pointing this out.

  The exported C API DateTime_AsTmStruct() will also reflect this change, since it uses the same conversion routines.

• Fixed a bug in the ISO parser: a backslash was missing which caused parsing of timezone information to fail. Thanks to Uche Ogbuji for finding the bug.

• Extended the timezone parser in ISO.py to handle 'Z' timezone indicators and hours only offsets.

• Corrected the JDN bug DateTimeFromJDN(0).jdn == 1.

• Corrected a bug in the calculation of Julian dates: previous versions didn't take into account that the Julian Epoch is not the same as the Gregorian one. The Julian calendar implementation should now be correct -- at least it gives correct dates for all historic dates I could get my hands on (which aren't as many as I had expected to find on the net :-/).

• Changed: Adding/Subtracting DateTime instances using the Julian calendar now causes the new instance to use the Julian calendar as well.

• Added support for Truncated Julian Day Numbers (TJD). Both a DateTime attribute (tjd) and a constructor (DateTimeFromTJD) are available.

• Cleaned up the code somewhat to eliminate multiple instances of the same algorithms.

• Modified the test suite to also check the JDN values and the Julian date constructor.

• Corrected a bug that caused repr(datetime) to be the same as str(datetime).

• Added RelativeDateTimeDiff() et al. inspired by a suggestion from Carel Fellinger for an age calculating function.

• Added NIST submodule and AtomicClock.py example.

Things that changed from 1.1.0 to 1.2.0:

• Fixed a few typos in the Feasts and Locale submodules. The changes were: Frohnleichnam -> Fronleichnam and introduction of GoodFriday and VendrediSaint. Thanks to Wolfgang Weitz for the spell check.

• Fixed a minor bug in localtime() and gmtime(). Thanks to Just van Rossum for finding it (it caused an OverflowError on Macs).

• Added some additional range checks to prevent the module from crashing on huge date/time values and deltas due to integer overflows.

• Reformatted some doc-strings and parts of the documentation.

• Added TrinitySunday and Pentecost to the Feasts submodule.

• ARPA.strUTC() and ARPA.strGMT() now return strings using 'UTC' and 'GMT' resp. Most Internet software expects the string 'GMT' and usually doesn't know how to handle 'UTC'.

• Added ARPA.ParseDate().

• Added new undocumented and experimental submodules Parser and Timezone.

• Added negative years to DateTime instances. The package follows the convention used in astronomy which maps the year 0 to 1 B.C.E., -1 to 2 B.C.E., etc. You may need to change code that does not expect negative years as input.

  XXX Note that the support is still experimental and still contains some bugs that need fixing... e.g. DateTimeFromJDN(0).jdn == 1.

• Added a few more constants for months and weekdays.

• Changed the Month attribute in the Locale instances to a mapping.

• The packages RangeError is now a subclass of the packages Error.

• Changed the exception types for range errors to always use DateTime.RangeError instead of OverflowError.

• Fixed a formatting quirk that cause DateTimeDelta instances to display a negative seconds entry for -DateTimeDelta(0) in their string repesentation.

• Added experimental generic constructors DateTimeFrom(), DateTimeDeltaFrom() and TimeDeltaFrom().

• Fixed the base classes of the two error objects Error and RangeError: Error has StandardError as base class and RangeError is a subclass of Error.

• Changed the now() API to a C function taking no arguments. Since this is needed quite frequently it should give better performance. The function uses the standard Python time module to query the system time. The documentation for the localtime() function now drops the default argument previously used -- it still works, but is depreciated.

  Note that the function no longer does rounding of the seconds part: you get the full precision returned by the time.time() function (which is system dependent).

• Fixed a bug in the constructor DateTimeFromAbsDays().

• Corrected the behaviour of .dst and .tz to also respect the time of day.

• Added a hack to work around a missing timegm() API. MacOS is one candidate that does not supply this function. The used workaround should provide the same functionality at a small performance penalty.

  If you have the timegm() API, enable it in Setup -- it's more accurate and probably faster too.

• Depreciated functions gmticks(), utcticks() and tz_offset(). Use the corresponding methods .gmticks() and .gmtoffset() instead.

• Added .gmtoffset() method.

• Added calendar support for Gregorian and Julian calendars.

• Included precompiled MacOS binaries donated by Joseph Strout. Thanks, Joseph !

• Fixed a bug in Timezone.utc_offset().

Things that changed from 1.0.1 to 1.1.0:

• Fixed the hour range check to not accept 24 as input anymore. Seconds may only have a value between 60.0 and 61.0 for the minute 23:59. The constructor will now raise a RangeError if it sees other values. Thanks to Jarkko Torppa for pointing me at it.

• Changed the keyword order for the RelativeDateTime constructors. This shouldn't effect any code, since normal usage is passing the parameters as keywords anyway.

• Added weekday and weeks parameters to RelativeDateTime; made the instances handle multiplication, negation and division, e.g. RelativeDateTime(days=4) / 2 is the same as RelativeDateTime(days=2). Note that comparing RelativeDateTime instances does not work.

• Added support for [Modified] Julian Day numbers: constructors and instance variables are available. This might be useful when you do astronomical date/time calculations and makes the types even more compatible to common date/time representations.

• RelativeDateTime now allow providing both absolute and delta values for all entities. The delta value is added after the absolute value has been set, e.g. RelativeDateTime(day=1,days=-1) will adjust to the last day of the previous month.

• Reduced the pickle sizes of both types a little more. DateTime instances now use about 49 bytes and DateTimeDelta instances around 37 bytes each (43 and 34 bytes if you pickle using the binary option).

• Made RelativeDateTime instances handle negative day settings like DateTime constructors: RelativeDateTime(day=-1) will adjust to the last day of the month.

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.