classification
Title: Don't use east/west of UTC in date/time documentation
Type: enhancement Stage: patch review
Components: Documentation Versions: Python 3.2
process
Status: open Resolution:
Dependencies: 7229 8810 Superseder:
Assigned To: Nosy List: Rodolpho.Eckhardt, belopolsky, csabella, docs@python, fdrake, henriquebastos, martin.panter, rbp, techtonik, tim.peters
Priority: normal Keywords: easy, patch

Created on 2010-07-19 16:21 by belopolsky, last changed 2017-10-24 18:38 by csabella.

Files
File name Uploaded Description Edit
datetime_doc_remove_east_west.diff henriquebastos, 2010-11-20 19:11 review
datetime_doc_remove_east_west_2.diff rbp, 2010-11-20 20:46 review
Messages (21)
msg110774 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2010-07-19 16:21
I am opening this to supersede issue7229.  See discussion following msg107148.

In many places offsets representing the difference between local time and UTC are described as minutes or seconds east or west of UTC.   This is not correct because UTC is not a place and minutes and seconds don't measure distance in this context.  Replacing UTC with the Prime Meridian will not fix that because some regions in the western hemisphere use positive offsets from UTC.  or example, Madrid is at 3° 42' West, but uses Central European Time which is UTC+1.

I believe geographical references in the python documentation are irrelevant.  What users are interested in is how to convert local time to UTC and UTC to local time rather than what is the sign of time.timezone in Madrid.

I suggest the following wording for time.timezone description:

time.timezone: The number of seconds one must add to the local time to arrive at UTC.

Similarly, tzinfo.utcoffset() can be defined as "Returns timedelta one must add to UTC to arrive at local time."
msg110905 - (view) Author: anatoly techtonik (techtonik) Date: 2010-07-20 14:46
On Mon, Jul 19, 2010 at 7:21 PM, Alexander Belopolsky
<report@bugs.python.org> wrote:
>
> I suggest the following wording for time.timezone description:
>
> time.timezone: The number of seconds one must add to the local time to arrive at UTC.

Makes sense. I can't see any other real explanation for -7200 value if
I am in +2 UTC timezone.

> Similarly, tzinfo.utcoffset() can be defined as "Returns timedelta one must add to UTC to arrive at local time."

I believe the correct convention is "Return timedelta...". Another
concern - if UTC is 0 reference point then there is no reason to add
something to it - you just can say - "Return timedelta equal to local
UTC offset."
msg110910 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2010-07-20 15:29
On Tue, Jul 20, 2010 at 10:46 AM, anatoly techtonik
<report@bugs.python.org> wrote:
> .. Another
> concern - if UTC is 0 reference point then there is no reason to add
> something to it - you just can say - "Return timedelta equal to local
> UTC offset."

No, UTC is not a 0 reference point, it is a time scale.  UTC offset is
the value that is used to translate between time expressed in UTC and
local time.   To make an analogy, expressing time in UTC is like
expressing temperature in Kelvin scale.  You need to subtract 273 from
the value in ºK to arrive at the value in ºC.

Documenting utcoffset() as "Return timedelta equal to local UTC
offset." is almost circular.  It does not explain whether it has to be
added or subtracted from UTC to arrive at local time.
msg110911 - (view) Author: Tim Peters (tim.peters) * (Python committer) Date: 2010-07-20 15:39
FYI, I like the change.  As I recall it, the current wording was just to avoid saying "ahead of UTC" or "behind UTC" (which was the original wording).  Technically pure or not, I never saw anyone get truly confused by "East of UTC" or "West of UTC", but I fully that what people really want to know is what to do with the thing (add or subtract it).
msg110912 - (view) Author: Fred L. Drake, Jr. (fdrake) (Python committer) Date: 2010-07-20 15:47
On Tue, Jul 20, 2010 at 10:46 AM, anatoly techtonik <techtonik@gmail.com> wrote:
> I believe the correct convention is "Return timedelta...".

This is handled inconsistently in the documentation; I'm hoping the
current maintainers reinforce the "Returns ..." structure.  The
documentation is descriptive, not an external specification.

  -Fred
msg110916 - (view) Author: anatoly techtonik (techtonik) Date: 2010-07-20 16:08
> Documenting utcoffset() as "Return timedelta equal to local UTC
> offset." is almost circular.  It does not explain whether it has to be
> added or subtracted from UTC to arrive at local time.

Ok. Sold.

