#2525: update timezone info examples in the docs.

Doc/includes/tzinfo-examples.py

@@ -87,11 +87,31 @@ def first_sunday_on_or_after(dt):
         dt += timedelta(days_to_go)
     return dt
 
-# In the US, DST starts at 2am (standard time) on the first Sunday in April.
-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, 1)
+
+# US DST Rules
+#
+# This is a simplified (i.e., wrong for a few cases) set of rules for US
+# DST start and end times. For a complete and up-to-date set of DST rules
+# and timezone definitions, visit the Olson Database (or try pytz):
+# http://www.twinsun.com/tz/tz-link.htm
+# http://sourceforge.net/projects/pytz/ (might not be up-to-date)
+#
+# In the US, since 2007, DST starts at 2am (standard time) on the second
+# Sunday in March, which is the first Sunday on or after Mar 8.
+DSTSTART_2007 = datetime(1, 3, 8, 2)
+# and ends at 2am (DST time; 1am standard time) on the first Sunday of Nov.
+DSTEND_2007 = datetime(1, 11, 1, 1)
+# From 1987 to 2006, DST used to start at 2am (standard time) on the first
+# Sunday in April and to end at 2am (DST time; 1am standard time) on the last
+# Sunday of October, which is the first Sunday on or after Oct 25.
+DSTSTART_1987_2006 = datetime(1, 4, 1, 2)
+DSTEND_1987_2006 = datetime(1, 10, 25, 1)
+# From 1967 to 1986, DST used to start at 2am (standard time) on the last
+# Sunday in April (the one on or after April 24) and to end at 2am (DST time;
+# 1am standard time) on the last Sunday of October, which is the first Sunday
+# on or after Oct 25.
+DSTSTART_1967_1986 = datetime(1, 4, 24, 2)
+DSTEND_1967_1986 = DSTEND_1987_2006
 
 class USTimeZone(tzinfo):
 
@@ -122,9 +142,19 @@ class USTimeZone(tzinfo):
             return ZERO
         assert dt.tzinfo is self
 
-        # Find first Sunday in April & the last in October.
-        start = first_sunday_on_or_after(DSTSTART.replace(year=dt.year))
-        end = first_sunday_on_or_after(DSTEND.replace(year=dt.year))
+        # Find start and end times for US DST. For years before 1967, return
+        # ZERO for no DST.
+        if 2006 < dt.year:
+            dststart, dstend = DSTSTART_2007, DSTEND_2007
+        elif 1986 < dt.year < 2007:
+            dststart, dstend = DSTSTART_1987_2006, DSTEND_1987_2006
+        elif 1966 < dt.year < 1987:
+            dststart, dstend = DSTSTART_1967_1986, DSTEND_1967_1986
+        else:
+            return ZERO
+
+        start = first_sunday_on_or_after(dststart.replace(year=dt.year))
+        end = first_sunday_on_or_after(dstend.replace(year=dt.year))
 
         # Can't compare naive to aware objects, so strip the timezone from
         # dt first.