[Python-checkins] python/dist/src/Doc/lib libdatetime.tex,1.25,1.26

[tim_one@users.sourceforge.net]

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}