[docs] TZ offset description is unclear in docs (issue 8810)

alexander.belopolsky at gmail.com alexander.belopolsky at gmail.com
Mon Sep 10 06:05:23 CEST 2012

File Doc/library/datetime.rst (right):

Doc/library/datetime.rst:1011: west from UTC.
On 2012/09/10 03:24:15, bignose wrote:
> You're right that UTC is not a geographical location. It is a region
in the
> abstract one-dimensional circular space of time zones, and other time
zones are
> east or west from that region in the space of time zones.

This is a novel interpretation, but in this sense that sentence is as
useful as saying that integers left of zero are negative and those right
of zero are positive.  Yes, in some sense the statement is correct, but
is not really helpful.

In datetime module documentation the East/West terminology is
unnecessary.  People don't read Python reference manual to figure out
whether they live in the East or in the West.  What they want to know is
what datetime.utcoffset means and it means timedelta that needs to be
added to (naive) UTC time to arrive at (naive) local time.  They also
want to know that the sign of utcoffset() is opposite to the sign of
time.timezone.  However, saying that time.timezone is positive west of
UTC and datetime.utcoffset() is negative west of UTC hides this simple
fact behind additional terminology.  (By the time one reads about
utcoffset() she already forgot what was East/West for time.timezone and
does not realize that the convention is opposite.)


More information about the docs mailing list