New rule for tzinfo subclasses handling both standard and daylight time:

When daylight time ends, an hour repeats on the local clock (for example,
in US Eastern, the clock jumps from 1:59 back to 1:00 again).  Times in
the repeated hour are ambiguous.  A tzinfo subclass that wants to play
with astimezone() needs to treat times in the repeated hour as being
standard time.  astimezone() previously required that such times be
treated as daylight time.  There seems no killer argument either way,
but Guido wants the standard-time version, and it does seem easier the
new way to code both American (local-time based) and European (UTC-based)
switch rules, and the astimezone() implementation is simpler.

2 files changed, 38 insertions, 32 deletions

diff --git a/Doc/lib/libdatetime.tex b/Doc/lib/libdatetime.tex
index 18edc32..2421fa7 100644
--- a/Doc/lib/libdatetime.tex
+++ b/Doc/lib/libdatetime.tex
@@ -30,7 +30,7 @@ the cost of ignoring some aspects of reality.
 
 For applications requiring more, \class{datetime} and \class{time}
 objects have an optional time zone information member,
-\member{tzinfo}, that can contain an instance of a subclass of 
+\member{tzinfo}, that can contain an instance of a subclass of
 the abstract \class{tzinfo} class.  These \class{tzinfo} objects
 capture information about the offset from UTC time, the time zone
 name, and whether Daylight Saving Time is in effect.  Note that no
@@ -1048,8 +1048,10 @@ implement all of them.
 
     If \method{utcoffset()} does not return \code{None},
     \method{dst()} should not return \code{None} either.
-\end{methoddesc}
 
+    The default implementation of \method{utcoffset()} raises
+    \exception{NotImplementedError}.
+\end{methoddesc}
 
 \begin{methoddesc}{dst}{self, dt}
   Return the daylight saving time (DST) adjustment, in minutes east of
@@ -1060,7 +1062,7 @@ implement all of them.
   Note that DST offset, if applicable, has
   already been added to the UTC offset returned by
   \method{utcoffset()}, so there's no need to consult \method{dst()}
-  unless you're interested in displaying DST info separately.  For
+  unless you're interested in obtaining DST info separately.  For
   example, \method{datetime.timetuple()} calls its \member{tzinfo}
   member's \method{dst()} method to determine how the
   \member{tm_isdst} flag should be set, and
@@ -1080,6 +1082,10 @@ implement all of them.
   cannot detect violations; it's the programmer's responsibility to
   ensure it.
 
+  The default implementation of \method{dst()} raises
+  \exception{NotImplementedError}.
+\end{methoddesc}
+
 \begin{methoddesc}{tzname}{self, dt}
   Return the timezone name corresponding to the \class{datetime}
   object represented
@@ -1092,8 +1098,9 @@ implement all of them.
   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}
 
+  The default implementation of \method{tzname()} raises
+  \exception{NotImplementedError}.
 \end{methoddesc}
 
 These methods are called by a \class{datetime} or \class{time} object,
@@ -1106,21 +1113,23 @@ class \class{datetime}.
 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 time 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.
+\class{tzinfo} protocol.  It may be more useful for \code{utcoffset(None)}
+to return the standard UTC offset, as there is no other convention for
+discovering the standard offset.
 
 When a \class{datetime} object is passed in response to a
 \class{datetime} 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.
+and not need worry about objects in other timezones.
 
 Example \class{tzinfo} classes:
 
 \verbatiminput{tzinfo-examples.py}
 
-Note that there are unavoidable subtleties twice per year in a tzinfo
+Note that there are unavoidable subtleties twice per year in a
+\class{tzinfo}
 subclass accounting for both standard and daylight time, at the DST
 transition points.  For concreteness, consider US Eastern (UTC -0500),
 where EDT begins the minute after 1:59 (EST) on the first Sunday in
@@ -1140,32 +1149,29 @@ When DST starts (the "start" line), the local wall clock leaps from 1:59
 to 3:00.  A wall time of the form 2:MM doesn't really make sense on that
 day, so \code{astimezone(Eastern)} won't deliver a result with
 \code{hour==2} on the
-day DST begins.  How an Eastern instance chooses to interpret 2:MM on
-that day is its business.  The example Eastern implementation above
-chose to
-consider it as a time in EDT, simply because it "looks like it's
-after 2:00", and so synonymous with the EST 1:MM times on that day.
-Your Eastern class may wish, for example, to raise an exception instead
-when it sees a 2:MM time on the day EDT begins.
+day DST begins.  In order for \method{astimezone()} to make this
+guarantee, the \class{tzinfo} \method{dst()} method must consider times
+in the "missing hour" (2:MM for Eastern) to be in daylight time.
 
 When DST ends (the "end" line), there's a potentially worse problem:
-there's an hour that can't be spelled unambiguously in local wall time, the
-hour beginning at the moment DST ends.  In this example, that's times of
-the form 6:MM UTC on the day daylight time ends.  The local wall clock
+there's an hour that can't be spelled unambiguously in local wall time:
+the last hour of daylight time.  In Eastern, that's times of
+the form 5:MM UTC on the day daylight time ends.  The local wall clock
 leaps from 1:59 (daylight time) back to 1:00 (standard time) again.
-1:MM is taken as daylight time (it's "before 2:00"), so maps to 5:MM UTC.
-2:MM is taken as standard time (it's "after 2:00"), so maps to 7:MM UTC.
-There is no local time that maps to 6:MM UTC on this day.
-
-Just as the wall clock does, \code{astimezone(Eastern)} maps both UTC
-hours 5:MM
-and 6:MM to Eastern hour 1:MM on this day.  However, this result is
-ambiguous (there's no way for Eastern to know which repetition of 1:MM
-is intended).  Applications that can't bear such ambiguity
-should avoid using hybrid tzinfo classes; there are no
-ambiguities when using UTC, or any other fixed-offset tzinfo subclass
-(such as a class representing only EST (fixed offset -5 hours), or only
-EDT (fixed offset -4 hours)).
+Local times of the form 1:MM are ambiguous.  \method{astimezone()} mimics
+the local clock's behavior by mapping two adjacent UTC hours into the
+same local hour then.  In the Eastern example, UTC times of the form
+5:MM and 6:MM both map to 1:MM when converted to Eastern.  In order for
+\method{astimezone()} to make this guarantee, the \class{tzinfo}
+\method{dst()} method must consider times in the "repeated hour" to be in
+standard time.  This is easily arranged, as in the example, by expressing
+DST switch times in the time zone's standard local time.
+
+Applications that can't bear such ambiguities should avoid using hybrid
+\class{tzinfo} subclasses; there are no ambiguities when using UTC, or
+any other fixed-offset \class{tzinfo} subclass (such as a class
+representing only EST (fixed offset -5 hours), or only EDT (fixed offset
+-4 hours)).
 
 
 \subsection{\method{strftime()} Behavior}
diff --git a/Doc/lib/tzinfo-examples.py b/Doc/lib/tzinfo-examples.py
index cea0309..b488dd0 100644
--- a/Doc/lib/tzinfo-examples.py
+++ b/Doc/lib/tzinfo-examples.py
@@ -91,7 +91,7 @@ def first_sunday_on_or_after(dt):
 DSTSTART = datetime(1, 4, 1, 2)
 # and ends at 2am (DST time; 1am standard time) on the last Sunday of Oct.
 # which is the first Sunday on or after Oct 25.
-DSTEND = datetime(1, 10, 25, 2)
+DSTEND = datetime(1, 10, 25, 1)
 
 class USTimeZone(tzinfo):