classification
Title: datetime documentation typos
Type: Stage: resolved
Components: Documentation Versions: Python 3.2, Python 3.3, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: belopolsky, docs@python, orsenthil, python-dev, steveire, terry.reedy, zacherates
Priority: normal Keywords: patch

Created on 2011-12-26 22:01 by steveire, last changed 2012-06-26 12:07 by orsenthil. This issue is now closed.

Files
File name Uploaded Description Edit
issue13666.diff zacherates, 2012-01-07 16:57 review
Messages (8)
msg150272 - (view) Author: Stephen Kelly (steveire) Date: 2011-12-26 22:01
There are several bugs on 

http://docs.python.org/library/datetime.html

Section 8.1.6 references the method rzinfo.dst(), which does not exist. Presumably this should be tzinfo.dst().

Section 8.1.4 contains an implementation of a GMT2 timezone. There seems to be a bug in the utcoffset() and dst() implementations. The timedelta(hours=2) is in the dst() implementation, but it should be in the uctoffset() implementation. 

The docs for tzinfo.utcoffset() start with 'Return offset of local time from UTC, in minutes east of UTC'. Other methods (eg dst()) also document that the unit to return should be 'minutes'. However, all code samples instead return a timedelta. The documentation I quoted should instead read 'Return offset of local time from UTC as a timedelta, or None'.
msg150395 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-12-30 21:29
2.6 only gets security updates.

I verified 'rzinfo' typo in x.1.6 in 2.7 and 3.2. Also in both, tzinfo.utcoffset begins as Stephen claims. I have not verified that this is error.

 Also in both, in x.1.4, class GMT1 has
...     def utcoffset(self, dt):
...         return timedelta(hours=1) + self.dst(dt)
...     def dst(self, dt):
...         if self.dston <=  dt.replace(tzinfo=None) < self.dstoff:
...             return timedelta(hours=1)
...         else:
...             return timedelta(0)

while GMT2 has
...     def utcoffset(self, dt):
...         return timedelta(hours=1) + self.dst(dt)
...     def dst(self, dt):
...         if self.dston <=  dt.replace(tzinfo=None) < self.dstoff:
...             return timedelta(hours=2)
...         else:
...             return timedelta(0)

Stephen is saying that 'hours=1' should here be 'hours=2'. Should '0' by 'hours=1' to be just 1 off from 2?
msg150806 - (view) Author: Aaron Maenpaa (zacherates) Date: 2012-01-07 16:57
This patch fixes the rzinfo typo as well as the GMT2 issue (GMT +2 should behave exactly the same as GMT +1 with regards to DST, it's base offset should simply be +2 hours instead of +1).

This does not; however, address the comment about the first line of the tzinfo.utcoffset(). The fact that tzinfo.utcoffset() should return a timedelta or None is addressed later in the same paragraph, as such I'm not sure the proposed change is an improvement.
msg150807 - (view) Author: Aaron Maenpaa (zacherates) Date: 2012-01-07 17:15
Looks like the issue of the first line of utcoffsect was also raised in issue 8810.
msg150808 - (view) Author: Stephen Kelly (steveire) Date: 2012-01-07 17:26
Patch looks good to me.
msg152038 - (view) Author: Stephen Kelly (steveire) Date: 2012-01-26 22:17
There are actually other bugs in the same code example:

...     def __init__(self):         # DST starts last Sunday in March
...         d = datetime(dt.year, 4, 1)   # ends last Sunday in October
...         self.dston = d - timedelta(days=d.weekday() + 1)
...         d = datetime(dt.year, 11, 1)
...         self.dstoff = d - timedelta(days=d.weekday() + 1)

where does dt come from? this fragment should be in the implementation of dst (in both the GMT1 and GMT2 classes.
msg164067 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-06-26 12:05
New changeset ec970793f390 by Senthil Kumaran in branch '3.2':
issue13666 - Fixing datetime documentation example when using tzinfo
http://hg.python.org/cpython/rev/ec970793f390

New changeset 98d40bd23381 by Senthil Kumaran in branch 'default':
issue13666 - merge from 3.2
http://hg.python.org/cpython/rev/98d40bd23381

New changeset 01d180987d90 by Senthil Kumaran in branch '2.7':
issue13666 - Fixing datetime documentation example when using tzinfo
http://hg.python.org/cpython/rev/01d180987d90
msg164068 - (view) Author: Senthil Kumaran (orsenthil) * (Python committer) Date: 2012-06-26 12:07
The docs are fixed now.
History
Date User Action Args
2012-06-26 12:07:47orsenthilsetstatus: open -> closed

nosy: + orsenthil
messages: + msg164068

resolution: fixed
stage: needs patch -> resolved
2012-06-26 12:05:33python-devsetnosy: + python-dev
messages: + msg164067
2012-01-26 22:17:28steveiresetmessages: + msg152038
2012-01-07 17:26:39steveiresetmessages: + msg150808
2012-01-07 17:15:08zacheratessetmessages: + msg150807
2012-01-07 16:57:50zacheratessetfiles: + issue13666.diff

nosy: + zacherates
messages: + msg150806

keywords: + patch
2011-12-30 21:29:23terry.reedysetversions: + Python 2.7, Python 3.2, Python 3.3, - Python 2.6
nosy: + terry.reedy, belopolsky

messages: + msg150395

stage: needs patch
2011-12-26 22:01:53steveirecreate