[Zope-Checkins] SVN: Zope/trunk/lib/python/DateTime/ Convert DateTime.txt to reST and a (pretty extensive) doctest.

Philipp von Weitershausen philikon at philikon.de
Tue Nov 29 09:30:14 EST 2005


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



More information about the Zope-Checkins mailing list