>> I believe the correct convention is "Return timedelta...".
>
> This is handled inconsistently in the documentation; I'm hoping the
> current maintainers reinforce the "Returns ..." structure.  The
> documentation is descriptive, not an external specification.

http://www.python.org/dev/peps/pep-0257/#one-line-docstrings

I've took the convention from here. I thought docs are generated from
docstrings.
msg110917 - (view) Author: Fred L. Drake, Jr. (fdrake) (Python committer) Date: 2010-07-20 16:13
On Tue, Jul 20, 2010 at 12:08 PM, anatoly techtonik
<report@bugs.python.org> wrote:
> I've took the convention from here. I thought docs are generated from
> docstrings.

They're not, but I don't think that really matters.

Older documentation used the imperative form consistently, but that's
shifted over time.  (I, at least, think that's a good thing.)

I don't think it really matters with regard to this issue.
msg110918 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2010-07-20 16:14
On Tue, Jul 20, 2010 at 11:39 AM, Tim Peters <report@bugs.python.org> wrote:
>..  As I recall it, the current wording was just to avoid saying "ahead of UTC" or "behind UTC" (which was the original wording).

Interesting.  I actually like the original wording better.  For me,
"my watch is 6 hours behind UTC" makes it clear that when the Big Ben
clock shows tea time (18:00), my watch displays noon (17:00 - 6:00 =
12:00.)

I wonder if east/west is somehow more natural for native speakers of
English.   I would really like to hear more from the international
audience.  When it comes to measuring time there are many interesting
traditions that don't translate well between nations.  For example,
I've heard that in the Far East, the future is considered to be behind
because you can see the past but you cannot see the future.  If this
is the notion that you are used to, time being ahead or behind can be
truly confusing.
msg110919 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2010-07-20 16:18
On Tue, Jul 20, 2010 at 12:14 PM, Alexander Belopolsky
<report@bugs.python.org> wrote:
..
> Interesting.  I actually like the original wording better.  For me,
> "my watch is 6 hours behind UTC" makes it clear that when the Big Ben
> clock shows tea time (18:00), my watch displays noon (17:00 - 6:00 =
> 12:00.)

I was too excited to add Alice in Wonderland humor to my post that did
not get the math right. :-)

The above should read 18:00 - 6:00 = 12:00, of course.  Or was it five
o'clock after all?
msg110926 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2010-07-20 17:19
On Tue, Jul 20, 2010 at 12:08 PM, anatoly techtonik
<report@bugs.python.org> wrote:
..
> Ok. Sold.

Good.  All we need now is just a patch. :-)
msg121726 - (view) Author: Henrique Bastos (henriquebastos) Date: 2010-11-20 19:10
Here goes a patch to replace east/west references on datetime documentation.

As spoken with fdrake we think the datetime documentation could be improved extracting the timezone subclassing details to specific section. We'll be filling a new issue for that patch.
msg121727 - (view) Author: Henrique Bastos (henriquebastos) Date: 2010-11-20 19:11
Here goes a patch to replace east/west references on datetime documentation.

As spoken with fdrake we think the datetime documentation could be improved extracting the timezone subclassing details to specific section. We'll be filling a new issue for that patch.
msg121728 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2010-11-20 19:18
LGTM
msg121745 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2010-11-20 19:56
On the second reading, I have a few issues with the patch.

1. Please run makepatcheck.  There are whitespace issues in datetime.rst.
2. In docstrings, you remove the information about the sign.  I would not mind leaving docstrings the way they are.  Otherwise, please add a short sentence explaining the sign of utcoffset and dst.
3. "This represents the offset in minutes that must be added to the local time zone to follow DST rules."   This unclear.  DST offset is added to the "standard time", not "local time zone".  (I am not sure if "standard time" is defined in the manual, though.)  Also, "in minutes" is not necessary - timedelta carries the units. You can add that only offsets that are multiples of a minute are supported.
msg121751 - (view) Author: Henrique Bastos (henriquebastos) Date: 2010-11-20 20:12
To clarify:

1) "we" means henriquebastos, rbp, Rodolpho.Eckhardt.

2) Mentioning fdrake I was trying to say that we followed his suggestion to only submit the specific changes on this patch, leaving further documentation changes to another issue.

Sorry about any inconvenience.
msg121765 - (view) Author: Rodrigo Bernardo Pimentel (rbp) (Python committer) Date: 2010-11-20 20:46
1. Done (it's on the patch I'm uploading). Sorry.

3. Ok, we've rewritten that sentence. As Henrique mentioned, we're working on a larger patch to make datetime documentation clearer, and we can include a definition of "standard time" there.


