Don't use east/west of UTC in date/time documentation

[abalkin]

BPO	9305
Nosy	@tim-one, @freddrake, @abalkin, @vadmium, @crwilcox, @pganssle, @csabella, @ravipudi, @slateny
PRs	bpo-9305: Remove east/west references from datetime #31697
Dependencies	bpo-7229: Manual entry for time.daylight can be misleading bpo-8810: TZ offset description is unclear in docs
Files	datetime_doc_remove_east_west.diff datetime_doc_remove_east_west_2.diff

^{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:

assignee = None
closed_at = None
created_at = <Date 2010-07-19.16:21:43.892>
labels = ['easy', 'type-feature', 'docs']
title = "Don't use east/west of UTC in date/time documentation"
updated_at = <Date 2022-03-05.16:55:35.124>
user = 'https://github.com/abalkin'

bugs.python.org fields:

activity = <Date 2022-03-05.16:55:35.124>
actor = 'slateny'
assignee = 'none'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2010-07-19.16:21:43.892>
creator = 'belopolsky'
dependencies = ['7229', '8810']
files = ['19694', '19709']
hgrepos = []
issue_num = 9305
keywords = ['patch', 'easy']
message_count = 24.0
messages = ['110774', '110905', '110910', '110911', '110912', '110916', '110917', '110918', '110919', '110926', '121726', '121727', '121728', '121745', '121751', '121765', '126020', '185565', '221916', '257935', '304934', '332985', '333045', '361715']
nosy_count = 15.0
nosy_names = ['tim.peters', 'fdrake', 'belopolsky', 'techtonik', 'rbp', 'docs@python', 'henriquebastos', 'Rodolpho.Eckhardt', 'martin.panter', 'crwilcox', 'p-ganssle', 'cheryl.sabella', 'Ajay Mahato', 'ravipudi', 'slateny']
pr_nums = ['31697']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue9305'
versions = ['Python 3.2']

[abalkin]

I am opening this to supersede bpo-7229. 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."

[techtonik]

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."

[abalkin]

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.

[tim-one]

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).

[freddrake]

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

[techtonik]

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.

[freddrake]

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.

[abalkin]

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.

[abalkin]

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?

[abalkin]

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. :-)

[henriquebastos]

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.