[issue7229] Manual entry for time.daylight can be misleading
anatoly techtonik <techtonik@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@bugs.python.org> <http://bugs.python.org/issue7229> _______________________________________
Alexander Belopolsky <belopolsky@users.sourceforge.net> added the comment: On Tue, Jan 11, 2011 at 4:55 AM, anatoly techtonik <report@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@bugs.python.org> <http://bugs.python.org/issue7229> _______________________________________
anatoly techtonik <techtonik@gmail.com> added the comment: On Tue, Jan 11, 2011 at 4:52 PM, Alexander Belopolsky <report@bugs.python.org> wrote:
..
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"?
Sorry, I've just copy/pasted this snippet and haven't noticed t argument. As for your question, I think that someone reading about time.daylight is reading about it to know how it can be used, and if you're quoting, please quote without removing words inside the quote, or else I won't be able to give you the answers that will be appropriate in your context.
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."
How about making it in iterations and keep the steps as small as possible, i.e. split the big problem into munchable chunks? First we can accept the version of doc from my previous comment and then open a new RFE for further work. Considering how much time this issue took already, I see this approach as the only viable one.
Here is how POSIX tzset() is defined: ...
I am sorry Alexander, but I can't really follow up on this issue. It is interesting, but unfortunately right now I can only dedicate my time to things that take don't more than 15 minutes of my attention, and there are about 50 out of 700 of these in my inbox right now. We need to split these datetime problems into smaller ones somehow. They are really too complex for users. To summarize: What is wrong with my previous proposal if we remove t from params? P.S. Looks like we need a PEP for this. =) ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue7229> _______________________________________
Alexander Belopolsky <belopolsky@users.sourceforge.net> added the comment: On Tue, Jan 11, 2011 at 4:15 PM, anatoly techtonik <report@bugs.python.org> wrote: ..
To summarize: What is wrong with my previous proposal if we remove t from params?
Not much is wrong with it. If it would come in a form of a patch and without typos or mark-up mistakes, I or another committer would probably apply it as an incremental improvement. However, given that additional effort is needed to apply your suggestion, I would rather wait until a better solution is available. Specifically, I don like the duplication of time.localtime().tm_isdst recipe in daylight and altzone. Also, these variables should really be grouped together in the docs. I would like this to be done before a committer spends time proofreading, fixing reST markup and committing the change. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue7229> _______________________________________
participants (2)
-
Alexander Belopolsky -
anatoly techtonik