SF bug 660872: datetimetz constructors behave counterintuitively (2.3a1).

This gives much the same treatment to datetime.fromtimestamp(stamp, tz) as
the last batch of checkins gave to datetime.now(tz):  do "the obvious"
thing with the tz argument instead of a senseless thing.

1 files changed, 19 insertions, 10 deletions

diff --git a/Doc/lib/libdatetime.tex b/Doc/lib/libdatetime.tex
index b890024..058d6d5 100644
--- a/Doc/lib/libdatetime.tex
+++ b/Doc/lib/libdatetime.tex
@@ -534,26 +534,35 @@ Other constructors, all class methods:
   \cfunction{gettimeofday()} function).
 
   Else \var{tz} must be an instance of a class \class{tzinfo} subclass,
-  and the current date and time are translated to \var{tz}'s time
+  and the current date and time are converted to \var{tz}'s time
   zone.  In this case the result is equivalent to
-  \code{\var{tz}.fromutc(datetime.utcnow().replace(tzinfo=\var{tz})}.
+  \code{\var{tz}.fromutc(datetime.utcnow().replace(tzinfo=\var{tz}))}.
   See also \method{today()}, \method{utcnow()}.
 \end{methoddesc}
 
 \begin{methoddesc}{utcnow}{}
   Return the current UTC date and time, with \member{tzinfo} \code{None}.
-  This is like \method{now()}, but  returns the current UTC date and time,
+  This is like \method{now()}, but returns the current UTC date and time,
   as a naive \class{datetime} object.
   See also \method{now()}.
 \end{methoddesc}
 
-\begin{methoddesc}{fromtimestamp}{timestamp}
-  Return the local \class{datetime} corresponding to the \POSIX{}
-  timestamp, such as is returned by \function{time.time()}.  This
-  may raise \exception{ValueError}, if the timestamp is out of the
-  range of values supported by the platform C
-  \cfunction{localtime()} function.  It's common for this to be
-  restricted to years in 1970 through 2038.
+\begin{methoddesc}{fromtimestamp}{timestamp, tz=None}
+  Return the local date and time corresponding to the \POSIX{}
+  timestamp, such as is returned by \function{time.time()}.
+  If optional argument \var{tz} is \code{None} or not specified, the
+  timestamp is converted to the platform's local date and time, and
+  the returned \class{datetime} object is naive.
+
+  Else \var{tz} must be an instance of a class \class{tzinfo} subclass,
+  and the timestamp is converted to \var{tz}'s time zone.  In this case
+  the result is equivalent to
+  \code{\var{tz}.fromutc(datetime.utcfromtimestamp(\var{timestamp}).replace(tzinfo=\var{tz}))}.
+
+  \method{fromtimestamp()} may raise \exception{ValueError}, if the
+  timestamp is out of the range of values supported by the platform C
+  \cfunction{localtime()} or \cfunction(gmtime()} functions.  It's common
+  for this to be restricted to years in 1970 through 2038.
   Note that on non-POSIX systems that include leap seconds in their
   notion of a timestamp, leap seconds are ignored by
   \method{fromtimestamp()}, and then it's possible to have two timestamps