New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Manual entry for time.daylight can be misleading #51478
Comments
Hello, it is not obvious that the time.daylight data item reports nonzero Current manual entry can be misleadingly interpreted that time.daylight Suggested FIX: Add a sentence: Tomas |
Run into the same problem in issue bpo-7582. Patch attached, but wording can be improved. |
Perhaps altzone() documentation is also wrong. Brian, can you comment on this? |
I don't think altzone was incorrect, but it could also use a little rewording. Attached is a patch which rewords daylight and altzone. Thoughts? |
bpo-8907 seems related. |
It may be a bit off-topic for this issue, but I don't like that the python manual uses UTC as if it was a geographical location. UTC is a time scale. You cannot be to the east or to the west of UTC just as you cannot be to the north of the Gregorian calendar. Even if we replace UTC with Prime or Greenwich Meridian, the manual would still be incorrect because some regions in the western hemisphere use positive offsets from UTC. For example, Madrid is at 3° 42' West, but uses Central European Time which is UTC+1. Since there are no plans to include any kind of geographical database in the standard library, I think the manual should avoid use of geographical terms. What I need to know from the manual is how to get local time from utc and daylight savings time from the standard time. From the top of my head, I know that localtime = utctime + utcoffset, but I am not sure whether dsttime = stdtime + dst or dsttime = stdtime - dst and the manual, reworded or not, does not immediately help me. As for the original issue, do we really need time.daylight at all? ISTM that in timezones without DST, time.altzone = time.timezone, so the software that unconditionally accounts for DST will still work correctly and software that wants to optimize for no DST case can simply chsck time.altzone == time.timezone. $ TZ=UTC ./python.exe -c "import time; print(time.daylight, time.tzname, (time.timezone, time.altzone))"
0 ('UTC', 'UTC') (0, 0) In other words, time.daylight is strictly redundant. |
It is too hard to track this issue without quotes from manual. Let's bring context into discussion: http://docs.python.org/library/time.html#time.altzone So, to answer a question "What is the current UTC offset?" you need to:
As for offtopic UTC vs GMT - I doubt there is a way to clearly express that the offset sign of the returned values is negated in comparison with real "UTC offsets" without resorting to some king of alternative east/west scale. |
On Sat, Jun 5, 2010 at 1:24 PM, anatoly techtonik
Sure there is. Here is how RFC 3339 handles this: """ and here is a quote from MacOS man page for tzset: """ No geographic reference needed. (And the issue is not UTC vs. GMT: |
On Sat, Jun 5, 2010 at 1:24 PM, anatoly techtonik
No, if time.daylight is non-zero, you still need to check the current Here is how bzr reportedly handles this: def local_time_offset(t=None):
"""Return offset of local zone from GMT, either at present or at time t."""
# python2.3 localtime() can't take None
if t is None:
t = time.time()
if time.localtime(t).tm_isdst and time.daylight:
return -time.altzone
else:
return -time.timezone http://blogs.gnome.org/jamesh/2006/12/31/python-timetimezone-timealtzone-edge-case/
That works for current time, but subject to race condition twice a
The come from existing C library practice. POSIX defines tzname[2], http://www.opengroup.org/onlinepubs/009695399/basedefs/time.h.html altzone is a popular non-standard addition which is strictly These variables are already grouped in tzinfo API. What is missing is |
Georg, Do you mind if I take this over? While I have issues with east/west of UTC terminology, it is the accepted terminology throughout the manual and Brian's rewording is an improvement. |
Please do! |
After reading the new wording on a formatted page, I don't like the proposed changes: """ 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. """ 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 |
I am going to reject this. None of the proposed changes seem to be better than the current documentation. The time.daylight variable has the same meaning as eponymous C variable defined in time.h header. The latter is described in widely available and well known C and POSIX standards. Users that find Python manual description confusing or incomplete can easily find clarifications or details in other sources. |
I am sorry, but as an original initiator of the the issue I find the argumentation of Alexander Belopolsky vastly ridiculous. Are you really seriously convinced that an average person responsible for Python application development and maintenance would be aware of a necessity to look for an ANSI C documentation to find a description and definitions of time functions? You sound like Marie Antoinette who replied to peasants complaining the they do not have any bread to eat that they should eat brioches instead. Maybe in the context of the “royal programmers family” documentation to ANSI C is wildly known and even memorized, but I do insist that Python documentation should be accessible and understandable even to ordinary peasants of the computer kingdom. And I keep my case that the current description might trick programmers to think that it holds information whether the summer time currently applies rather than just plain information about current time zone being able to use summer time. Regards |
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
http://docs.python.org/library/time.html#time.daylight
http://docs.python.org/library/time.html#time.timezone
BTW, isn't the following check redundant? |
Hello, I find this version very clear. Thanks |
On Tue, Jan 11, 2011 at 4:55 AM, anatoly techtonik
This is simply wrong. Your time.localtime(t).tm_isdst expression will What can be improved, though, is the documentation of time.tzset(). Here is how POSIX tzset() is defined: """ tzname[0] = "std"; where std and dst are as described in the XBD specification, The tzset() function also sets the external variable daylight to 0 if |
If you are not familiar with the cryptic names of POSIX but live in normal world, time.daylight sounds like a quite probable place where to check if the daylight savings are active. That's why I think the help text should explicitely note it has other meaning. You should try to think like a person that does not have any background knowledge of underlying libraries but just looks through the time library trying to solve the question - how can I check if my machine uses daylight savings now. Regards |
On Tue, Jan 11, 2011 at 11:20 AM, Tomas Kubes <report@bugs.python.org> wrote:
I think you are confusing the purposes of a reference manual with that I will keep this issue open, however, in case someone will come up |
There is a fine line between them. Even though reference manual should not be a substitute for a tutorial, I still believe it should try to clarify potential confusions - after all it is the less experienced users who will most likely spend their time with it looking for something. |
It seems to me that the quoted function from bzr def local_time_offset(t=None):
"""Return offset of local zone from GMT, either at present or at time t."""
# python2.3 localtime() can't take None
if t is None:
t = time.time()
if time.localtime(t).tm_isdst and time.daylight:
return -time.altzone
else:
return -time.timezone would be very helpful to add to the |
On Tue, Jan 11, 2011 at 1:56 PM, Georg Brandl report@bugs.python.org wrote:
The problem with this function is the same as with the doc patches
In some ways the state of the docs is reflective of the state of the I agree that the docs can be improved, but I don't see patches that |
On Tue, Jan 11, 2011 at 4:52 PM, Alexander Belopolsky
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
How about making it in iterations and keep the steps as small as
I am sorry Alexander, but I can't really follow up on this issue. It To summarize: What is wrong with my previous proposal if we remove t P.S. Looks like we need a PEP for this. =) |
On Tue, Jan 11, 2011 at 9:42 PM, Alexander Belopolsky
Absurd need to be eliminated, but every time I touch datetime issues I |
On Tue, Jan 11, 2011 at 4:15 PM, anatoly techtonik
Not much is wrong with it. If it would come in a form of a patch and |
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
GitHub fields:
bugs.python.org fields:
The text was updated successfully, but these errors were encountered: