Add aware local time support to datetime module

Lib/datetime.py

 """Concrete date/time and related types -- prototype implemented in Python.
 
 See http://www.zope.org/Members/fdrake/DateTimeWiki/FrontPage
 
 See also http://dir.yahoo.com/Reference/calendars/
 
 For a primer on DST, including many current DST rules, see
 http://webexhibits.org/daylightsaving/
 
 For more about DST than you ever wanted to know, see
@@ skipping 1397 matching lines @@
     @classmethod
     def combine(cls, date, time):
         "Construct a datetime from a given date and a given time."
         if not isinstance(date, _date_class):
             raise TypeError("date argument must be a date instance")
         if not isinstance(time, _time_class):
             raise TypeError("time argument must be a time instance")
         return cls(date.year, date.month, date.day,
                    time.hour, time.minute, time.second, time.microsecond,
                    time.tzinfo)
+
+    @classmethod
+    def localtime(cls, t=None, isdst=-1):

[techtonik, 2011/01/14 01:14:26]

The t param should probably be called 'time'.

[sasha, 2011/01/14 04:30:11]

Yes, a better name should be found, although it won't matter for the C
implementation.   I would not call it "time" because that conflicts with the
time class and localtime expects a datetime instance in t.

[techtonik, 2011/01/14 18:28:50]

dt is a consistent name for datetime parameters in Python manual.

+        """Return local time as an aware datetime object.

[techtonik, 2011/01/14 01:14:26]

ISTM that we need an object hierarchy like DateTime->DateTimeTZ, because
debugging which object is TZ aware and which is not is rather hard. 

[sasha, 2011/01/14 04:30:11]

Early versions of datetime has a separate datetimetz class.  I don't remember
what were the actual reasons for removing it, but I am glad that this was done. 
Hopefully applications will stop using naive datetime objects at some point, so
there will be less need to distinguish naive and aware instances.

[techtonik, 2011/01/14 18:28:50]

It must be recorded for history if we want to get rid of date/time curse in
Python4 without missing any details. Removing naive objects in favor of
normalized objects with UTC timestamps seems like a way to go.

+
+        If called without arguments, return current time.  Otherwise
+        *t* is converted to local time zone according to the system
+        time zone database.  If *t* is naive (i.e. t.tzinfo is None),
+        it is assumed to be in local time.  In this case, a positive or
+        zero value for *isdst* causes localtime to presume initially
+        that summer time (for example, Daylight Saving Time) is or is
+        not (respectively) in effect for the specified time.  A
+        negative value for *isdst* causes the localtime() function to
+        attempt to divine whether summer time is in effect for the
+        specified time.  
+        """
+        if t is None:
+            t = _time.time()

[techtonik, 2011/01/14 01:14:26]

Here we should always receive aware object, but I couldn't find reference to C
standard to ensure that all systems return this correctly.

[sasha, 2011/01/14 04:30:11]

No.  _time.time() returns seconds since epoch. Naive/aware distinction is not
applicable.

[techtonik, 2011/01/14 18:28:50]

On 2011/01/14 04:30:11, sasha wrote: 
But these seconds are in UTC. There is no TZ correction.

+        else:
+            if t.tzinfo is None:

[techtonik, 2011/01/14 01:14:26]

I'd replace this with elif and place comment that here we detect non-aware time
object. Docstring above is nice, but it will probably be parsed into
documentation, and I am not sure if these details should be present in user
manual.

[sasha, 2011/01/14 04:30:11]

Yes, elif would probably be cleaner and I'll add comments.

+                tm = t.timetuple()[:-1] + (isdst,)

[techtonik, 2011/01/14 01:14:26]

IIUC return result of time() value is time.struct_time which doesn't have
timetuple() method. If you work with datetime objects only, then you need to
name variables accordingly.

[sasha, 2011/01/14 04:30:11]

No, t here has not been converted to seconds yet, it is still a timedelta
instance.  It was probably an ill-advised optimization to reuse t variable for
seconds calculation.  I'll think of a better name for the timedelta argument and
use two variables instead of one.

+                t = _time.mktime(tm)
+            else:
+                delta = t - datetime(1970, 1, 1, tzinfo=timezone.utc)
+                t = delta.total_seconds()
+        tm = _time.localtime(t)
+        if _time.daylight:
+            if tm.tm_isdst:
+                offset = _time.altzone
+                tzname = _time.tzname[1]
+            else:
+                offset = _time.timezone
+                tzname = _time.tzname[0]
+        tz = timezone(timedelta(seconds=-offset), tzname)
+        return cls.fromtimestamp(t, tz)
 
     def timetuple(self):
         "Return local time tuple compatible with time.localtime()."
         dst = self.dst()
         if dst is None:
             dst = -1
         elif dst:
             dst = 1
         else:
             dst = 0
@@ skipping 659 matching lines @@
          _check_time_fields, _check_tzinfo_arg, _check_tzname,
          _check_utc_offset, _cmp, _cmperror, _date_class, _days_before_month,
          _days_before_year, _days_in_month, _format_time, _is_leap,
          _isoweek1monday, _math, _ord2ymd, _time, _time_class, _tzinfo_class,
          _wrap_strftime, _ymd2ord)
     # XXX Since import * above excludes names that start with _,
     # docstring does not get overwritten. In the future, it may be
     # appropriate to maintain a single module level docstring and
     # remove the following line.
     from _datetime import __doc__