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

[Alexander Belopolsky]

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

After reading the new wording on a formatted page, I don't like the proposed changes:

"""
time.altzone

When daylight is nonzero, altzone specifies the offset of the local DST timezone, in seconds west of UTC. This is negative if the local DST timezone is east of UTC ...
"""

In the second sentence, it is not clear whether "this" refers to altzone or daylight.

"""
time.daylight

Whether or not DST is in effect, daylight specifies the DST offset. 
"""

This is simply wrong.  time.daylight does not necessarily specify the DST offset (and I think it does not on most systems.)  POSIX requires that "The tzset() function also shall set the external variable daylight to 0 if Daylight Savings Time conversions should never be applied for the timezone in use; otherwise, non-zero." [1]  This means that a compliant system may store just 0 or 1 in daylight rather than the DST offset.

For example, on my OSX system:

$ TZ=America/New_York python -c "import time; print(time.daylight)"
1
$ TZ=UTC python -c "import time; print(time.daylight)"
0
$ TZ=EDT python -c "import time; print(time.daylight)"
0

I will think some more on how to improve the current documentation, but at least with respect to time.daylight, current language is better than the proposed change.




[1] http://www.opengroup.org/onlinepubs/009695399/functions/tzset.html

----------
superseder:  -> Don't use east/west of UTC in date/time documentation

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