2. I assume you're talking about sentences like "(negative for west of UTC)". We removed that wording because it inevitably leads to associating UTC with a geographical reference. Even if we disregard that, it's not true that "utcoffset is negative west of UTC", since it will we zero for for UTC-1 (and even +1 for places physically "west of UTC" but at timezone UTC+0) when DST is effective.

It seems that any sentence we add to that effect will be simply restating the definitions of UTC, timezones and DST (and their mathematical relationships). That is, "utcoffset will be negative when dt.tzinfo + dst() is negative".

Perhaps we could include a more detailed discusion about the sign of utcoffset() on the larger doc patch I've mentioned? Or do you have any suggestions?
msg126020 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2011-01-11 16:26
I've noticed that the time module docstring handles this issue rather nicely:

>>> help('time')
...
    timezone -- difference in seconds between UTC and local standard time
    altzone -- difference in  seconds between UTC and local DST time

We can use similar language for utcoffset(): "difference between local time and UTC expressed as a timedelta".
msg185565 - (view) Author: Mark Lawrence (BreamoreBoy) * Date: 2013-03-30 15:16
Well, we have a patch and it's been discussed here and on #7229, so can we take this forward?
msg221916 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2014-06-29 23:28
This seems to be touching the same areas as #9305.
msg257935 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2016-01-10 20:33
Assuming you meant Issue 8810, yes these patches would collide with each other. I am yet to look at the patches, but I gess they should be merged.
msg304934 - (view) Author: Cheryl Sabella (csabella) * Date: 2017-10-24 18:38
Would one of the original authors of the patches like to create a GitHub pull request for this issue?
History
Date User Action Args
2017-10-24 18:38:20csabellasetnosy: + csabella
messages: + msg304934
2016-02-08 04:36:40ncoghlanlinkissue8810 superseder
2016-01-10 20:33:05martin.pantersetnosy: + martin.panter
dependencies: + TZ offset description is unclear in docs, - Don't use east/west of UTC in date/time documentation
messages: + msg257935
2016-01-10 20:33:05martin.panterunlinkissue9305 dependencies
2014-06-29 23:28:03belopolskysetassignee: belopolsky ->
messages: + msg221916
2014-06-29 23:26:34belopolskysetdependencies: + Don't use east/west of UTC in date/time documentation
2014-06-29 23:26:34belopolskylinkissue9305 dependencies
2014-02-03 18:37:43BreamoreBoysetnosy: - BreamoreBoy
2013-03-30 15:16:52BreamoreBoysetnosy: + BreamoreBoy
messages: + msg185565
2011-01-11 16:26:27belopolskysetnosy: tim.peters, fdrake, belopolsky, techtonik, rbp, docs@python, henriquebastos, Rodolpho.Eckhardt
messages: + msg126020
2010-11-20 20:46:25rbpsetfiles: + datetime_doc_remove_east_west_2.diff

messages: + msg121765
2010-11-20 20:12:31henriquebastossetmessages: + msg121751
2010-11-20 19:56:10belopolskysetmessages: + msg121745
stage: commit review -> patch review
2010-11-20 19:26:02belopolskysetassignee: docs@python -> belopolsky
stage: needs patch -> commit review
2010-11-20 19:18:25belopolskysetmessages: + msg121728
2010-11-20 19:11:14henriquebastossetfiles: + datetime_doc_remove_east_west.diff
keywords: + patch
messages: + msg121727
2010-11-20 19:10:54henriquebastossetnosy: + henriquebastos, Rodolpho.Eckhardt
messages: + msg121726
2010-11-20 17:35:37rbpsetnosy: + rbp
2010-07-20 17:19:50belopolskysetmessages: + msg110926
2010-07-20 16:18:31belopolskysetmessages: + msg110919
2010-07-20 16:14:38belopolskysetmessages: + msg110918
2010-07-20 16:13:19fdrakesetmessages: + msg110917
2010-07-20 16:08:06techtoniksetmessages: + msg110916
2010-07-20 15:47:14fdrakesetnosy: + fdrake
messages: + msg110912
2010-07-20 15:39:36tim.peterssetnosy: + tim.peters
messages: + msg110911
2010-07-20 15:29:05belopolskysetmessages: + msg110910
2010-07-20 14:46:12techtoniksetnosy: + techtonik
messages: + msg110905
2010-07-19 16:42:17belopolskylinkissue7229 superseder
2010-07-19 16:42:05belopolskysetdependencies: + Manual entry for time.daylight can be misleading
2010-07-19 16:21:43belopolskycreate