[Python-checkins] python/dist/src/Doc/lib libdatetime.tex,1.25,1.26
tim_one@users.sourceforge.net
tim_one@users.sourceforge.net
Wed, 01 Jan 2003 13:51:38 -0800
Update of /cvsroot/python/python/dist/src/Doc/lib
In directory sc8-pr-cvs1:/tmp/cvs-serv23673/python/Doc/lib
Modified Files:
libdatetime.tex
Log Message:
A quicker astimezone() implementation, rehabilitating an earlier
suggestion from Guido, along with a formal correctness proof of the
trickiest bit. The intricacy of the proof reveals how delicate this
is, but also how robust the conclusion: correctness doesn't rely on
dst() returning +- one hour (not all real time zones do!), it only
relies on:
1. That dst() returns a (any) non-zero value if and only if daylight
time is in effect.
and
2. That the tzinfo subclass implements a consistent notion of time zone.
The meaning of "consistent" was a hidden assumption, which is now an
explicit requirement in the docs. Alas, it's an unverifiable (by the
datetime implementation) requirement, but so it goes.
Index: libdatetime.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libdatetime.tex,v
retrieving revision 1.25
retrieving revision 1.26
diff -C2 -d -r1.25 -r1.26
*** libdatetime.tex 31 Dec 2002 18:31:48 -0000 1.25
--- libdatetime.tex 1 Jan 2003 21:51:36 -0000 1.26
***************
*** 888,895 ****
\class{timedelta} object representing a whole number of minutes
in the same range. Most implementations of \method{utcoffset()}
! will probably look like:
\begin{verbatim}
! return CONSTANT # fixed-offset class
return CONSTANT + self.dst(dt) # daylight-aware class
\end{verbatim}
--- 888,895 ----
\class{timedelta} object representing a whole number of minutes
in the same range. Most implementations of \method{utcoffset()}
! will probably look like one of these two:
\begin{verbatim}
! return CONSTANT # fixed-offset class
return CONSTANT + self.dst(dt) # daylight-aware class
\end{verbatim}
***************
*** 906,915 ****
will wish to return different names depending on the specific value
of \var{dt} passed, especially if the \class{tzinfo} class is
! accounting for DST.
\end{methoddesc}
\begin{methoddesc}{dst}{self, dt}
! Return the DST offset, in minutes east of UTC, or \code{None} if
! DST information isn't known. Return \code{0} if DST is not in effect.
If DST is in effect, return the offset as an integer or
\class{timedelta} object (see \method{utcoffset()} for details).
--- 906,916 ----
will wish to return different names depending on the specific value
of \var{dt} passed, especially if the \class{tzinfo} class is
! accounting for daylight time.
\end{methoddesc}
\begin{methoddesc}{dst}{self, dt}
! Return the daylight savings time (DST) adjustment, in minutes east of
! UTC, or \code{None} if DST information isn't known. Return \code{0} if
! DST is not in effect.
If DST is in effect, return the offset as an integer or
\class{timedelta} object (see \method{utcoffset()} for details).
***************
*** 920,924 ****
example, \method{datetimetz.timetuple()} calls its \member{tzinfo}
member's \method{dst()} method to determine how the
! \member{tm_isdst} flag should be set.
\end{methoddesc}
--- 921,941 ----
example, \method{datetimetz.timetuple()} calls its \member{tzinfo}
member's \method{dst()} method to determine how the
! \member{tm_isdst} flag should be set, and
! \method{datetimetz.astimezone()} calls \method{dst()} to account for
! DST changes when crossing time zones.
!
! An instance \var{tz} of a \class{tzinfo} subclass that models both
! standard and daylight times must be consistent in this sense:
!
! \code{tz.utcoffset(dt) - tz.dst(dt)}
!
! must return the same result for every \class{datetimetz} \var{dt}
! in a given year with \code{dt.tzinfo==tz} For sane \class{tzinfo}
! subclasses, this expression yields the time zone's "standard offset"
! within the year, which should be the same across all days in the year.
! The implementation of \method{datetimetz.astimezone()} relies on this,
! but cannot detect violations; it's the programmer's responsibility to
! ensure it.
!
\end{methoddesc}