Log message for revision 40402: Convert DateTime.txt to reST and a (pretty extensive) doctest.
Changed: U Zope/trunk/lib/python/DateTime/DateTime.txt U Zope/trunk/lib/python/DateTime/tests/testDateTime.py -=- Modified: Zope/trunk/lib/python/DateTime/DateTime.txt =================================================================== --- Zope/trunk/lib/python/DateTime/DateTime.txt 2005-11-29 07:45:24 UTC (rev 40401) +++ Zope/trunk/lib/python/DateTime/DateTime.txt 2005-11-29 14:30:14 UTC (rev 40402) @@ -1,550 +1,782 @@ -DateTime - - Encapsulation of date/time values +==================== +The DateTime package +==================== -Module Functions +Encapsulation of date/time values. -Timezones() - - Return the list of recognized timezone names - + +Function Timezones() +==================== + +Returns the list of recognized timezone names: + + >>> from DateTime import Timezones + >>> Timezones() # doctest: +ELLIPSIS + ['Brazil/Acre', 'Brazil/DeNoronha', ..., 'NZST', 'IDLE'] + + Class DateTime +============== DateTime objects represent instants in time and provide interfaces for -controlling its representation without affecting the absolute value of the -object. +controlling its representation without affecting the absolute value of +the object. -DateTime objects may be created from a wide variety of string or numeric data, -or may be computed from other DateTime objects. DateTimes support the ability -to convert their representations to many major timezones, as well as the -ablility to create a DateTime object in the context of a given timezone. +DateTime objects may be created from a wide variety of string or +numeric data, or may be computed from other DateTime objects. +DateTimes support the ability to convert their representations to many +major timezones, as well as the ablility to create a DateTime object +in the context of a given timezone. DateTime objects provide partial numerical behavior: - * Two date-time objects can be subtracted to obtain a time, in days between - the two. - - * A date-time object and a positive or negative number may be added to obtain - a new date-time object that is the given number of days later than the - input date-time object. - - * A positive or negative number and a date-time object may be added to obtain - a new date-time object that is the given number of days later than the - input date-time object. - - * A positive or negative number may be subtracted from a date-time object to - obtain a new date-time object that is the given number of days earlier than - the input date-time object. - -DateTime objects may be converted to integer, long, or float numbers of days -since January 1, 1901, using the standard int, long, and float functions -(Compatibility Note: int, long and float return the number of days since 1901 -in GMT rather than local machine timezone). DateTime objects also provide -access to their value in a float format usable with the python time module, -provided that the value of the object falls in the range of the epoch-based -time module. +* Two date-time objects can be subtracted to obtain a time, in days + between the two. +* A date-time object and a positive or negative number may be added to + obtain a new date-time object that is the given number of days later + than the input date-time object. + +* A positive or negative number and a date-time object may be added to + obtain a new date-time object that is the given number of days later + than the input date-time object. + +* A positive or negative number may be subtracted from a date-time + object to obtain a new date-time object that is the given number of + days earlier than the input date-time object. + +DateTime objects may be converted to integer, long, or float numbers +of days since January 1, 1901, using the standard int, long, and float +functions (Compatibility Note: int, long and float return the number +of days since 1901 in GMT rather than local machine timezone). +DateTime objects also provide access to their value in a float format +usable with the python time module, provided that the value of the +object falls in the range of the epoch-based time module. + A DateTime object should be considered immutable; all conversion and numeric operations return a new DateTime object rather than modify the current object. -Constructor For DateTime - - DateTime() - - Return a new date-time object - - A DateTime object always maintains its value as an absolute UTC time, - and is represented in the context of some timezone based on the - arguments used to create the object. A DateTime object's methods return - values based on the timezone context. - - Note that in all cases the local machine timezone is used for - representation if no timezone is specified. - - DateTimes may be created with from zero to seven arguments. - - o If the function is called with no arguments, then the current date/ - time is returned, represented in the timezone of the local machine. - - o If the function is invoked with a single string argument which is a - recognized timezone name, an object representing the current time - is returned, represented in the specified timezone. - - o If the function is invoked with a single string argument - representing a valid date/time, an object representing that date/ - time will be returned. - - As a general rule, any date-time representation that is recognized - and unambigous to a resident of North America is acceptable.(The - reason for this qualification is that in North America, a date - like: 2/1/1994 is interpreted as February 1, 1994, while in some - parts of the world, it is interpreted as January 2, 1994.) A date/ - time string consists of two components, a date component and an - optional time component, separated by one or more spaces. If the - time component is omited, 12:00am is assumed. Any recognized - timezone name specified as the final element of the date/time - string will be used for computing the date/time value. (If you - create a DateTime with the string Mar 9, 1997 1:45pm US/Pacific, - the value will essentially be the same as if you had captured - time.time() at the specified date and time on a machine in that - timezone) - - - - e=DateTime(US/Eastern) - # returns current date/time, represented in US/Eastern. - - - - - - x=DateTime(1997/3/9 1:45pm) - # returns specified time, represented in local machine zone. - - - - - - y=DateTime(Mar 9, 1997 13:45:00) - # y is equal to x - - - - - - - - The date component consists of year, month, and day values. The - year value must be a one-, two-, or four-digit integer. If a one- - or two-digit year is used, the year is assumed to be in the - twentieth century. The month may an integer, from 1 to 12, a month - name, or a month abreviation, where a period may optionally follow - the abreviation. The day must be an integer from 1 to the number of - days in the month. The year, month, and day values may be separated - by periods, hyphens, forward, shashes, or spaces. Extra spaces are - permitted around the delimiters. Year, month, and day values may be - given in any order as long as it is possible to distinguish the - components. If all three components are numbers that are less than - 13, then a a month-day-year ordering is assumed. - - The time component consists of hour, minute, and second values - separated by colons. The hour value must be an integer between 0 - and 23 inclusively. The minute value must be an integer between 0 - and 59 inclusively. The second value may be an integer value - between 0 and 59.999 inclusively. The second value or both the - minute and second values may be ommitted. The time may be followed - by am or pm in upper or lower case, in which case a 12-hour clock - is assumed. - - o If the DateTime function is invoked with a single Numeric argument, - the number is assumed to be either a floating point value such as - that returned by time.time() , or a number of days after January 1, - 1901 00:00:00 UTC. - - A DateTime object is returned that represents either the gmt value - of the time.time() float represented in the local machine's - timezone, or that number of days after January 1, 1901. Note that - the number of days after 1901 need to be expressed from the - viewpoint of the local machine's timezone. A negative argument will - yield a date-time value before 1901. - - o If the function is invoked with two numeric arguments, then the - first is taken to be an integer year and the second argument is - taken to be an offset in days from the beginning of the year, in - the context of the local machine timezone. The date-time value - returned is the given offset number of days from the beginning of - the given year, represented in the timezone of the local machine. - The offset may be positive or negative. Two-digit years are assumed - to be in the twentieth century. - - o If the function is invoked with two arguments, the first a float - representing a number of seconds past the epoch in gmt (such as - those returned by time.time()) and the second a string naming a - recognized timezone, a DateTime with a value of that gmt time will - be returned, represented in the given timezone. - import time - t=time.time() - - - - now_east=DateTime(t,'US/Eastern') - # Time t represented as US/Eastern - - - - - - now_west=DateTime(t,'US/Pacific') - # Time t represented as US/Pacific - - - - - - # now_east == now_west - # only their representations are different - - - - - - - - o If the function is invoked with three or more numeric arguments, - then the first is taken to be an integer year, the second is taken - to be an integer month, and the third is taken to be an integer - day. If the combination of values is not valid, then a - DateTimeError is raised. Two-digit years are assumed to be in the - twentieth century. The fourth, fifth, and sixth arguments are - floating point, positive or negative offsets in units of hours, - minutes, and days, and default to zero if not given. An optional - string may be given as the final argument to indicate timezone (the - effect of this is as if you had taken the value of time.time() at - that time on a machine in the specified timezone). - - If a string argument passed to the DateTime constructor cannot be - parsed, it will raise DateTime.SyntaxError. Invalid date, time, or - timezone components will raise a DateTime.DateTimeError. - - The module function Timezones() will return a list of the timezones - recognized by the DateTime module. Recognition of timezone names is - case-insensitive. - -Instance Methods For DateTime - - aMonth() - - Return the abreviated month name. - - pCommon() - - Return a string representing the object's value in the format: Mar. 1, - 1997 1:45 pm - - minute() - - Return the minute - - isLeapYear() - - Return true if the current year (in the context of the object's - timezone) is a leap year - - pMonth() - - Return the abreviated (with period) month name. - - DayOfWeek() - - Compatibility: see Day - - Day_() - - Compatibility: see pDay - - isCurrentDay() - - Return true if this object represents a date/time that falls within the - current day, in the context of this object's timezone representation - - Mon() - - Compatibility: see aMonth - - hour() - - Return the 24-hour clock representation of the hour - - Date() - - Return the date string for the object. - - aCommonZ() - - Return a string representing the object's value in the format: Mar 1, - 1997 1:45 pm US/Eastern - - fCommonZ() - - Return a string representing the object's value in the format: March 1, - 1997 1:45 pm US/Eastern - - isCurrentYear() - - Return true if this object represents a date/time that falls within the - current year, in the context of this object's timezone representation - - AMPMMinutes() - - Return the time string for an object not showing seconds. - - dd() - - Return day as a 2 digit string - - TimeMinutes() - - Return the time string for an object not showing seconds. - - h_24() - - Return the 24-hour clock representation of the hour - - isPast() - - Return true if this object represents a date/time earlier than the time - of the call - - dow() - - Return the integer day of the week, where sunday is 0 - - isFuture() - - Return true if this object represents a date/time later than the time - of the call - - pCommonZ() - - Return a string representing the object's value in the format: Mar. 1, - 1997 1:45 pm US/Eastern - - timezone() - - Return the timezone in which the object is represented. - - h_12() - - Return the 12-hour clock representation of the hour - - PreciseTime() - - Return the time string for the object. - - isCurrentMinute() - - Return true if this object represents a date/time that falls within the - current minute, in the context of this object's timezone representation - - rfc822() - - Return the date in RFC 822 format - - equalTo(t) - - Compare this DateTime object to another DateTime object OR a floating - point number such as that which is returned by the python time module. - Returns true if the object represents a date/time equal to the - specified DateTime or time module style time. - - yy() - - Return calendar year as a 2 digit string - - mm() - - Return month as a 2 digit string - - Mon_() - - Compatibility: see pMonth - - toZone(z) - - Return a DateTime with the value as the current object, represented in - the indicated timezone. - - earliestTime() - - Return a new DateTime object that represents the earliest possible time - (in whole seconds) that still falls within the current object's day, in - the object's timezone context - - aDay() - - Return the abreviated name of the day of the week - - dayOfYear() - - Return the day of the year, in context of the timezone representation - of the object - - latestTime() - - Return a new DateTime object that represents the latest possible time - (in whole seconds) that still falls within the current object's day, in - the object's timezone context - - notEqualTo(t) - - Compare this DateTime object to another DateTime object OR a floating - point number such as that which is returned by the python time module. - Returns true if the object represents a date/time not equal to the - specified DateTime or time module style time. - - PreciseAMPM() - - Return the time string for the object. - - day() - - Return the integer day - - timeTime() - - Return the date/time as a floating-point number in UTC, in the format - used by the python time module. Note that it is possible to create date - /time values with DateTime that have no meaningful value to the time - module, and in such cases a DateTimeError is raised. A DateTime - object's value must generally be between Jan 1, 1970 (or your local - machine epoch) and Jan 2038 to produce a valid time.time() style value. - - ampm() - - Return the appropriate time modifier (am or pm) - - greaterThan(t) - - Compare this DateTime object to another DateTime object OR a floating - point number such as that which is returned by the python time module. - Returns true if the object represents a date/time greater than the - specified DateTime or time module style time. - - month() - - Return the month of the object as an integer - - AMPM() - - Return the time string for an object to the nearest second. - - second() - - Return the second - - parts() - - Return a tuple containing the calendar year, month, day, hour, minute - second and timezone of the object - - greaterThanEqualTo(t) - - Compare this DateTime object to another DateTime object OR a floating - point number such as that which is returned by the python time module. - Returns true if the object represents a date/time greater than or equal - to the specified DateTime or time module style time. - - lessThanEqualTo(t) - - Compare this DateTime object to another DateTime object OR a floating - point number such as that which is returned by the python time module. - Returns true if the object represents a date/time less than or equal to - the specified DateTime or time module style time. - - isCurrentHour() - - Return true if this object represents a date/time that falls within the - current hour, in the context of this object's timezone representation - - aCommon() - - Return a string representing the object's value in the format: Mar 1, - 1997 1:45 pm - - dow_1() - - Return the integer day of the week, where sunday is 1 - - Day() - - Return the full name of the day of the week - - fCommon() - - Return a string representing the object's value in the format: March 1, - 1997 1:45 pm - - Month() - - Return the full month name - - isCurrentMonth() - - Return true if this object represents a date/time that falls within the - current month, in the context of this object's timezone representation - - year() - - Return the calendar year of the object - - lessThan(t) - - Compare this DateTime object to another DateTime object OR a floating - point number such as that which is returned by the python time module. - Returns true if the object represents a date/time less than the - specified DateTime or time module style time. - - Time() - - Return the time string for an object to the nearest second. - - pDay() - - Return the abreviated (with period) name of the day of the week - +A DateTime object always maintains its value as an absolute UTC time, +and is represented in the context of some timezone based on the +arguments used to create the object. A DateTime object's methods +return values based on the timezone context. + +Note that in all cases the local machine timezone is used for +representation if no timezone is specified. + +Constructor for DateTime +------------------------ + +DateTime() returns a new date-time object. DateTimes may be created +with from zero to seven arguments: + +* If the function is called with no arguments, then the current date/ + time is returned, represented in the timezone of the local machine. + +* If the function is invoked with a single string argument which is a + recognized timezone name, an object representing the current time is + returned, represented in the specified timezone. + +* If the function is invoked with a single string argument + representing a valid date/time, an object representing that date/ + time will be returned. + + As a general rule, any date-time representation that is recognized + and unambigous to a resident of North America is acceptable. (The + reason for this qualification is that in North America, a date like: + 2/1/1994 is interpreted as February 1, 1994, while in some parts of + the world, it is interpreted as January 2, 1994.) A date/ time + string consists of two components, a date component and an optional + time component, separated by one or more spaces. If the time + component is omited, 12:00am is assumed. Any recognized timezone + name specified as the final element of the date/time string will be + used for computing the date/time value. (If you create a DateTime + with the string "Mar 9, 1997 1:45pm US/Pacific", the value will + essentially be the same as if you had captured time.time() at the + specified date and time on a machine in that timezone). + + o Returns current date/time, represented in US/Eastern: + + >>> from DateTime import DateTime + >>> e = DateTime('US/Eastern') + >>> e.timezone() + 'US/Eastern' + + o Returns specified time, represented in local machine zone: + + >>> x = DateTime('1997/3/9 1:45pm') + >>> x.parts() # doctest: +ELLIPSIS + (1997, 3, 9, 13, 45, 0.0, ...) + + o Specified time in local machine zone, verbose format: + + >>> y = DateTime('Mar 9, 1997 13:45:00') + >>> y.parts() # doctest: +ELLIPSIS + (1997, 3, 9, 13, 45, 0.0, ...) + >>> y == x + True + + The date component consists of year, month, and day values. The + year value must be a one-, two-, or four-digit integer. If a one- + or two-digit year is used, the year is assumed to be in the + twentieth century. The month may an integer, from 1 to 12, a month + name, or a month abreviation, where a period may optionally follow + the abreviation. The day must be an integer from 1 to the number of + days in the month. The year, month, and day values may be separated + by periods, hyphens, forward, shashes, or spaces. Extra spaces are + permitted around the delimiters. Year, month, and day values may be + given in any order as long as it is possible to distinguish the + components. If all three components are numbers that are less than + 13, then a a month-day-year ordering is assumed. + + The time component consists of hour, minute, and second values + separated by colons. The hour value must be an integer between 0 + and 23 inclusively. The minute value must be an integer between 0 + and 59 inclusively. The second value may be an integer value + between 0 and 59.999 inclusively. The second value or both the + minute and second values may be ommitted. The time may be followed + by am or pm in upper or lower case, in which case a 12-hour clock is + assumed. + +* If the DateTime function is invoked with a single Numeric argument, + the number is assumed to be either a floating point value such as + that returned by time.time() , or a number of days after January 1, + 1901 00:00:00 UTC. + + A DateTime object is returned that represents either the gmt value + of the time.time() float represented in the local machine's + timezone, or that number of days after January 1, 1901. Note that + the number of days after 1901 need to be expressed from the + viewpoint of the local machine's timezone. A negative argument will + yield a date-time value before 1901. + +* If the function is invoked with two numeric arguments, then the + first is taken to be an integer year and the second argument is + taken to be an offset in days from the beginning of the year, in the + context of the local machine timezone. The date-time value returned + is the given offset number of days from the beginning of the given + year, represented in the timezone of the local machine. The offset + may be positive or negative. Two-digit years are assumed to be in + the twentieth century. + +* If the function is invoked with two arguments, the first a float + representing a number of seconds past the epoch in gmt (such as + those returned by time.time()) and the second a string naming a + recognized timezone, a DateTime with a value of that gmt time will + be returned, represented in the given timezone. + + >>> import time + >>> t = time.time() + + Time t represented as US/Eastern: + + >>> now_east = DateTime(t, 'US/Eastern') + + Time t represented as US/Pacific: + + >>> now_west = DateTime(t, 'US/Pacific') + + Only their representations are different: + + >>> now_east == now_west + True + +* If the function is invoked with three or more numeric arguments, + then the first is taken to be an integer year, the second is taken + to be an integer month, and the third is taken to be an integer day. + If the combination of values is not valid, then a DateTimeError is + raised. Two-digit years are assumed to be in the twentieth century. + The fourth, fifth, and sixth arguments are floating point, positive + or negative offsets in units of hours, minutes, and days, and + default to zero if not given. An optional string may be given as + the final argument to indicate timezone (the effect of this is as if + you had taken the value of time.time() at that time on a machine in + the specified timezone). + +If a string argument passed to the DateTime constructor cannot be +parsed, it will raise DateTime.SyntaxError. Invalid date, time, or +timezone components will raise a DateTime.DateTimeError. + +The module function Timezones() will return a list of the timezones +recognized by the DateTime module. Recognition of timezone names is +case-insensitive. + +Instance Methods for DateTime (IDateTime interface) +--------------------------------------------------- + +Conversion and comparison methods +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* ``timeTime()`` returns the date/time as a floating-point number in + UTC, in the format used by the python time module. Note that it is + possible to create date /time values with DateTime that have no + meaningful value to the time module, and in such cases a + DateTimeError is raised. A DateTime object's value must generally + be between Jan 1, 1970 (or your local machine epoch) and Jan 2038 to + produce a valid time.time() style value. + + >>> dt = DateTime('Mar 9, 1997 13:45:00 US/Eastern') + >>> dt.timeTime() + 857933100.0 + + >>> DateTime('2040/01/01').timeTime() + 2208985200.0 + + >>> DateTime('1900/01/01').timeTime() + -2208992400.0 + +* ``toZone(z)`` returns a DateTime with the value as the current + object, represented in the indicated timezone: + + >>> dt.toZone('UTC') + DateTime('1997/03/09 18:45:00 Universal') + + >>> dt.toZone('UTC') == dt + True + +* ``isFuture()`` returns true if this object represents a date/time + later than the time of the call: + + >>> dt.isFuture() + False + >>> DateTime('Jan 1 3000').isFuture() # not time-machine safe! + True + +* ``isPast()`` returns true if this object represents a date/time + earlier than the time of the call: + + >>> dt.isPast() + True + >>> DateTime('Jan 1 3000').isPast() # not time-machine safe! + False + +* ``isCurrentYear()`` returns true if this object represents a + date/time that falls within the current year, in the context of this + object's timezone representation: + + >>> dt.isCurrentYear() + False + >>> DateTime().isCurrentYear() + True + +* ``isCurrentMonth()`` returns true if this object represents a + date/time that falls within the current month, in the context of + this object's timezone representation: + + >>> dt.isCurrentMonth() + False + >>> DateTime().isCurrentMonth() + True + +* ``isCurrentDay()`` returns true if this object represents a + date/time that falls within the current day, in the context of this + object's timezone representation: + + >>> dt.isCurrentDay() + False + >>> DateTime().isCurrentDay() + True + +* ``isCurrentHour()`` returns true if this object represents a + date/time that falls within the current hour, in the context of this + object's timezone representation: + + >>> dt.isCurrentHour() + False + + >>> DateTime().isCurrentHour() + True + +* ``isCurrentMinute()`` returns true if this object represents a + date/time that falls within the current minute, in the context of + this object's timezone representation: + + >>> dt.isCurrentMinute() + False + >>> DateTime().isCurrentMinute() + True + +* ``isLeapYear()`` returns true if the current year (in the context of + the object's timezone) is a leap year: + + >>> dt.isLeapYear() + False + >>> DateTime('Mar 8 2004').isLeapYear() + True + +* ``earliestTime()`` returns a new DateTime object that represents the + earliest possible time (in whole seconds) that still falls within + the current object's day, in the object's timezone context: + + >>> dt.earliestTime() + DateTime('1997/03/09') + +* ``latestTime()`` return a new DateTime object that represents the + latest possible time (in whole seconds) that still falls within the + current object's day, in the object's timezone context + + >>> dt.latestTime() + DateTime('1997/03/09 23:59:59 US/Eastern') + +Component access +~~~~~~~~~~~~~~~~ + +* ``parts()`` returns a tuple containing the calendar year, month, + day, hour, minute second and timezone of the object + + >>> dt.parts() + (1997, 3, 9, 13, 45, 0.0, 'US/Eastern') + +* ``timezone()`` returns the timezone in which the object is represented: + + >>> dt.timezone() in Timezones() + True + +* ``tzoffset()`` returns the timezone offset for the objects timezone: + + >>> dt.tzoffset() + -18000 + +* ``year()`` returns the calendar year of the object: + + >>> dt.year() + 1997 + +* ``month()`` retursn the month of the object as an integer: + + >>> dt.month() + 3 + +* ``Month()`` returns the full month name: + + >>> dt.Month() + 'March' + +* ``aMonth()`` returns the abreviated month name: + + >>> dt.aMonth() + 'Mar' + +* ``pMonth()`` returns the abreviated (with period) month name: + + >>> dt.pMonth() + 'Mar.' + +* ``day()`` returns the integer day: + + >>> dt.day() + 9 + +* ``Day()`` returns the full name of the day of the week: + + >>> dt.Day() + 'Sunday' + +* ``dayOfYear()`` returns the day of the year, in context of the + timezone representation of the object: + + >>> dt.dayOfYear() + 68 + +* ``aDay()`` returns the abreviated name of the day of the week: + + >>> dt.aDay() + 'Sun' + +* ``pDay()`` returns the abreviated (with period) name of the day of + the week: + + >>> dt.pDay() + 'Sun.' + +* ``dow()`` returns the integer day of the week, where Sunday is 0: + + >>> dt.dow() + 0 + +* ``dow_1()`` returns the integer day of the week, where sunday is 1: + + >>> dt.dow_1() + 1 + +* ``h_12()`` returns the 12-hour clock representation of the hour: + + >>> dt.h_12() + 1 + +* ``h_24()`` returns the 24-hour clock representation of the hour: + + >>> dt.h_24() + 13 + +* ``ampm()`` returns the appropriate time modifier (am or pm): + + >>> dt.ampm() + 'pm' + +* ``hour()`` returns the 24-hour clock representation of the hour: + + >>> dt.hour() + 13 + +* ``minute()`` returns the minute: + + >>> dt.minute() + 45 + +* ``second()`` returns the second: + + >>> dt.second() + 0.0 + +* ``millis()`` returns the milliseconds since the epoch in GMT. + + >>> dt.millis() + 857933100000L + +strftime() +~~~~~~~~~~ + +See ``tests/testDateTime.py``. + +General formats from previous DateTime +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* ``Date()`` return the date string for the object: + + >>> dt.Date() + '1997/03/09' + +* ``Time()`` returns the time string for an object to the nearest + second: + + >>> dt.Time() + '13:45:00' + +* ``TimeMinutes()`` returns the time string for an object not showing + seconds: + + >>> dt.TimeMinutes() + '13:45' + +* ``AMPM()`` returns the time string for an object to the nearest second: + + >>> dt.AMPM() + '01:45:00 pm' + +* ``AMPMMinutes()`` returns the time string for an object not showing + seconds: + + >>> dt.AMPMMinutes() + '01:45 pm' + +* ``PreciseTime()`` returns the time string for the object: + + >>> dt.PreciseTime() + '13:45:00.000' + +* ``PreciseAMPM()``return the time string for the object: + + >>> dt.PreciseAMPM() + '01:45:00.000 pm' + +* ``yy()`` returns the calendar year as a 2 digit string + + >>> dt.yy() + '97' + +* ``mm()`` returns the month as a 2 digit string + + >>> dt.mm() + '03' + +* ``dd()`` returns the day as a 2 digit string: + + >>> dt.dd() + '09' + +* ``rfc822()`` returns the date in RFC 822 format: + + >>> dt.rfc822() + 'Sun, 09 Mar 1997 13:45:00 -0500' + +New formats +~~~~~~~~~~~ + +* ``fCommon()`` returns a string representing the object's value in + the format: March 9, 1997 1:45 pm: + + >>> dt.fCommon() + 'March 9, 1997 1:45 pm' + +* ``fCommonZ()`` returns a string representing the object's value in + the format: March 9, 1997 1:45 pm US/Eastern: + + >>> dt.fCommonZ() + 'March 9, 1997 1:45 pm US/Eastern' + +* ``aCommon()`` returns a string representing the object's value in + the format: Mar 9, 1997 1:45 pm: + + >>> dt.aCommon() + 'Mar 9, 1997 1:45 pm' + +* ``aCommonZ()`` return a string representing the object's value in + the format: Mar 9, 1997 1:45 pm US/Eastern: + + >>> dt.aCommonZ() + 'Mar 9, 1997 1:45 pm US/Eastern' + +* ``pCommon()`` returns a string representing the object's value in + the format Mar. 9, 1997 1:45 pm: + + >>> dt.pCommon() + 'Mar. 9, 1997 1:45 pm' + +* ``pCommonZ()`` returns a string representing the object's value in + the format: Mar. 9, 1997 1:45 pm US/Eastern: + + >>> dt.pCommonZ() + 'Mar. 9, 1997 1:45 pm US/Eastern' + +* ``ISO()`` returns a string with the date/time in ISO format. Note: + this is not ISO 8601-format! See the ISO8601 and HTML4 methods below + for ISO 8601-compliant output. Dates are output as: YYYY-MM-DD HH:MM:SS + + >>> dt.ISO() + '1997-03-09 13:45:00' + +* ``ISO8601()`` returns the object in ISO 8601-compatible format + containing the date, time with seconds-precision and the time zone + identifier - see http://www.w3.org/TR/NOTE-datetime. Dates are + output as: YYYY-MM-DDTHH:MM:SSTZD (T is a literal character, TZD is + Time Zone Designator, format +HH:MM or -HH:MM). + + The ``HTML4()`` method below offers the same formatting, but + converts to UTC before returning the value and sets the TZD"Z" + + >>> dt.ISO8601() + '1997-03-09T13:45:00-05:00' + + +* ``HTML4()`` returns the object in the format used in the HTML4.0 + specification, one of the standard forms in ISO8601. See + http://www.w3.org/TR/NOTE-datetime. Dates are output as: + YYYY-MM-DDTHH:MM:SSZ (T, Z are literal characters, the time is in + UTC.): + + >>> dt.HTML4() + '1997-03-09T18:45:00Z' + +* ``JulianDay()`` returns the Julian day according to + http://www.tondering.dk/claus/cal/node3.html#sec-calcjd + + >>> dt.JulianDay() + 2450517 + +* ``week()`` returns the week number according to ISO + see http://www.tondering.dk/claus/cal/node6.html#SECTION00670000000000000000 + + >>> dt.week() + 10 + +Deprecated API +~~~~~~~~~~~~~~ + +* DayOfWeek(): see Day() + +* Day_(): see pDay() + +* Mon(): see aMonth() + +* Mon_(): see pMonth + General Services Provided by DateTime - - `aDateTime` - - Convert a DateTime to a string that looks like a Python expression. - - str(aDateTime) - - Convert a DateTime to a string. - - cmp(aDateTime, other) - - Compare a DateTime with another DateTime object, or a float such as - those returned by time.time(). - - NOTE: __cmp__ support is provided for backward compatibility only, and - mixing DateTimes with ExtensionClasses could cause __cmp__ to break. - You should use the methods lessThan, greaterThan, lessThanEqualTo, - greaterThanEqualTo, equalTo and notEqualTo to avoid potential problems - later!! - - hash(aDateTime) - - Compute a hash value for a DateTime - +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +DateTimes can be repr()'ed; the result will be a string indicating how +to make a DateTime object like this: + + >>> `dt` + "DateTime('1997/03/09 13:45:00 US/Eastern')" + +When we convert them into a string, we get a nicer string that could +actually be shown to a user: + + >>> str(dt) + '1997/03/09 13:45:00 US/Eastern' + +The hash value of a DateTime is based on the date and time and is +equal for different representations of the DateTime: + + >>> hash(dt) + 3618678 + >>> hash(dt.toZone('UTC')) + 3618678 + +A DateTime can be compared with another DateTime or float via +``cmp()``. NOTE: __cmp__ support is provided for backward +compatibility only, and mixing DateTimes with ExtensionClasses could +cause __cmp__ to break. You should use the methods lessThan, +greaterThan, lessThanEqualTo, greaterThanEqualTo, equalTo and +notEqualTo to avoid potential problems later! + + >>> cmp(dt, dt) + 0 + >>> cmp(dt, dt.toZone('UTC')) + 0 + >>> cmp(dt, dt.timeTime()) + 0 + + >>> cmp(dt, DateTime('2000/01/01')) + -1 + >>> cmp(dt, DateTime('1900/01/01')) + 1 + +DateTime objects can be compared to other DateTime objects OR floating +point numbers such as the ones which are returned by the python time +module. On comparison for equality, True is returned if the object +represents a date/time equal to the specified DateTime or time module +style time: + + >>> dt == dt + True + >>> dt == dt.toZone('UTC') + True + >>> dt == dt.timeTime() + True + >>> dt == DateTime() + False + + >>> dt.equalTo(dt) + True + >>> dt.equalTo(dt.toZone('UTC')) + True + >>> dt.equalTo(dt.timeTime()) + True + >>> dt.equalTo(DateTime()) + False + +Same goes for inequalities: + + >>> dt != dt + False + >>> dt != dt.toZone('UTC') + False + >>> dt != dt.timeTime() + False + >>> dt != DateTime() + True + + >>> dt.notEqualTo(dt) + False + >>> dt.notEqualTo(dt.toZone('UTC')) + False + >>> dt.notEqualTo(dt.timeTime()) + False + >>> dt.notEqualTo(DateTime()) + True + + >>> dt > dt + False + >>> DateTime() > dt + True + >>> dt > DateTime().timeTime() + False + >>> DateTime().timeTime() > dt + True + + >>> dt.greaterThan(dt) + False + >>> DateTime().greaterThan(dt) + True + >>> dt.greaterThan(DateTime().timeTime()) + False + + >>> dt >= dt + True + >>> DateTime() >= dt + True + >>> dt >= DateTime().timeTime() + False + >>> DateTime().timeTime() >= dt + True + + >>> dt.greaterThanEqualTo(dt) + True + >>> DateTime().greaterThanEqualTo(dt) + True + >>> dt.greaterThanEqualTo(DateTime().timeTime()) + False + + >>> dt < dt + False + >>> DateTime() < dt + False + >>> dt < DateTime().timeTime() + True + >>> DateTime().timeTime() < dt + False + + >>> dt.lessThan(dt) + False + >>> DateTime().lessThan(dt) + False + >>> dt.lessThan(DateTime().timeTime()) + True + + >>> dt <= dt + True + >>> DateTime() <= dt + False + >>> dt <= DateTime().timeTime() + True + >>> DateTime().timeTime() <= dt + False + + >>> dt.lessThanEqualTo(dt) + True + >>> DateTime().lessThanEqualTo(dt) + False + >>> dt.lessThanEqualTo(DateTime().timeTime()) + True + Numeric Services Provided by DateTime - - aDateTime + other - - A DateTime may be added to a number and a number may be added to a - DateTime; two DateTimes cannot be added. - - aDateTime - other - - Either a DateTime or a number may be subtracted from a DateTime, - however, a DateTime may not be subtracted from a number. - - other + aDateTimeAdd aDateTime to other. - - A DateTime may be added to a number and a number may be added to a - DateTime; two DateTimes cannot be added. - - int(aDateTime) - - Convert to an integer number of days since Jan. 1, 1901 (gmt) - - long(aDateTime) - - Convert to a long-int number of days since Jan. 1, 1901 (gmt) - - float(aDateTime) - - Convert to floating-point number of days since Jan. 1, 1901 (gmt) - -------------------------------------------------------------------------------- -Last Modified: 14 March 1997 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A DateTime may be added to a number and a number may be added to a +DateTime: + + >>> dt + 5 + DateTime('1997/03/14 13:45:00 US/Eastern') + >>> 5 + dt + DateTime('1997/03/14 13:45:00 US/Eastern') + +Two DateTimes cannot be added: + + >>> dt + dt + Traceback (most recent call last): + ... + DateTimeError: Cannot add two DateTimes + +Either a DateTime or a number may be subtracted from a DateTime, +however, a DateTime may not be subtracted from a number: + + >>> DateTime('1997/03/10 13:45 US/Eastern') - dt + 1.0 + >>> dt - 1 + DateTime('1997/03/08 13:45:00 US/Eastern') + >>> 1 - dt + Traceback (most recent call last): + ... + TypeError: unsupported operand type(s) for -: 'int' and 'instance' + +DateTimes can also be converted to integers (number of seconds since +the epoch), longs (not too long ;)) and floats: + + >>> int(dt) + 857933100 + >>> long(dt) + 857933100L + >>> float(dt) + 857933100.0 Modified: Zope/trunk/lib/python/DateTime/tests/testDateTime.py =================================================================== --- Zope/trunk/lib/python/DateTime/tests/testDateTime.py 2005-11-29 07:45:24 UTC (rev 40401) +++ Zope/trunk/lib/python/DateTime/tests/testDateTime.py 2005-11-29 14:30:14 UTC (rev 40402) @@ -379,7 +379,11 @@ self.assertEqual(dt.strftime(u'Le %d/%m/%Y \xe0 %Hh%M'), ok) def test_suite(): - return unittest.makeSuite(DateTimeTests) + from zope.testing import doctest + return unittest.TestSuite([ + unittest.makeSuite(DateTimeTests), + doctest.DocFileSuite('DateTime.txt', package='DateTime') + ]) if __name__=="__main__": unittest.main(defaultTest='test_suite') _______________________________________________ Zope-Checkins maillist - Zope-Checkins@zope.org http://mail.zope.org/mailman/listinfo/zope-checkins