classification
Title: TZ offset description is unclear in docs
Type: enhancement Stage:
Components: Documentation Versions: Python 3.5
process
Status: closed Resolution: duplicate
Dependencies: Superseder: Don't use east/west of UTC in date/time documentation
View: 9305
Assigned To: Nosy List: belopolsky, benjamin.peterson, bignose, docs@python, eric.araujo, jafo, matrixise, ncoghlan
Priority: normal Keywords: easy, needs review, patch

Created on 2010-05-24 16:20 by belopolsky, last changed 2016-02-08 04:36 by ncoghlan. This issue is now closed.

Files
File name Uploaded Description Edit
python-utcoffsetdoc.patch jafo, 2010-05-29 18:56 Patch with suggested wording.
python-utcoffsetdoc2.patch jafo, 2010-05-29 19:36 Patch with description from docs.python.org.
issue8810_reconcile_docs.patch bignose, 2012-08-20 03:15 patch against current HEAD for code comments, docstrings, and documentation review
issue8810_reconcile_docs.patch bignose, 2012-08-20 06:44 patch against current HEAD for code comments, docstrings, and documentation review
Messages (18)
msg106371 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2010-05-24 16:20
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."
msg106728 - (view) Author: Sean Reifschneider (jafo) * (Python committer) Date: 2010-05-29 18:56
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
msg106729 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-05-29 19:09
I’m not sure about the “with negative” wording.
msg106730 - (view) Author: Sean Reifschneider (jafo) * (Python committer) Date: 2010-05-29 19:36
Alternately, here is a patch that just takes the docs.python.org description.
msg106731 - (view) Author: Sean Reifschneider (jafo) * (Python committer) Date: 2010-05-29 19:37
Then how about:

timedelta() showing offset from UTC, negative values indicating West of UTC

?
msg106732 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-05-29 19:43
> 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?
msg106734 - (view) Author: Sean Reifschneider (jafo) * (Python committer) Date: 2010-05-29 19:59
I'm fine without ().

I thought the direction was generally initial-capped, but I may be wrong there.  Let's go with "west".
msg107001 - (view) Author: Sean Reifschneider (jafo) * (Python committer) Date: 2010-06-04 01:54
Committed to 2.7 in 81681 and 3.x in 81682.
msg107002 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2010-06-04 03:31
> 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.
msg107003 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2010-06-04 04:02
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.
msg109156 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2010-07-03 02:21
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.
msg109157 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2010-07-03 03:39
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.
msg168615 - (view) Author: Ben Finney (bignose) Date: 2012-08-20 03:15
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.
msg168620 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2012-08-20 04:44
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
msg168623 - (view) Author: Ben Finney (bignose) Date: 2012-08-20 06:44
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.
msg221915 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2014-06-29 23:23
Isn't this a duplicate of #9305?
msg257936 - (view) Author: Stéphane Wirtel (matrixise) * (Python triager) Date: 2016-01-10 20:35
Hi Martin,

Which patch?

Thanks
-- 
Stéphane Wirtel - http://wirtel.be - @matrixise
msg259815 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2016-02-08 04:36
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.
History
Date User Action Args
2016-02-08 04:36:40ncoghlansetstatus: open -> closed
superseder: Don't use east/west of UTC in date/time documentation
messages: + msg259815

resolution: duplicate
stage: patch review ->
2016-01-10 20:35:58matrixisesetnosy: + matrixise
messages: + msg257936
2016-01-10 20:33:05martin.panterlinkissue9305 dependencies
2016-01-10 20:32:54martin.pantersetstage: needs patch -> patch review
2014-06-29 23:23:39belopolskysetassignee: belopolsky ->
messages: + msg221915
versions: + Python 3.5, - Python 3.2
2012-08-20 06:44:14bignosesetfiles: + issue8810_reconcile_docs.patch

messages: + msg168623
2012-08-20 04:44:35ncoghlansetmessages: + msg168620
2012-08-20 03:15:20bignosesetfiles: + issue8810_reconcile_docs.patch

nosy: + ncoghlan, bignose
messages: + msg168615

keywords: + patch
2010-07-03 03:39:15belopolskysetassignee: docs@python -> belopolsky
messages: + msg109157
versions: - Python 2.7
2010-07-03 02:21:52belopolskysetnosy: + benjamin.peterson
messages: + msg109156
2010-06-04 04:02:27belopolskysetmessages: + msg107003
2010-06-04 03:32:15belopolskysetresolution: accepted -> (no value)
2010-06-04 03:31:45belopolskysetstage: resolved -> needs patch
2010-06-04 03:31:21belopolskysetstatus: closed -> open

messages: + msg107002
2010-06-04 01:54:53jafosetstatus: open -> closed
type: enhancement
messages: + msg107001

keywords: + needs review, - patch
resolution: accepted
stage: resolved
2010-05-29 19:59:59jafosetmessages: + msg106734
2010-05-29 19:43:34eric.araujosetmessages: + msg106732
2010-05-29 19:37:54jafosetmessages: + msg106731
2010-05-29 19:36:27jafosetfiles: + python-utcoffsetdoc2.patch

messages: + msg106730
2010-05-29 19:09:35eric.araujosetnosy: + eric.araujo
messages: + msg106729
2010-05-29 18:56:54jafosetfiles: + python-utcoffsetdoc.patch

nosy: + jafo
messages: + msg106728

keywords: + patch
2010-05-24 16:20:18belopolskycreate