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

[Alexander Belopolsky]

Alexander Belopolsky <belopolsky at users.sourceforge.net> added the comment:

On Tue, Jan 11, 2011 at 4:55 AM, anatoly techtonik
<report at bugs.python.org> wrote:
..
> I propose the following change:
..
> http://docs.python.org/library/time.html#time.daylight
> -  Nonzero if a DST timezone is defined.
> + .. To check if DST is currently active, use `time.localtime(t).tm_isdst`

This is simply wrong. Your time.localtime(t).tm_isdst expression will
return the DST flag for the POSIX time value t, not for the current
time.  This could be fixed by replacing your proposed expression with
time.localtime().tm_isdst, but why do you think someone  reading about
time.daylight actually wants to "check if DST is currently active"?

What can be improved, though, is the documentation of time.tzset().
The current version fails to mention that  time.tzset() resets the
values of tzname, timezone, altzone and daylight.  This would be the
proper place to document the meaning of all three variables in greater
detail.  Individual entries can then refer to it with say "See
time.tzset() for details."

Here is how POSIX tzset() is defined:

"""
The tzset() function sets the external variable tzname as follows:

tzname[0] = "std";
tzname[1] = "dst";

where std and dst are as described in the XBD specification,
Environment Variables .

The tzset() function also sets the external variable daylight to 0 if
Daylight Savings Time conversions should never be applied for the time
zone in use; otherwise non-zero. The external variable timezone is set
to the difference, in seconds, between Coordinated Universal Time
(UTC) and local standard time.
"""  http://pubs.opengroup.org/onlinepubs/007908799/xsh/tzset.html

----------

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