jpayne@68: ############################################################################## jpayne@68: # jpayne@68: # Copyright (c) 2005 Zope Foundation and Contributors. jpayne@68: # jpayne@68: # This software is subject to the provisions of the Zope Public License, jpayne@68: # Version 2.1 (ZPL). A copy of the ZPL should accompany this distribution. jpayne@68: # THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED jpayne@68: # WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED jpayne@68: # WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS jpayne@68: # FOR A PARTICULAR PURPOSE jpayne@68: # jpayne@68: ############################################################################## jpayne@68: from zope.interface import Interface jpayne@68: jpayne@68: jpayne@68: class DateTimeError(Exception): jpayne@68: pass jpayne@68: jpayne@68: jpayne@68: class SyntaxError(DateTimeError): jpayne@68: pass jpayne@68: jpayne@68: jpayne@68: class DateError(DateTimeError): jpayne@68: pass jpayne@68: jpayne@68: jpayne@68: class TimeError(DateTimeError): jpayne@68: pass jpayne@68: jpayne@68: jpayne@68: class IDateTime(Interface): jpayne@68: # Conversion and comparison methods jpayne@68: jpayne@68: def localZone(ltm=None): jpayne@68: """Returns the time zone on the given date. The time zone jpayne@68: can change according to daylight savings.""" jpayne@68: jpayne@68: def timeTime(): jpayne@68: """Return the date/time as a floating-point number in UTC, in jpayne@68: the format used by the Python time module. Note that it is jpayne@68: possible to create date/time values with DateTime that have no jpayne@68: meaningful value to the time module.""" jpayne@68: jpayne@68: def toZone(z): jpayne@68: """Return a DateTime with the value as the current object, jpayne@68: represented in the indicated timezone.""" jpayne@68: jpayne@68: def isFuture(): jpayne@68: """Return true if this object represents a date/time later jpayne@68: than the time of the call""" jpayne@68: jpayne@68: def isPast(): jpayne@68: """Return true if this object represents a date/time earlier jpayne@68: than the time of the call""" jpayne@68: jpayne@68: def isCurrentYear(): jpayne@68: """Return true if this object represents a date/time that jpayne@68: falls within the current year, in the context of this jpayne@68: object's timezone representation""" jpayne@68: jpayne@68: def isCurrentMonth(): jpayne@68: """Return true if this object represents a date/time that jpayne@68: falls within the current month, in the context of this jpayne@68: object's timezone representation""" jpayne@68: jpayne@68: def isCurrentDay(): jpayne@68: """Return true if this object represents a date/time that jpayne@68: falls within the current day, in the context of this object's jpayne@68: timezone representation""" jpayne@68: jpayne@68: def isCurrentHour(): jpayne@68: """Return true if this object represents a date/time that jpayne@68: falls within the current hour, in the context of this object's jpayne@68: timezone representation""" jpayne@68: jpayne@68: def isCurrentMinute(): jpayne@68: """Return true if this object represents a date/time that jpayne@68: falls within the current minute, in the context of this jpayne@68: object's timezone representation""" jpayne@68: jpayne@68: def isLeapYear(): jpayne@68: """Return true if the current year (in the context of the jpayne@68: object's timezone) is a leap year""" jpayne@68: jpayne@68: def earliestTime(): jpayne@68: """Return a new DateTime object that represents the earliest jpayne@68: possible time (in whole seconds) that still falls within the jpayne@68: current object's day, in the object's timezone context""" jpayne@68: jpayne@68: def latestTime(): jpayne@68: """Return a new DateTime object that represents the latest jpayne@68: possible time (in whole seconds) that still falls within the jpayne@68: current object's day, in the object's timezone context""" jpayne@68: jpayne@68: def greaterThan(t): jpayne@68: """Compare this DateTime object to another DateTime object OR jpayne@68: a floating point number such as that which is returned by the jpayne@68: Python time module. Returns true if the object represents a jpayne@68: date/time greater than the specified DateTime or time module jpayne@68: style time. Revised to give more correct results through jpayne@68: comparison of long integer milliseconds.""" jpayne@68: jpayne@68: __gt__ = greaterThan jpayne@68: jpayne@68: def greaterThanEqualTo(t): jpayne@68: """Compare this DateTime object to another DateTime object OR jpayne@68: a floating point number such as that which is returned by the jpayne@68: Python time module. Returns true if the object represents a jpayne@68: date/time greater than or equal to the specified DateTime or jpayne@68: time module style time. Revised to give more correct results jpayne@68: through comparison of long integer milliseconds.""" jpayne@68: jpayne@68: __ge__ = greaterThanEqualTo jpayne@68: jpayne@68: def equalTo(t): jpayne@68: """Compare this DateTime object to another DateTime object OR jpayne@68: a floating point number such as that which is returned by the jpayne@68: Python time module. Returns true if the object represents a jpayne@68: date/time equal to the specified DateTime or time module style jpayne@68: time. Revised to give more correct results through comparison jpayne@68: of long integer milliseconds.""" jpayne@68: jpayne@68: __eq__ = equalTo jpayne@68: jpayne@68: def notEqualTo(t): jpayne@68: """Compare this DateTime object to another DateTime object OR jpayne@68: a floating point number such as that which is returned by the jpayne@68: Python time module. Returns true if the object represents a jpayne@68: date/time not equal to the specified DateTime or time module jpayne@68: style time. Revised to give more correct results through jpayne@68: comparison of long integer milliseconds.""" jpayne@68: jpayne@68: __ne__ = notEqualTo jpayne@68: jpayne@68: def lessThan(t): jpayne@68: """Compare this DateTime object to another DateTime object OR jpayne@68: a floating point number such as that which is returned by the jpayne@68: Python time module. Returns true if the object represents a jpayne@68: date/time less than the specified DateTime or time module jpayne@68: style time. Revised to give more correct results through jpayne@68: comparison of long integer milliseconds.""" jpayne@68: jpayne@68: __lt__ = lessThan jpayne@68: jpayne@68: def lessThanEqualTo(t): jpayne@68: """Compare this DateTime object to another DateTime object OR jpayne@68: a floating point number such as that which is returned by the jpayne@68: Python time module. Returns true if the object represents a jpayne@68: date/time less than or equal to the specified DateTime or time jpayne@68: module style time. Revised to give more correct results jpayne@68: through comparison of long integer milliseconds.""" jpayne@68: jpayne@68: __le__ = lessThanEqualTo jpayne@68: jpayne@68: # Component access jpayne@68: jpayne@68: def parts(): jpayne@68: """Return a tuple containing the calendar year, month, day, jpayne@68: hour, minute second and timezone of the object""" jpayne@68: jpayne@68: def timezone(): jpayne@68: """Return the timezone in which the object is represented.""" jpayne@68: jpayne@68: def tzoffset(): jpayne@68: """Return the timezone offset for the objects timezone.""" jpayne@68: jpayne@68: def year(): jpayne@68: """Return the calendar year of the object""" jpayne@68: jpayne@68: def month(): jpayne@68: """Return the month of the object as an integer""" jpayne@68: jpayne@68: def Month(): jpayne@68: """Return the full month name""" jpayne@68: jpayne@68: def aMonth(): jpayne@68: """Return the abbreviated month name.""" jpayne@68: jpayne@68: def Mon(): jpayne@68: """Compatibility: see aMonth""" jpayne@68: jpayne@68: def pMonth(): jpayne@68: """Return the abbreviated (with period) month name.""" jpayne@68: jpayne@68: def Mon_(): jpayne@68: """Compatibility: see pMonth""" jpayne@68: jpayne@68: def day(): jpayne@68: """Return the integer day""" jpayne@68: jpayne@68: def Day(): jpayne@68: """Return the full name of the day of the week""" jpayne@68: jpayne@68: def DayOfWeek(): jpayne@68: """Compatibility: see Day""" jpayne@68: jpayne@68: def dayOfYear(): jpayne@68: """Return the day of the year, in context of the timezone jpayne@68: representation of the object""" jpayne@68: jpayne@68: def aDay(): jpayne@68: """Return the abbreviated name of the day of the week""" jpayne@68: jpayne@68: def pDay(): jpayne@68: """Return the abbreviated (with period) name of the day of the jpayne@68: week""" jpayne@68: jpayne@68: def Day_(): jpayne@68: """Compatibility: see pDay""" jpayne@68: jpayne@68: def dow(): jpayne@68: """Return the integer day of the week, where sunday is 0""" jpayne@68: jpayne@68: def dow_1(): jpayne@68: """Return the integer day of the week, where sunday is 1""" jpayne@68: jpayne@68: def h_12(): jpayne@68: """Return the 12-hour clock representation of the hour""" jpayne@68: jpayne@68: def h_24(): jpayne@68: """Return the 24-hour clock representation of the hour""" jpayne@68: jpayne@68: def ampm(): jpayne@68: """Return the appropriate time modifier (am or pm)""" jpayne@68: jpayne@68: def hour(): jpayne@68: """Return the 24-hour clock representation of the hour""" jpayne@68: jpayne@68: def minute(): jpayne@68: """Return the minute""" jpayne@68: jpayne@68: def second(): jpayne@68: """Return the second""" jpayne@68: jpayne@68: def millis(): jpayne@68: """Return the millisecond since the epoch in GMT.""" jpayne@68: jpayne@68: def strftime(format): jpayne@68: """Format the date/time using the *current timezone representation*.""" jpayne@68: jpayne@68: # General formats from previous DateTime jpayne@68: jpayne@68: def Date(): jpayne@68: """Return the date string for the object.""" jpayne@68: jpayne@68: def Time(): jpayne@68: """Return the time string for an object to the nearest second.""" jpayne@68: jpayne@68: def TimeMinutes(): jpayne@68: """Return the time string for an object not showing seconds.""" jpayne@68: jpayne@68: def AMPM(): jpayne@68: """Return the time string for an object to the nearest second.""" jpayne@68: jpayne@68: def AMPMMinutes(): jpayne@68: """Return the time string for an object not showing seconds.""" jpayne@68: jpayne@68: def PreciseTime(): jpayne@68: """Return the time string for the object.""" jpayne@68: jpayne@68: def PreciseAMPM(): jpayne@68: """Return the time string for the object.""" jpayne@68: jpayne@68: def yy(): jpayne@68: """Return calendar year as a 2 digit string""" jpayne@68: jpayne@68: def mm(): jpayne@68: """Return month as a 2 digit string""" jpayne@68: jpayne@68: def dd(): jpayne@68: """Return day as a 2 digit string""" jpayne@68: jpayne@68: def rfc822(): jpayne@68: """Return the date in RFC 822 format""" jpayne@68: jpayne@68: # New formats jpayne@68: jpayne@68: def fCommon(): jpayne@68: """Return a string representing the object's value in the jpayne@68: format: March 1, 1997 1:45 pm""" jpayne@68: jpayne@68: def fCommonZ(): jpayne@68: """Return a string representing the object's value in the jpayne@68: format: March 1, 1997 1:45 pm US/Eastern""" jpayne@68: jpayne@68: def aCommon(): jpayne@68: """Return a string representing the object's value in the jpayne@68: format: Mar 1, 1997 1:45 pm""" jpayne@68: jpayne@68: def aCommonZ(): jpayne@68: """Return a string representing the object's value in the jpayne@68: format: Mar 1, 1997 1:45 pm US/Eastern""" jpayne@68: jpayne@68: def pCommon(): jpayne@68: """Return a string representing the object's value in the jpayne@68: format: Mar. 1, 1997 1:45 pm""" jpayne@68: jpayne@68: def pCommonZ(): jpayne@68: """Return a string representing the object's value jpayne@68: in the format: Mar. 1, 1997 1:45 pm US/Eastern""" jpayne@68: jpayne@68: def ISO(): jpayne@68: """Return the object in ISO standard format. Note: this is jpayne@68: *not* ISO 8601-format! See the ISO8601 and HTML4 methods below jpayne@68: for ISO 8601-compliant output jpayne@68: jpayne@68: Dates are output as: YYYY-MM-DD HH:MM:SS jpayne@68: """ jpayne@68: jpayne@68: def ISO8601(): jpayne@68: """Return the object in ISO 8601-compatible format containing jpayne@68: the date, time with seconds-precision and the time zone jpayne@68: identifier - see http://www.w3.org/TR/NOTE-datetime jpayne@68: jpayne@68: Dates are output as: YYYY-MM-DDTHH:MM:SSTZD jpayne@68: T is a literal character. jpayne@68: TZD is Time Zone Designator, format +HH:MM or -HH:MM jpayne@68: jpayne@68: The HTML4 method below offers the same formatting, but jpayne@68: converts to UTC before returning the value and sets the TZD"Z" jpayne@68: """ jpayne@68: jpayne@68: def HTML4(): jpayne@68: """Return the object in the format used in the HTML4.0 jpayne@68: specification, one of the standard forms in ISO8601. See jpayne@68: http://www.w3.org/TR/NOTE-datetime jpayne@68: jpayne@68: Dates are output as: YYYY-MM-DDTHH:MM:SSZ jpayne@68: T, Z are literal characters. jpayne@68: The time is in UTC. jpayne@68: """ jpayne@68: jpayne@68: def JulianDay(): jpayne@68: """Return the Julian day according to jpayne@68: https://www.tondering.dk/claus/cal/julperiod.php#formula jpayne@68: """ jpayne@68: jpayne@68: def week(): jpayne@68: """Return the week number according to ISO. jpayne@68: jpayne@68: See https://www.tondering.dk/claus/cal/week.php#weekno jpayne@68: """ jpayne@68: jpayne@68: # Python operator and conversion API jpayne@68: jpayne@68: def __add__(other): jpayne@68: """A DateTime may be added to a number and a number may be jpayne@68: added to a DateTime; two DateTimes cannot be added.""" jpayne@68: jpayne@68: __radd__ = __add__ jpayne@68: jpayne@68: def __sub__(other): jpayne@68: """Either a DateTime or a number may be subtracted from a jpayne@68: DateTime, however, a DateTime may not be subtracted from a jpayne@68: number.""" jpayne@68: jpayne@68: def __repr__(): jpayne@68: """Convert a DateTime to a string that looks like a Python jpayne@68: expression.""" jpayne@68: jpayne@68: def __str__(): jpayne@68: """Convert a DateTime to a string.""" jpayne@68: jpayne@68: def __hash__(): jpayne@68: """Compute a hash value for a DateTime""" jpayne@68: jpayne@68: def __int__(): jpayne@68: """Convert to an integer number of seconds since the epoch (gmt)""" jpayne@68: jpayne@68: def __long__(): jpayne@68: """Convert to a long-int number of seconds since the epoch (gmt)""" jpayne@68: jpayne@68: def __float__(): jpayne@68: """Convert to floating-point number of seconds since the epoch (gmt)"""