[issue8810] TZ offset description is unclear in docs
New submission from Alexander Belopolsky belopolsky@users.sourceforge.net:
From http://docs.python.org/dev/py3k/library/datetime.html#datetime.tzinfo.utcoffset:
""" tzinfo.utcoffset(self, dt)
Return offset of local time from UTC, in minutes east of UTC. """
This suggests that the return value is an integer representing the number of minutes. It is later explained that in fact "the value returned must be a timedelta object specifying a whole number of minutes", but many users won't read past the first sentence.
I suggest s/in minutes east of UTC/as a timedelta object/. I think "east of UTC" is redundant given the next sentence, "If local time is west of UTC, this should be negative", but that can also be reworded for clarity as "The offset for timezones west of UTC is negative, and for those east of UTC is positive."
---------- assignee: docs@python components: Documentation keywords: easy messages: 106371 nosy: belopolsky, docs@python priority: normal severity: normal status: open title: TZ offset description is unclear in docs versions: Python 2.7, Python 3.2
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue8810 _______________________________________
Sean Reifschneider jafo@tummy.com added the comment:
In this case, the docs.python.org link you point to seems to be correct, saying that it returns a timedelta. It is the docstring that says it's minutes east of UTC.
I've attached a patch which changes this wording to:
timedelta() showing offset from UTC, with negative for West of UTC
---------- keywords: +patch nosy: +jafo Added file: http://bugs.python.org/file17495/python-utcoffsetdoc.patch
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue8810 _______________________________________
Éric Araujo merwok@netwok.org added the comment:
I’m not sure about the “with negative” wording.
---------- nosy: +merwok
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue8810 _______________________________________
Sean Reifschneider jafo@tummy.com added the comment:
Alternately, here is a patch that just takes the docs.python.org description.
---------- Added file: http://bugs.python.org/file17496/python-utcoffsetdoc2.patch
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue8810 _______________________________________
Sean Reifschneider jafo@tummy.com added the comment:
Then how about:
timedelta() showing offset from UTC, negative values indicating West of UTC
?
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue8810 _______________________________________
Éric Araujo merwok@netwok.org added the comment:
timedelta() showing offset from UTC, negative values indicating West of UTC
+1 for the last one.
Micro nit: I would not put parentheses when referring to the type (we talk about “a list”, not “a list()”).
Micro nit: Some languages use case to distinguish direction vs. region, e.g. in French we have “ouest” and “Ouest”. Does that apply to English?
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue8810 _______________________________________
Sean Reifschneider jafo@tummy.com added the comment:
I'm fine without ().
I thought the direction was generally initial-capped, but I may be wrong there. Let's go with "west".
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue8810 _______________________________________
Sean Reifschneider jafo@tummy.com added the comment:
Committed to 2.7 in 81681 and 3.x in 81682.
---------- keywords: +needs review -patch resolution: -> accepted stage: -> committed/rejected status: open -> closed type: -> feature request
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue8810 _______________________________________
Alexander Belopolsky belopolsky@users.sourceforge.net added the comment:
In this case, the docs.python.org link you point to seems to be correct, saying that it returns a timedelta.
This issue is specifically about ReST documentation, not the docstring. I explained in the opening comment that 'It is later explained that in fact "the value returned must be a timedelta object specifying a whole number of minutes", but many users won't read past the first sentence.' Ironically, you not noticing that reaffirms my proposition that "many users won't read past the first sentence." :-)
Also, the documentation for tzinfo.dst is similarly unclear with ReST text slightly better than docstring.
Finally, please use rNNNNN form for revisions in commit comments. These are converted to hyperlinks by the tracker. For example, your commit comment would become:
Committed to 2.7 in r81681 and 3.x in r81682.
---------- status: closed -> open
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue8810 _______________________________________
Changes by Alexander Belopolsky belopolsky@users.sourceforge.net:
---------- stage: committed/rejected -> needs patch
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue8810 _______________________________________
Changes by Alexander Belopolsky belopolsky@users.sourceforge.net:
---------- resolution: accepted ->
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue8810 _______________________________________
Alexander Belopolsky belopolsky@users.sourceforge.net added the comment:
Sean,
It looks like you committed your first patch rather than your second. Is that what you intended?
Also in msg106734, you agree to change "West" to "west", but committed "West." Note that "west" is correct. In English, the West means the western part of the world while western direction is the west.
Pedantically, the UTC is not a location, so you cannot say "to the west of UTC". Instead, you should say "to the west of the Greenwich Meridian."
Note how RFC 3339 defines the offset:
""" Numeric offsets are calculated as "local time minus UTC". So the equivalent time in UTC can be determined by subtracting the offset from the local time. """
I think this is preferable because there are locations such as Spain to the west of Greenwich which use UTC+1.
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue8810 _______________________________________
Alexander Belopolsky belopolsky@users.sourceforge.net added the comment:
Benjamin,
Is it too late to do anything about this. Apparently Sean committed wrong patch and as a result 2.7 is about to be released with an error in tzinfo.fromutc docstring. This method is confusing enough without documentation bugs. Would you mind if I revert r81681? This is a docstring only change.
---------- nosy: +benjamin.peterson
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue8810 _______________________________________
Alexander Belopolsky belopolsky@users.sourceforge.net added the comment:
Reverted r81681 and r81682 in r82466 and r82467.
It looks like docstring changes intended for utcoffset() landed in a docstring for fromutc(). Given that we are very close to 2.7 release, I am not attempting to improve the docs - just reverting an obvious error.
---------- assignee: docs@python -> belopolsky versions: -Python 2.7
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue8810 _______________________________________
Ben Finney added the comment:
Here is an updated patch. I examined the implementation in the code for UTC offset and DST handling, and updated the code comments, the docstrings, and the library documentation.
---------- keywords: +patch nosy: +bignose, ncoghlan Added file: http://bugs.python.org/file26908/issue8810_reconcile_docs.patch
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue8810 _______________________________________
Nick Coghlan added the comment:
It turns out these particular docstrings are duplicated all over the place, as time and datetime both wrap the tzinfo method, and there is both the tzinfo ABC as well as the concrete fixed offset subclasses, and this happens in both C and Python.
Ben's patch currently only covers the docstrings for the Python tzinfo ABC implementation
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue8810 _______________________________________
Ben Finney added the comment:
Attached is a patch which is more comprehensive (covering the additional locations pointed out to me by ncoghlan), and also consolidating the details into the library documentation so they're not verbosely repeated in so many places.
I agree with Nick's position that the docstrings are not the place to go into great detail about the significance and background of the issues. So the docstrings in this patch are accurate, but terse; the details are in the library documentation.
---------- Added file: http://bugs.python.org/file26911/issue8810_reconcile_docs.patch
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue8810 _______________________________________
Alexander Belopolsky added the comment:
Isn't this a duplicate of #9305?
---------- assignee: belopolsky -> versions: +Python 3.5 -Python 3.2
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue8810 _______________________________________
Changes by Martin Panter vadmium+py@gmail.com:
---------- stage: needs patch -> patch review
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue8810 _______________________________________
Nick Coghlan added the comment:
I agree it makes sense to merge this and #9305, and since the latter has seen more recent activity, I'll do the merge in that direction.
---------- resolution: -> duplicate stage: patch review -> status: open -> closed superseder: -> Don't use east/west of UTC in date/time documentation
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue8810 _______________________________________
participants (6)
-
Alexander Belopolsky -
Ben Finney
-
Martin Panter
-
Nick Coghlan
-
Sean Reifschneider
-
Éric Araujo