[Python-checkins] python/dist/src/Doc/lib libdatetime.tex,1.15,1.16

Mon, 30 Dec 2002 12:52:34 -0800

Update of /cvsroot/python/python/dist/src/Doc/lib
In directory sc8-pr-cvs1:/tmp/cvs-serv32300/python/Doc/lib

Modified Files:
	libdatetime.tex 
Log Message:
A step on the way to making tzinfo classes writable by mortals:  get rid
of the timetz case.  A tzinfo method will always see a datetimetz arg,
or None, now.  In the former case, it's still possible that it will get
a datetimetz argument belonging to a different timezone.  That will get
fixed next.

Index: libdatetime.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libdatetime.tex,v
retrieving revision 1.15
retrieving revision 1.16
diff -C2 -d -r1.15 -r1.16
*** libdatetime.tex	30 Dec 2002 20:35:32 -0000	1.15
--- libdatetime.tex	30 Dec 2002 20:52:32 -0000	1.16
***************
*** 1,4 ****
  % XXX what order should the types be discussed in?
!  
  \section{\module{datetime} ---
           Basic date and time types}
--- 1,4 ----
  % XXX what order should the types be discussed in?
! 
  \section{\module{datetime} ---
           Basic date and time types}
***************
*** 786,796 ****
  In \code{range(24)}.
  \end{memberdesc}
! \begin{memberdesc}{minute}     
  In \code{range(60)}.
  \end{memberdesc}
! \begin{memberdesc}{second}         
  In \code{range(60)}.
  \end{memberdesc}
! \begin{memberdesc}{microsecond}    
  In \code{range(1000000)}.
  \end{memberdesc}
--- 786,796 ----
  In \code{range(24)}.
  \end{memberdesc}
! \begin{memberdesc}{minute}
  In \code{range(60)}.
  \end{memberdesc}
! \begin{memberdesc}{second}
  In \code{range(60)}.
  \end{memberdesc}
! \begin{memberdesc}{microsecond}
  In \code{range(1000000)}.
  \end{memberdesc}
***************
*** 845,849 ****
  subclass, and (at least) supply implementations of the standard
  \class{tzinfo} methods needed by the \class{datetime} methods you
! use. The \module{datetime} module does not supply any concrete
  subclasses of \class{tzinfo}.

--- 845,849 ----
  subclass, and (at least) supply implementations of the standard
  \class{tzinfo} methods needed by the \class{datetime} methods you
! use.  The \module{datetime} module does not supply any concrete
  subclasses of \class{tzinfo}.

***************
*** 855,859 ****
  date or time object passed to them.

! Special requirement for pickling:  A tzinfo subclass must have an
  \method{__init__} method that can be called with no arguments, else it
  can be pickled but possibly not unpickled again.  This is a technical
--- 855,859 ----
  date or time object passed to them.

! Special requirement for pickling:  A \class{tzinfo} subclass must have an
  \method{__init__} method that can be called with no arguments, else it
  can be pickled but possibly not unpickled again.  This is a technical
***************
*** 862,873 ****
  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 \module{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 \code{None} or of type \class{timetz} or
! \class{datetimetz}.

! \begin{methoddesc}{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
--- 862,869 ----
  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 \module{datetime} objects.  If in doubt, simply
! implement all of them.

! \begin{methoddesc}{utcoffset}{self, 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
***************
*** 879,886 ****
      the magnitude of the offset must be less than one day), or a
      \class{timedelta} object representing a whole number of minutes
!     in the same range.
  \end{methoddesc}

! \begin{methoddesc}{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
--- 875,886 ----
      the magnitude of the offset must be less than one day), or a
      \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{methoddesc}

! \begin{methoddesc}{tzname}{self, dt}
      Return the timezone name corresponding to the \class{datetime} represented
      by dt, as a string.  Nothing about string names is defined by the
***************
*** 894,898 ****
  \end{methoddesc}

! \begin{methoddesc}{dst}{dt}
      Return the DST offset, in minutes east of UTC, or \code{None} if
      DST information isn't known.  Return 0 if DST is not in effect.
--- 894,898 ----
  \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 0 if DST is not in effect.
***************
*** 907,910 ****
--- 907,930 ----
      \member{tm_isdst} flag should be set.
  \end{methoddesc}
+ 
+ These methods are called by a \class{datetimetz} or \class{timetz} object,
+ in response to their methods of the same names.  A \class{datetimetz}
+ object passes itself as the argument, and a \class{timetz} object passes
+ \code{None} as the argument.  A \class{tzinfo} subclass's methods should
+ therefore be prepared to accept a \var{dt} argument of \code{None}, or of
+ class \class{datetimetz}.
+ 
+ When \code{None} is passed, it's up to the class designer to decide the
+ best response.  For example, returning \code{None} is appropriate if the
+ class wishes to say that timetz objects don't participate in the
+ \class{tzinfo} protocol.  In other applications, it may be more useful
+ for \code{utcoffset(None}} to return the standard UTC offset.
+ 
+ When a \class{datetimetz} object is passed in response to a
+ \class{datetimetz} method, \code{dt.tzinfo} is the same object as
+ \var{self}.  \class{tzinfo} methods can rely on this, unless
+ user code calls \class{tzinfo} methods directly.  The intent is that
+ the \class{tzinfo} methods interpret \var{dt} as being in local time,
+ and not need to worry about objects in other timezones.

  Example \class{tzinfo} classes: