Table of Contents

Class: DateTime Zope-2.2.1-src/lib/python/Products/OFSP/help/DateTime.py

The DateTime object provides an interface for working with dates and times in various formats. DateTime also provides methods for calendar operations, date and time arithmetic and formatting.

DateTime objects represent instants in time and provide interfaces for 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 ability 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.

A DateTime object should be considered immutable; all conversion and numeric operations return a new DateTime object rather than modify the current object.

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.

  • 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 unambiguous 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 omitted, 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 abbreviation, where a period may optionally follow the abbreviation. 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, slashes, 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 omitted. 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 a floating point value such as that returned by time.time().

    A DateTime object is returned that represents the gmt value of the time.time() float represented in the local machine's timezone.

  • 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()
    
              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
    
    
  • 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 specify a time in hours, minutes, and seconds; hours and minutes should be positive integers and seconds is a positive floating point value, all of these 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.

Methods   
AMPM
AMPMMinutes
Date
Day
DayOfWeek
Day_
HTML4
ISO
Mon
Mon_
Month
PreciseAMPM
PreciseTime
Time
TimeMinutes
aCommon
aCommonZ
aDay
aMonth
ampm
day
dayOfYear
dd
dow
dow_1
earliestTime
equalTo
fCommon
fCommonZ
greaterThan
greaterThanEqualTo
h_12
h_24
hour
isCurrentDay
isCurrentHour
isCurrentMinute
isCurrentMonth
isCurrentYear
isFuture
isLeapYear
isPast
latestTime
lessThan
lessThanEqualTo
millis
minute
mm
month
notEqualTo
pCommon
pCommonZ
pDay
pMonth
parts
rfc822
second
strftime
timeTime
timezone
toZone
year
yy
  AMPM 
AMPM ( self )

Return the time string for an object to the nearest second.

  AMPMMinutes 
AMPMMinutes ( self )

Return the time string for an object not showing seconds.

  Date 
Date ( self )

Return the date string for the object.

General formats from previous DateTime

  Day 
Day ( self )

Return the full name of the day of the week

  DayOfWeek 
DayOfWeek ( self )

Compatibility: see Day

  Day_ 
Day_ ( self )

Compatibility: see pDay

  HTML4 
HTML4 ( self )

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

  ISO 
ISO ( self )

Return the object in ISO standard format

Dates are output as: YYYY-MM-DD HH:MM:SS

  Mon 
Mon ( self )

Compatibility: see aMonth

  Mon_ 
Mon_ ( self )

Compatibility: see pMonth

  Month 
Month ( self )

Return the full month name

  PreciseAMPM 
PreciseAMPM ( self )

Return the time string for the object.

  PreciseTime 
PreciseTime ( self )

Return the time string for the object.

  Time 
Time ( self )

Return the time string for an object to the nearest second.

  TimeMinutes 
TimeMinutes ( self )

Return the time string for an object not showing seconds.

  aCommon 
aCommon ( self )

Return a string representing the object's value in the format: Mar 1, 1997 1:45 pm

  aCommonZ 
aCommonZ ( self )

Return a string representing the object's value in the format: Mar 1, 1997 1:45 pm US/Eastern

  aDay 
aDay ( self )

Return the abbreviated name of the day of the week

  aMonth 
aMonth ( self )

Return the abbreviated month name.

  ampm 
ampm ( self )

Return the appropriate time modifier (am or pm)

  day 
day ( self )

Return the integer day

  dayOfYear 
dayOfYear ( self )

Return the day of the year, in context of the timezone representation of the object

  dd 
dd ( self )

Return day as a 2 digit string

  dow 
dow ( self )

Return the integer day of the week, where Sunday is 0

  dow_1 
dow_1 ( self )

Return the integer day of the week, where Sunday is 1

  earliestTime 
earliestTime ( self )

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

  equalTo 
equalTo ( self,  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. Revised to give more correct results through comparison of long integer milliseconds.

  fCommon 
fCommon ( self )

Return a string representing the object's value in the format: March 1, 1997 1:45 pm

New formats

  fCommonZ 
fCommonZ ( self )

Return a string representing the object's value in the format: March 1, 1997 1:45 pm US/Eastern

  greaterThan 
greaterThan ( self,  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. Revised to give more correct results through comparison of long integer milliseconds.

  greaterThanEqualTo 
greaterThanEqualTo ( self,  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. Revised to give more correct results through comparison of long integer milliseconds.

  h_12 
h_12 ( self )

Return the 12-hour clock representation of the hour

  h_24 
h_24 ( self )

Return the 24-hour clock representation of the hour

  hour 
hour ( self )

Return the 24-hour clock representation of the hour

  isCurrentDay 
isCurrentDay ( self )

Return true if this object represents a date/time that falls within the current day, in the context of this object's timezone representation

  isCurrentHour 
isCurrentHour ( self )

Return true if this object represents a date/time that falls within the current hour, in the context of this object's timezone representation

  isCurrentMinute 
isCurrentMinute ( self )

Return true if this object represents a date/time that falls within the current minute, in the context of this object's timezone representation

  isCurrentMonth 
isCurrentMonth ( self )

Return true if this object represents a date/time that falls within the current month, in the context of this object's timezone representation

  isCurrentYear 
isCurrentYear ( self )

Return true if this object represents a date/time that falls within the current year, in the context of this object's timezone representation

  isFuture 
isFuture ( self )

Return true if this object represents a date/time later than the time of the call

  isLeapYear 
isLeapYear ( self )

Return true if the current year (in the context of the object's timezone) is a leap year

  isPast 
isPast ( self )

Return true if this object represents a date/time earlier than the time of the call

  latestTime 
latestTime ( self )

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

  lessThan 
lessThan ( self,  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. Revised to give more correct results through comparison of long integer milliseconds.

  lessThanEqualTo 
lessThanEqualTo ( self,  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. Revised to give more correct results through comparison of long integer milliseconds.

  millis 
millis ( self )

Return the millisecond since the epoch in GMT.

  minute 
minute ( self )

Return the minute

  mm 
mm ( self )

Return month as a 2 digit string

  month 
month ( self )

Return the month of the object as an integer

  notEqualTo 
notEqualTo ( self,  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. Revised to give more correct results through comparison of long integer milliseconds.

  pCommon 
pCommon ( self )

Return a string representing the object's value in the format: Mar. 1, 1997 1:45 pm

  pCommonZ 
pCommonZ ( self )

Return a string representing the object's value in the format: Mar. 1, 1997 1:45 pm US/Eastern

  pDay 
pDay ( self )

Return the abbreviated (with period) name of the day of the week

  pMonth 
pMonth ( self )

Return the abbreviated (with period) month name.

  parts 
parts ( self )

Return a tuple containing the calendar year, month, day, hour, minute second and timezone of the object

Component access

  rfc822 
rfc822 ( self )

Return the date in RFC 822 format

  second 
second ( self )

Return the second

  strftime 
strftime ( self,  format )

Return date time string formatted according to format

  timeTime 
timeTime ( self )

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.

  timezone 
timezone ( self )

Return the timezone in which the object is represented.

  toZone 
toZone ( self,  z )

Return a DateTime with the value as the current object, represented in the indicated timezone.

  year 
year ( self )

Return the calendar year of the object

  yy 
yy ( self )

Return calendar year as a 2 digit string


Table of Contents

This document was automatically generated on Mon Sep 4 07:33:06 2000 by HappyDoc version r0_6