[issue7229] Manual entry for time.daylight can be misleading

[anatoly techtonik]

anatoly techtonik <techtonik at gmail.com> added the comment:

Classic user developer impedance mismatch. =)

I agree that Python should guard its users against crazy standards that creep into standard lib, because nobody had time to think about pythonic API.

I propose the following change:

http://docs.python.org/library/time.html#time.altzone
-  UTC offset of the local DST timezone if one is defined. Only use this if daylight is nonzero.
+  UTC offset of the current timezone with Daylight Savings Time (DST) correction. To check if DST is currently active, use `time.localtime(t).tm_isdst`

http://docs.python.org/library/time.html#time.daylight
-  Nonzero if a DST timezone is defined.
+  Flag indicating that current timezone has Daylight Savings Time (DST) offset. To check if DST is currently active, use `time.localtime(t).tm_isdst`

http://docs.python.org/library/time.html#time.timezone
-  UTC offset of the local (non-DST) timezone
+  UTC offset of the current timezone. It doesn't include Daylight Savings Time (DST) correction. See `time.altzone` for that.


BTW, isn't the following check redundant?
    if time.localtime(t).tm_isdst and time.daylight:

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue7229>
_______________________________________