--- /dev/null
+
+\section{\module{datetime} --
+ Basic date and time types}
+
+\declaremodule{builtin}{datetime}
+\modulesynopsis{Basic date and time types.}
+\moduleauthor{Tim Peters}{tim@zope.com} % XXX check address
+\sectionauthor{A.M. Kuchling}{amk@amk.ca}
+
+\newcommand{\naive}{na\"ive}
+
+The \module{datetime} module supplies classes for manipulating dates
+and times in both simple and complex ways. While date and time
+arithmetic is supported, the focus of the implementation is on
+efficient field extraction, for output formatting and manipulation.
+
+There are two kinds of date and time objects: ``\naive'' and ``aware''.
+This distinction refers to whether the object has any notion of time
+zone, daylight savings time, or other kind of algorithmic or political
+time adjustment. Whether a \naive\ \class{datetime} object represents
+Coordinated Universal Time (UTC), local time, or time in some other
+timezone is purely up to the program, just like it's up to the program
+whether a particular number represents meters, miles, or mass. \Naive\
+\class{datetime} objects are easy to understand and to work with, at
+the cost of ignoring some aspects of reality.
+
+For applications requiring more, ``aware'' \class{datetime} subclasses add an
+optional time zone information object to the basic \naive\ classes.
+These \class{tzinfo} objects capture information about the offset from
+UTC time, the time zone name, and whether Daylight Savings Time is in
+effect. Note that no concrete \class{tzinfo} classes are supplied by
+the \module{datetime} module. Instead, they provide a framework for
+incorporating the level of detail an app may require. The rules for
+time adjustment across the world are more political than rational, and
+there is no standard suitable for every app.
+
+The \module{datetime} module exports the following constants:
+
+\begin{datadesc}{MINYEAR}
+ The smallest year number allowed in a \class{date},
+ \class{datetime}, or \class{datetimetz}
+ object. \constant{MINYEAR} is 1.
+\end{datadesc}
+
+\begin{datadesc}{MAXYEAR}
+ The largest year number allowed in a \class{date},
+ \class{datetime}, or \class{datetimetz}
+ object. \constant{MAXYEAR} is 9999.
+\end{datadesc}
+
+
+\subsection{Available Types}
+
+\begin{classdesc}{date}{}
+ An idealized \naive\ date, assuming the current Gregorian calendar
+ always was, and always will be, in effect.
+ Attributes: \member{year}, \member{month}, and \member{day}.
+\end{classdesc}
+
+\begin{classdesc}{time}{}
+ An idealized \naive\ time, independent of any particular day, assuming
+ that every day has exactly 24*60*60 seconds (there is no notion
+ of "leap seconds" here).
+ Attributes: \member{hour}, \member{minute}, \member{second}, and
+ \member{microsecond}
+\end{classdesc}
+
+\begin{classdesc}{datetime}{}
+ A combination of a \naive\ date and a \naive\ time.
+ Attributes: \member{year}, \member{month}, \member{day},
+ \member{hour}, \member{minute}, \member{second},
+ and \member{microsecond}.
+\end{classdesc}
+
+\begin{classdesc}{timedelta}{}
+ A duration, expressing the difference between two \class{date},
+ \class{time}, or \class{datetime} instances, to microsecond
+ resolution.
+\end{classdesc}
+
+\begin{classdesc}{tzinfo}{}
+ An abstract base class for time zone information objects. These
+ are used by the \class{datetimetz} and \class{timetz} classes to
+ provided a customizable notion of time adjustment (for example, to
+ account for time zone and/or daylight savings time).
+\end{classdesc}
+
+\begin{classdesc}{timetz}{}
+ An aware subclass of \class{time}, supporting a customizable notion of
+ time adjustment.
+\end{classdesc}
+
+\begin{classdesc}{datetimetz}{}
+ An aware subclass of \class{datetime}, supporting a customizable notion of
+ time adjustment.
+\end{classdesc}
+
+Objects of these types are immutable.
+
+Objects of the \class{date}, \class{datetime}, and
+\class{time} types are always \naive.
+
+An object \code{D} of type \class{timetz} or \class{datetimetz} may be
+\naive\ or aware. \code{D} is aware if \code{D.tzinfo} is not \code{None},
+and \code{D.tzinfo.utcoffset(D)} does not return \code{None}. If
+\code{D.tzinfo} is \code{None}, or if \code{D.tzinfo} is not
+\code{None} but \code{D.tzinfo.utcoffset(D)} returns \code{None}, \code{D} is
+\naive.
+
+The distinction between \naive\ and aware doesn't apply to \code{timedelta}
+objects.
+
+Subclass relationships
+======================
+% XXX latex
+ object
+ timedelta
+ tzinfo
+ time
+ timetz
+ date
+ datetime
+ datetimetz
+
+
+
+\subsection{\method{strftime()} Behavior}
+
+\class{date}, \class{datetime}, \class{datetimetz} , \class{time}, and
+\class{timetz} objects all support
+a strftime(format) method, to create a string representing the time
+under the control of an explicit format string. Broadly speaking,
+ d.strftime(fmt)
+acts like the time module's
+ time.strftime(fmt, d.timetuple())
+although not all objects support a timetuple() method.
+
+For time and \class{timetz} objects, format codes for year, month, and day
+should not be used, as time objects have no such values. 0 is used
+instead.
+
+For date objects, format codes for hours, minutes, and seconds should
+not be used, as date objects have no such values. 0 is used insted.
+
+For a \naive\ object, the %z and %Z format codes are replaced by
+empty strings.
+
+For an aware object:
+
+- %z: self.utcoffset() is transformed into a 5-character
+ string of the form +HHMM or -HHMM, where HH is a 2-digit string
+ giving the number of UTC offset hours, and MM is a 2-digit string
+ giving the number of UTC offset minutes. For example, if
+ utcoffset() returns -180, %z is replaced with string "-0300".
+
+- %Z: If self.tzname() returns None, %Z is replaced by an empty string.
+ Else %Z is replaced by the returned value, which must be a string.
+
+
+\subsection{\class{timedelta} \label{datetime-timedelta}
+
+A timedelta object represents a duration, the difference between two
+dates or times.
+
+Constructor:
+
+ timedelta(days=0, seconds=0, microseconds=0,
+ # The following should only be used as keyword args:
+ milliseconds=0, minutes=0, hours=0, weeks=0)
+
+ All arguments are optional. Arguments may be ints, longs, or floats,
+ and may be positive or negative.
+
+ Only days, seconds and microseconds are stored internally. Arguments
+ are converted to those units:
+
+ A millisecond is converted 1000 microseconds.
+ A minute is converted to 60 seconds.
+ An hour is converted to 3600 seconds.
+ A week is converted to 7 days.
+
+ and days, seconds and microseconds are then normalized so that the
+ representation is unique, with
+
+ 0 <= microseconds < 1000000
+ 0 <= seconds < 3600*24 (the number of seconds in one day)
+ -999999999 <= days <= 999999999
+
+ If any argument is a float, and there are fractional microseconds,
+ the fractional microseconds left over from all arguments are combined
+ and their sum is rounded to the nearest microsecond. If no
+ argument is a flost, the conversion and normalization processes
+ are exact (no information is lost).
+
+ If the normalized value of days lies outside the indicated range,
+ OverflowError is raised.
+
+ Note that normalization of negative values may be surprising at first.
+ For example,
+
+ >>> d = timedelta(microseconds=-1)
+ >>> (d.days, d.seconds, d.microseconds)
+ (-1, 86399, 999999)
+ >>>
+
+
+Class attributes:
+
+ .min
+ The most negative timedelta object, timedelta(-999999999).
+
+ .max
+ The most positive timedelta object,
+ timedelta(days=999999999, hours=23, minutes=59, seconds=59,
+ microseconds=999999)
+
+ .resolution
+ The smallest possible difference between non-equal timedelta
+ objects, timedelta(microseconds=1).
+
+ Note that, because of normalization, timedelta.max > -timedelta.min.
+ -timedelta.max is not representable as a timedelta object.
+
+Instance attributes (read-only):
+
+ .days between -999999999 and 999999999 inclusive
+ .seconds between 0 and 86399 inclusive
+ .microseconds between 0 and 999999 inclusive
+
+Supported operations:
+
+ - timedelta + timedelta -> timedelta
+ This is exact, but may overflow. After
+ t1 = t2 + t3
+ t1-t2 == t3 and t1-t3 == t2 are true.
+
+ - timedelta - timedelta -> timedelta
+ This is exact, but may overflow. After
+ t1 = t2 - t3
+ t2 == t1 + t3 is true.
+
+ - timedelta * (int or long) -> timedelta
+ (int or long) * timedelta -> timedelta
+ This is exact, but may overflow. After
+ t1 = t2 * i
+ t1 // i == t2 is true, provided i != 0. In general,
+ t * i == t * (i-1) + t
+ is true.
+
+ - timedelta // (int or long) -> timedelta
+ The floor is computed and the remainder (if any) is thrown away.
+ Division by 0 raises ZeroDivisionError.
+
+ - certain additions and subtractions with date, datetime, and datimetz
+ objects (see below)
+
+ - +timedelta -> timedelta
+ Returns a timedelta object with the same value.
+
+ - -timedelta -> timedelta
+ -t is equivalent to timedelta(-t.days, -t.seconds, -t.microseconds),
+ and to t*-1. This is exact, but may overflow (for example,
+ -timedelta.max is not representable as a timedelta object).
+
+ - abs(timedelta) -> timedelta
+ abs(t) is equivalent to +t when t.days >= 0, and to -t when
+ t.days < 0. This is exact, and cannot overflow.
+
+ - comparison of timedelta to timedelta; the timedelta representing
+ the smaller duration is considered to be the smaller timedelta
+
+ - hash, use as dict key
+
+ - efficient pickling
+
+ - in Boolean contexts, a timedelta object is considred to be true
+ if and only if it isn't equal to timedelta(0)
+
+
+\subsection{\class{date} \label{datetime-date}}
+
+A date object represents a date (year, month and day) in an idealized
+calendar, the current Gregorian calendar indefinitely extended in both
+directions. January 1 of year 1 is called day number 1, January 2 of year
+1 is called day number 2, and so on. This matches the definition of the
+"proleptic Gregorian" calendar in Dershowitz and Reingold's book
+"Calendrical Calculations", where it's the base calendar for all
+computations. See the book for algorithms for converting between
+proleptic Gregorian ordinals and many other calendar systems.
+
+Constructor:
+
+ date(year, month, day)
+
+ All arguments are required. Arguments may be ints or longs, in the
+ following ranges:
+
+ MINYEAR <= year <= MAXYEAR
+ 1 <= month <= 12
+ 1 <= day <= number of days in the given month and year
+
+ If an argument outside those ranges is given, ValueError is raised.
+
+Other constructors (class methods):
+
+ - today()
+ Return the current local date. This is equivalent to
+ date.fromtimestamp(time.time()).
+
+ - fromtimestamp(timestamp)
+ Return the local date corresponding to the POSIX timestamp, such as
+ is returned by time.time(). This may raise ValueError, if the
+ timestamp is out of the range of values supported by the platform C
+ localtime() function. It's common for this to be restricted to
+ years in 1970 through 2038.
+
+ - fromordinal(ordinal)
+ Return the date corresponding to the proleptic Gregorian ordinal,
+ where January 1 of year 1 has ordinal 1. ValueError is raised
+ unless 1 <= ordinal <= date.max.toordinal(). For any date d,
+ date.fromordinal(d.toordinal()) == d.
+
+Class attributes:
+
+ .min
+ The earliest representable date, date(MINYEAR, 1, 1).
+
+ .max
+ The latest representable date, date(MAXYEAR, 12, 31).
+
+ .resolution
+ The smallest possible difference between non-equal date
+ objects, timedelta(days=1).
+
+Instance attributes (read-only):
+
+ .year between MINYEAR and MAXYEAR inclusive
+ .month between 1 and 12 inclusive
+ .day between 1 and the number of days in the given month
+ of the given year
+
+Supported operations:
+
+ - date1 + timedelta -> date2
+ timedelta + date1 -> date2
+ date2 is timedelta.days days removed from the date1, moving forward
+ in time if timedelta.days > 0, or backward if timedetla.days < 0.
+ date2 - date1 == timedelta.days after. timedelta.seconds and
+ timedelta.microseconds are ignored. OverflowError is raised if
+ date2.year would be smaller than MINYEAR or larger than MAXYEAR.
+
+ - date1 - timedelta -> date2
+ Computes the date2 such that date2 + timedelta == date1. This
+ isn't quite equivalent to date1 + (-timedelta), because -timedelta
+ in isolation can overflow in cases where date1 - timedelta does
+ not. timedelta.seconds and timedelta.microseconds are ignored.
+
+ - date1 - date2 -> timedelta
+ This is exact, and cannot overflow. timedelta.seconds and
+ timedelta.microseconds are 0, and date2 + timedelta == date1
+ after.
+
+ - comparison of date to date, where date1 is considered less than
+ date2 when date1 precedes date2 in time. In other words,
+ date1 < date2 if and only if date1.toordinal() < date2.toordinal().
+
+ - hash, use as dict key
+
+ - efficient pickling
+
+ - in Boolean contexts, all date objects are considered to be true
+
+Instance methods:
+
+ - timetuple()
+ Return a 9-element tuple of the form returned by time.localtime().
+ The hours, minutes and seconds are 0, and the DST flag is -1.
+ d.timetuple() is equivalent to
+ (d.year, d.month, d.day,
+ 0, 0, 0, # h, m, s
+ d.weekday(), # 0 is Monday
+ d.toordinal() - date(d.year, 1, 1).toordinal() + 1, # day of year
+ -1)
+
+ - toordinal()
+ Return the proleptic Gregorian ordinal of the date, where January 1
+ of year 1 has ordinal 1. For any date object d,
+ date.fromordinal(d.toordinal()) == d.
+
+ - weekday()
+ Return the day of the week as an integer, where Monday is 0 and
+ Sunday is 6. For example, date(2002, 12, 4).weekday() == 2, a
+ Wednesday.
+ See also isoweekday().
+
+ - isoweekday()
+ Return the day of the week as an integer, where Monday is 1 and
+ Sunday is 7. For example, date(2002, 12, 4).isoweekday() == 3, a
+ Wednesday.
+ See also weekday() and isocalendar().
+
+ - isocalendar()
+ Return a 3-tuple, (ISO year, ISO week number, ISO weekday).
+
+ The ISO calendar is a widely used variant of the Gregorian calendar.
+ See <http://www.phys.uu.nl/~vgent/calendar/isocalendar.htm>
+ for a good explanation.
+
+ The ISO year consists of 52 or 53 full weeks, and where a week starts
+ on a Monday and ends on a Sunday. The first week of an ISO year is
+ the first (Gregorian) calendar week of a year containing a Thursday.
+ This is called week number 1, and the ISO year of that Thursday is
+ the same as its Gregorian year.
+
+ For example, 2004 begins on a Thursday, so the first week of ISO
+ year 2004 begins on Monday, 29 Dec 2003 and ends on Sunday, 4 Jan
+ 2004, so that
+
+ date(2003, 12, 29).isocalendar() == (2004, 1, 1)
+ date(2004, 1, 4).isocalendar() == (2004, 1, 7)
+
+ - isoformat()
+ Return a string representing the date in ISO 8601 format,
+ 'YYYY-MM-DD'. For example,
+ date(2002, 12, 4).isoformat() == '2002-12-04'.
+
+ - __str__()
+ For a date d, str(d) is equivalent to d.isoformat().
+
+ - ctime()
+ Return a string representing the date, for example
+ date(2002, 12, 4).ctime() == 'Wed Dec 4 00:00:00 2002'.
+ d.ctime() is equivalent to time.ctime(time.mktime(d.timetuple()))
+ on platforms where the native C ctime() function (which time.ctime()
+ invokes, but which date.ctime() does not invoke) conforms to the
+ C standard.
+
+ - strftime(format)
+ Return a string representing the date, controlled by an explicit
+ format string. Format codes referring to hours, minutes or seconds
+ will see 0 values. See the section on strftime() behavior.
+
+
+\subsection{\class{datetime} \label{datetime-datetime}}
+
+A \class{datetime} object is a single object containing all the information from
+a date object and a time object. Like a date object, \class{datetime} assumes
+the current Gregorian calendar extended in both directions; like a time
+object, \class{datetime} assumes there are exactly 3600*24 seconds in every day.
+
+Constructor:
+
+ datetime(year, month, day,
+ hour=0, minute=0, second=0, microsecond=0)
+
+ The year, month and day arguments are required. Arguments may be ints
+ or longs, in the following ranges:
+
+ MINYEAR <= year <= MAXYEAR
+ 1 <= month <= 12
+ 1 <= day <= number of days in the given month and year
+ 0 <= hour < 24
+ 0 <= minute < 60
+ 0 <= second < 60
+ 0 <= microsecond < 1000000
+
+ If an argument outside those ranges is given, ValueError is raised.
+
+Other constructors (class methods):
+
+ - today()
+ Return the current local datetime. This is equivalent to
+ datetime.fromtimestamp(time.time()).
+ See also now(), fromtimestamp().
+
+ - now()
+ Return the current local datetime. This is like today(), but, if
+ possible, supplies more precision than can be gotten from going
+ through a time.time() timestamp (for example, this may be possible
+ on platforms that supply the C gettimeofday() function).
+ See also today(), utcnow().
+
+ - utcnow()
+ Return the current UTC datetime. This is like now(), but returns
+ the current UTC date and time.
+ See also now().
+
+ - fromtimestamp(timestamp)
+ Return the local \class{datetime} corresponding to the POSIX timestamp, such
+ as is returned by time.time(). This may raise ValueError, if the
+ timestamp is out of the range of values supported by the platform C
+ localtime() function. It's common for this to be restricted to
+ years in 1970 through 2038.
+ See also utcfromtimestamp().
+
+ - utcfromtimestamp(timestamp)
+ Return the UTC \class{datetime} corresponding to the POSIX timestamp.
+ This may raise ValueError, if the timestamp is out of the range of
+ values supported by the platform C gmtime() function. It's common
+ for this to be restricted to years in 1970 through 2038.
+ See also fromtimestamp().
+
+ - fromordinal(ordinal)
+ Return the \class{datetime} corresponding to the proleptic Gregorian ordinal,
+ where January 1 of year 1 has ordinal 1. ValueError is raised
+ unless 1 <= ordinal <= datetime.max.toordinal(). The hour, minute,
+ second and microsecond of the result are all 0.
+
+ - combine(date, time)
+ Return a new \class{datetime} object whose date components are equal to the
+ given date object's, and whose time components are equal to the given
+ time object's. For any \class{datetime} object d,
+ d == datetime.combine(d.date(), d.time()).
+ If date is a \class{datetime} or \class{datetimetz} object, its time components are
+ ignored. If date is \class{datetimetz} object, its tzinfo component is also
+ ignored. If time is a \class{timetz} object, its tzinfo component is ignored.
+
+Class attributes:
+
+ .min
+ The earliest representable datetime,
+ datetime(MINYEAR, 1, 1).
+
+ .max
+ The latest representable datetime,
+ datetime(MAXYEAR, 12, 31, 23, 59, 59, 999999).
+
+ .resolution
+ The smallest possible difference between non-equal datetime
+ objects, timedelta(microseconds=1).
+
+Instance attributes (read-only):
+
+ .year between MINYEAR and MAXYEAR inclusive
+ .month between 1 and 12 inclusive
+ .day between 1 and the number of days in the given month
+ of the given year
+ .hour in range(24)
+ .minute in range(60)
+ .second in range(60)
+ .microsecond in range(1000000)
+
+Supported operations:
+
+ - datetime1 + timedelta -> datetime2
+ timedelta + datetime1 -> datetime2
+ datetime2 is a duration of timedelta removed from datetime1, moving
+ forward in time if timedelta.days > 0, or backward if
+ timedelta.days < 0. datetime2 - datetime1 == timedelta after.
+ OverflowError is raised if datetime2.year would be smaller than
+ MINYEAR or larger than MAXYEAR.
+
+ - datetime1 - timedelta -> datetime2
+ Computes the datetime2 such that datetime2 + timedelta == datetime1.
+ This isn't quite equivalent to datetime1 + (-timedelta), because
+ -timedelta in isolation can overflow in cases where
+ datetime1 - timedelta does not.
+
+ - datetime1 - datetime2 -> timedelta
+ This is exact, and cannot overflow.
+ datetime2 + timedelta == datetime1 after.
+
+ - comparison of \class{datetime} to datetime, where datetime1 is considered
+ less than datetime2 when datetime1 precedes datetime2 in time.
+
+ - hash, use as dict key
+
+ - efficient pickling
+
+ - in Boolean contexts, all \class{datetime} objects are considered to be true
+
+Instance methods:
+
+ - date()
+ Return date object with same year, month and day.
+
+ - time()
+ Return time object with same hour, minute, second and microsecond.
+
+ - timetuple()
+ Return a 9-element tuple of the form returned by time.localtime().
+ The DST flag is -1. d.timetuple() is equivalent to
+ (d.year, d.month, d.day,
+ d.hour, d.minute, d.second,
+ d.weekday(), # 0 is Monday
+ d.toordinal() - date(d.year, 1, 1).toordinal() + 1, # day of year
+ -1)
+
+ - toordinal()
+ Return the proleptic Gregorian ordinal of the date. The same as
+ date.toordinal().
+
+ - weekday()
+ Return the day of the week as an integer, where Monday is 0 and
+ Sunday is 6. The same as date.weekday().
+ See also isoweekday().
+
+ - isoweekday()
+ Return the day of the week as an integer, where Monday is 1 and
+ Sunday is 7. The same as date.isoweekday().
+ See also weekday() and isocalendar().
+
+ - isocalendar()
+ Return a 3-tuple, (ISO year, ISO week number, ISO weekday). The
+ same as date.isocalendar().
+
+ - isoformat(sep='T')
+ Return a string representing the date and time in ISO 8601 format,
+ YYYY-MM-DDTHH:MM:SS.mmmmmm
+ or, if self.microsecond is 0,
+ YYYY-MM-DDTHH:MM:SS
+ Optional argument sep (default 'T') is a one-character separator,
+ placed between the date and time portions of the result. For example,
+ datetime(2002, 12, 4, 1, 2, 3, 4).isoformat(' ') ==
+ '2002-12-04 01:02:03.000004'
+
+ - __str__()
+ For a \class{datetime} d, str(d) is equivalent to d.isoformat(' ').
+
+ - ctime()
+ Return a string representing the date, for example
+ datetime(2002, 12, 4, 20, 30, 40).ctime() == 'Wed Dec 4 20:30:40 2002'.
+ d.ctime() is equivalent to time.ctime(time.mktime(d.timetuple()))
+ on platforms where the native C ctime() function (which time.ctime()
+ invokes, but which datetime.ctime() does not invoke) conforms to the
+ C standard.
+
+ - strftime(format)
+ Return a string representing the date and time, controlled by an
+ explicit format string. See the section on strftime() behavior.
+
+
+\subsection{\class{time} \label{datetime-time}}
+
+A time object represents an idealized time of day, independent of day
+and timezone.
+
+Constructor:
+
+ time(hour=0, minute=0, second=0, microsecond=0)
+
+ All arguments are optional. They may be ints or longs, in the
+ following ranges:
+
+ 0 <= hour < 24
+ 0 <= minute < 60
+ 0 <= second < 60
+ 0 <= microsecond < 1000000
+
+ If an argument outside those ranges is given, ValueError is raised.
+
+Other constructors (class methods):
+
+ None
+
+Class attributes:
+
+ .min
+ The earliest representable time, time(0, 0, 0, 0).
+
+ .max
+ The latest representable time, time(23, 59, 59, 999999).
+
+ .resolution
+ The smallest possible difference between non-equal time
+ objects, timedelta(microseconds=1), although note that
+ arithmetic on time objects is not supported.
+
+Instance attributes (read-only):
+
+ .hour in range(24)
+ .minute in range(60)
+ .second in range(60)
+ .microsecond in range(1000000)
+
+Supported operations:
+
+ - comparison of time to time, where time1 is considered
+ less than time2 when time1 precedes time2 in time.
+
+ - hash, use as dict key
+
+ - efficient pickling
+
+ - in Boolean contexts, a time object is considered to be true
+ if and only if it isn't equal to time(0)
+
+Instance methods:
+
+ - isoformat()
+ Return a string representing the time in ISO 8601 format,
+ HH:MM:SS.mmmmmm
+ or, if self.microsecond is 0
+ HH:MM:SS
+
+ - __str__()
+ For a time t, str(t) is equivalent to t.isoformat().
+
+ - strftime(format)
+ Return a string representing the time, controlled by an explicit
+ format string. See the section on strftime() behavior.
+
+
+\subsection{\class{tzinfo} \label{datetime-tzinfo}}
+
+tzinfo is an abstract base clase, meaning that objects directly of this
+class should not be instantiated. You need to derive a concrete
+subclass, and (at least) supply implementations of the standard tzinfo
+methods needed by the \class{datetime} methods you use. The \module{datetime} module does
+not supply any concrete subclasses of tzinfo.
+
+An instance of (a concrete subclass of) \class{tzinfo} can be passed to the
+constructors for \class{datetimetz} and \class{timetz} objects. The latter objects
+view their fields as being in local time, and the \class{tzinfo} object supports
+methods revealing offset of local time from UTC, the name of the time
+zone, and DST offset, all relative to a date or time object passed
+to them.
+
+A concrete subclass of \class{tzinfo} may need to implement the following
+methods. Exactly which methods are needed depends on the uses made
+of aware \class{datetime} objects; if in doubt, simply implement all of them.
+The methods are called by a \class{datetimetz} or \class{timetz} object, passing itself
+as the argument. A \class{tzinfo} subclass's methods should be prepared to
+accept a dt argument of type None, timetz, or datetimetz. If is not
+None, and dt.tzinfo is not None and not equal to self, an exception
+should be raised.
+
+ - utcoffset(dt)
+ Return offset of local time from UTC, in minutes east of UTC. If
+ local time is west of UTC, this should be negative. Note that this
+ is intended to be the total offset from UTC; for example, if a
+ \class{tzinfo} object represents both time zone and DST adjustments,
+ utcoffset() should return their sum. If the UTC offset isn't known,
+ return None. Else the value returned must be an int (or long), in
+ the range -1439 to 1439 inclusive (1440 = 24*60; the magnitude of
+ the offset must be less than one day).
+
+ - tzname(dt)
+ Return the timezone name corresponding to the \class{datetime} represented
+ by dt, as a string. Nothing about string names is defined by the
+ \module{datetime} module, and there's no requirement that it mean anything
+ in particular. For example, "GMT", "UTC", "-500", "-5:00", "EDT",
+ "US/Eastern", "America/New York" are all valid replies. Return
+ None if a string name isn't known. Note that this is a method
+ rather than a fixed string primarily because some \class{tzinfo} objects
+ will wish to return different names depending on the specific value
+ of dt passed, especially if the \class{tzinfo} class is accounting for DST.
+
+ - dst(dt)
+ Return the DST offset, in minutes east of UTC, or None if DST
+ information isn't known. Return 0 if DST is not in effect.
+ If DST is in effect, return an int (or long), in the range
+ -1439 to 1439 inclusive. Note that DST offset, if applicable,
+ has already been added to the UTC offset returned by utcoffset(),
+ so there's no need to consult dst() unless you're interested in
+ displaying DST info separately. For example, datetimetz.timetuple()
+ calls its \class{tzinfo} object's dst() method to determine how the tm_isdst
+ flag should be set.
+
+Example \class{tzinfo} classes:
+
+ class UTC(tzinfo):
+ "UTC"
+ def utcoffset(self, dt):
+ return 0
+ def tzname(self, dt):
+ return "UTC"
+ def dst(self, dt):
+ return 0
+
+ class FixedOffset(tzinfo):
+ "Fixed offset in minutes east from UTC"
+ def __init__(self, offset, name):
+ self.__offset = offset
+ self.__name = name
+ def utcoffset(self, dt):
+ return self.__offset
+ def tzname(self, dt):
+ return self.__name
+ def dst(self, dt):
+ # It depends on more than we know in an example.
+ return None # Indicate we don't know
+
+ import time
+ class LocalTime(tzinfo):
+ "Local time as defined by the operating system"
+ def _isdst(self, dt):
+ t = (dt.year, dt.month, dt.day, dt.hour, dt.minute, dt.second,
+ -1, -1, -1)
+ # XXX This may fail for years < 1970 or >= 2038
+ t = time.localtime(time.mktime(t))
+ return t.tm_isdst > 0
+ def utcoffset(self, dt):
+ if self._isdst(dt):
+ return -time.timezone/60
+ else:
+ return -time.altzone/60
+ def tzname(self, dt):
+ return time.tzname[self._isdst(dt)]
+
+
+\subsection{\class{timetz} \label{datetime-timetz}}
+
+A time object represents a (local) time of day, independent of any
+particular day, and subject to adjustment via a \class{tzinfo} object.
+
+Constructor:
+
+ time(hour=0, minute=0, second=0, microsecond=0, tzinfo=None)
+
+ All arguments are optional. tzinfo may be None, or an instance of
+ a \class{tzinfo} subclass. The remaining arguments may be ints or longs, in
+ the following ranges:
+
+ 0 <= hour < 24
+ 0 <= minute < 60
+ 0 <= second < 60
+ 0 <= microsecond < 1000000
+
+ If an argument outside those ranges is given, ValueError is raised.
+
+Other constructors (class methods):
+
+ None
+
+Class attributes:
+
+ .min
+ The earliest representable time, timetz(0, 0, 0, 0).
+
+ .max
+ The latest representable time, timetz(23, 59, 59, 999999).
+
+ .resolution
+ The smallest possible difference between non-equal timetz
+ objects, timedelta(microseconds=1), although note that
+ arithmetic on \class{timetz} objects is not supported.
+
+Instance attributes (read-only):
+
+ .hour in range(24)
+ .minute in range(60)
+ .second in range(60)
+ .microsecond in range(1000000)
+ .tzinfo the object passed as the tzinfo argument to the
+ \class{timetz} constructor, or None if none was passed.
+
+Supported operations:
+
+ - comparison of \class{timetz} to timetz, where timetz1 is considered
+ less than timetz2 when timetz1 precedes timetz2 in time, and
+ where the \class{timetz} objects are first adjusted by subtracting
+ their UTC offsets (obtained from self.utcoffset()).
+
+ - hash, use as dict key
+
+ - pickling
+
+ - in Boolean contexts, a \class{timetz} object is considered to be true
+ if and only if, after converting it to minutes and subtracting
+ self.utcoffset() (or 0 if that's None), the result is non-zero.
+
+Instance methods:
+
+ - isoformat()
+ Return a string representing the time in ISO 8601 format,
+ HH:MM:SS.mmmmmm
+ or, if self.microsecond is 0
+ HH:MM:SS
+ If self.utcoffset() does not return None, a 6-character string is
+ appended, giving the UTC offset in (signed) hours and minutes:
+ HH:MM:SS.mmmmmm+HH:MM
+ or, if self.microsecond is 0
+ HH:MM:SS+HH:MM
+
+ - __str__()
+ For a \class{timetz} t, str(t) is equivalent to t.isoformat().
+
+ - strftime(format)
+ Return a string representing the time, controlled by an explicit
+ format string. See the section on strftime() behavior.
+
+ - utcoffset()
+ If self.tzinfo is None, returns None, else self.tzinfo.utcoffset(self).
+
+ - tzname():
+ If self.tzinfo is None, returns None, else self.tzinfo.tzname(self).
+
+ - dst()
+ If self.tzinfo is None, returns None, else self.tzinfo.dst(self).
+
+
+
+\subsection{ \class{datetimetz} \label{datetime-datetimetz}}
+
+XXX I think this is *still* missing some methods from the
+XXX Python implementation.
+A \class{datetimetz} object is a single object containing all the information
+from a date object and a \class{timetz} object.
+
+Constructor:
+
+ datetimetz(year, month, day,
+ hour=0, minute=0, second=0, microsecond=0, tzinfo=None)
+
+ The year, month and day arguments are required. tzinfo may be None,
+ or an instance of a \class{tzinfo} subclass. The remaining arguments may be
+ ints or longs, in the following ranges:
+
+ MINYEAR <= year <= MAXYEAR
+ 1 <= month <= 12
+ 1 <= day <= number of days in the given month and year
+ 0 <= hour < 24
+ 0 <= minute < 60
+ 0 <= second < 60
+ 0 <= microsecond < 1000000
+
+ If an argument outside those ranges is given, ValueError is raised.
+
+Other constructors (class methods):
+
+ - today()
+ utcnow()
+ utcfromtimestamp(timestamp)
+ fromordinal(ordinal)
+
+ These are the same as the \class{datetime} class methods of the same names,
+ except that they construct a \class{datetimetz} object, with tzinfo None.
+
+ - now([tzinfo=None])
+ fromtimestamp(timestamp[, tzinfo=None])
+
+ These are the same as the \class{datetime} class methods of the same names,
+ except that they accept an additional, optional tzinfo argument, and
+ construct a \class{datetimetz} object with that \class{tzinfo} object attached.
+
+ - combine(date, time)
+ This is the same as datetime.combine(), except that it constructs
+ a \class{datetimetz} object, and, if the time object is of type timetz,
+ the \class{datetimetz} object has the same \class{tzinfo} object as the time object.
+
+Class attributes:
+
+ .min
+ The earliest representable datetimetz,
+ datetimetz(MINYEAR, 1, 1).
+
+ .max
+ The latest representable datetime,
+ datetimetz(MAXYEAR, 12, 31, 23, 59, 59, 999999).
+
+ .resolution
+ The smallest possible difference between non-equal datetimetz
+ objects, timedelta(microseconds=1).
+
+Instance attributes (read-only):
+
+ .year between MINYEAR and MAXYEAR inclusive
+ .month between 1 and 12 inclusive
+ .day between 1 and the number of days in the given month
+ of the given year
+ .hour in range(24)
+ .minute in range(60)
+ .second in range(60)
+ .microsecond in range(1000000)
+ .tzinfo the object passed as the tzinfo argument to the
+ \class{datetimetz} constructor, or None if none was passed.
+
+Supported operations:
+
+ - datetimetz1 + timedelta -> datetimetz2
+ timedelta + datetimetz1 -> datetimetz2
+ The same as addition of \class{datetime} objects, except that
+ datetimetz2.tzinfo is set to datetimetz1.tzinfo.
+
+ - datetimetz1 - timedelta -> datetimetz2
+ The same as addition of \class{datetime} objects, except that
+ datetimetz2.tzinfo is set to datetimetz1.tzinfo.
+
+ - aware_datetimetz1 - aware_datetimetz2 -> timedelta
+ \naive\_datetimetz1 - \naive\_datetimetz2 -> timedelta
+ \naive\_datetimetz1 - datetime2 -> timedelta
+ datetime1 - \naive\_datetimetz2 -> timedelta
+
+ Subtraction of a \class{datetime} or datetimetz, from a \class{datetime} or
+ datetimetz, is defined only if both operands are \naive, or if
+ both are aware. If one is aware and the other is \naive, TypeError
+ is raised.
+
+ If both are \naive, subtraction acts as for \class{datetime} subtraction.
+
+ If both are aware \class{datetimetz} objects, a-b acts as if a and b were
+ first converted to UTC datetimes (by subtracting a.utcoffset()
+ minutes from a, and b.utcoffset() minutes from b), and then doing
+ \class{datetime} subtraction, except that the implementation never
+ overflows.
+
+ - Comparison of \class{datetimetz} to \class{datetime} or datetimetz. As for
+ subtraction, comparison is defined only if both operands are
+ \naive\ or both are aware. If both are \naive, comparison is as
+ for \class{datetime} objects with the same date and time components.
+ If both are aware, comparison acts as if both were converted to
+ UTC datetimes first, except the the implementation never
+ overflows. If one comparand is \naive\ and the other aware,
+ TypeError is raised.
+
+ - hash, use as dict key
+
+ - efficient pickling
+
+ - in Boolean contexts, all \class{datetimetz} objects are considered to be
+ true
+
+Instance methods:
+
+ - date()
+ time()
+ toordinal()
+ weekday()
+ isoweekday()
+ isocalendar()
+ ctime()
+ __str__()
+ strftime(format)
+
+ These are the same as the \class{datetime} methods of the same names.
+
+ - timetz()
+ Return \class{timetz} object with same hour, minute, second, microsecond,
+ and tzinfo.
+
+ - utcoffset()
+ If self.tzinfo is None, returns None, else self.tzinfo.utcoffset(self).
+
+ - tzname():
+ If self.tzinfo is None, returns None, else self.tzinfo.tzname(self).
+
+ - dst()
+ If self.tzinfo is None, returns None, else self.tzinfo.dst(self).
+
+ - timetuple()
+ Like datetime.timetuple(), but sets the tm_isdst flag according to
+ the dst() method: if self.dst() returns None, tm_isdst is set to -1;
+ else if self.dst() returns a non-zero value, tm_isdst is set to 1;
+ else tm_isdst is set to 0.
+
+ - utctimetuple()
+ If \class{datetimetz} d is \naive, this is the same as d.timetuple() except
+ that tm_isdst is forced to 0 regardless of what d.dst() returns.
+ DST is never in effect for a UTC time.
+
+ If d is aware, d is normalized to UTC time, by subtracting
+ d.utcoffset() minutes, and a timetuple for the normalized time is
+ returned. tm_isdst is forced to 0. Note that the result's
+ tm_year field may be MINYEAR-1 or MAXYEAR+1, if d.year was MINYEAR
+ or MAXYEAR and UTC adjustment spills over a year boundary.
+
+ - isoformat(sep='T')
+ Return a string representing the date and time in ISO 8601 format,
+ YYYY-MM-DDTHH:MM:SS.mmmmmm
+ or, if self.microsecond is 0,
+ YYYY-MM-DDTHH:MM:SS
+
+ If self.utcoffset() does not return None, a 6-character string is
+ appended, giving the UTC offset in (signed) hours and minutes:
+ YYYY-MM-DDTHH:MM:SS.mmmmmm+HH:MM
+ or, if self.microsecond is 0
+ YYYY-MM-DDTHH:MM:SS+HH:MM
+
+ Optional argument sep (default 'T') is a one-character separator,
+ placed between the date and time portions of the result. For example,
+
+ >>> from \class{datetime} import *
+ >>> class TZ(tzinfo):
+ ... def utcoffset(self, dt): return -399
+ ...
+ >>> datetimetz(2002, 12, 25, tzinfo=TZ()).isoformat(' ')
+ '2002-12-25 00:00:00-06:39'
+ >>>
+
+ str(d) is equivalent to d.isoformat(' ').
+
+
+\subsection{C API}
+
+Struct typedefs:
+
+ PyDateTime_Date
+ PyDateTime_DateTime
+ PyDateTime_DateTimeTZ
+ PyDateTime_Time
+ PyDateTime_TimeTZ
+ PyDateTime_Delta
+ PyDateTime_TZInfo
+
+Type-check macros:
+
+ PyDate_Check(op)
+ PyDate_CheckExact(op)
+
+ PyDateTime_Check(op)
+ PyDateTime_CheckExact(op)
+
+ PyDateTimeTZ_Check(op)
+ PyDateTimeTZ_CheckExact(op)
+
+ PyTime_Check(op)
+ PyTime_CheckExact(op)
+
+ PyTimeTZ_Check(op)
+ PyTimeTZ_CheckExact(op)
+
+ PyDelta_Check(op)
+ PyDelta_CheckExact(op)
+
+ PyTZInfo_Check(op)
+ PyTZInfo_CheckExact(op
+
+Accessor macros:
+
+All objects are immutable, so accessors are read-only. All macros
+return ints:
+
+ For date, datetime, and \class{datetimetz} instances:
+ PyDateTime_GET_YEAR(o)
+ PyDateTime_GET_MONTH(o)
+ PyDateTime_GET_DAY(o)
+
+ For \class{datetime} and \class{datetimetz} instances:
+ PyDateTime_DATE_GET_HOUR(o)
+ PyDateTime_DATE_GET_MINUTE(o)
+ PyDateTime_DATE_GET_SECOND(o)
+ PyDateTime_DATE_GET_MICROSECOND(o)
+
+ For time and \class{timetz} instances:
+ PyDateTime_TIME_GET_HOUR(o)
+ PyDateTime_TIME_GET_MINUTE(o)
+ PyDateTime_TIME_GET_SECOND(o)
+ PyDateTime_TIME_GET_MICROSECOND(o)
projects / python / commitdiff