classification
Title: Misleading class names in datetime.tzinfo usage examples
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.8, Python 3.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Robert.Tasarz, belopolsky, docs@python, mariocj89, miss-islington, vstinner
Priority: normal Keywords: patch

Created on 2017-06-18 22:15 by Robert.Tasarz, last changed 2019-06-04 15:29 by vstinner. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 4290 merged mariocj89, 2017-11-05 19:57
PR 13811 merged miss-islington, 2019-06-04 15:18
Messages (4)
msg296296 - (view) Author: Robert Tasarz (Robert.Tasarz) Date: 2017-06-18 22:15
https://docs.python.org/3/library/datetime.html#datetime-objects
gives in an example two classes named GMT1 and GMT2 subclassing tzinfo, defined with dst(…) methods returning one hour timedelta for summer periods. This is in conflict with naming, as GMT timezone is not defined with any daylight saving time, so any timezone offsetted from it shouldn't be as well. I would suggest renaming them to something like BrusselsTZ and HelsinkiTZ (with a comment that this is simplified implementation, that doesn't account for exact hour when dst switch is made, and maybe mentioning pytz) and tzname(…) to return ('CET', 'CEST')[bool(self.dst(dt))] and ('EET', 'EEST')[bool(self.dst(dt))] accordingly.

Also https://docs.python.org/3/library/datetime.html#time-objects
has an example with GMT1 class, though this time dst(…) unconditionally returns offset 0 properly, tzname(…) gives 'Europe/Prague' – region that uses dst. IMHO returning any of: "CET", "GMT+1", "Africa/Tunis" would be better here.
msg344592 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2019-06-04 15:18
New changeset f0b5ae4567637b24035ecda93a3240efc96b6dd9 by Victor Stinner (Mario Corchero) in branch 'master':
bpo-30699: Improve example on datetime tzinfo instances (GH-4290)
https://github.com/python/cpython/commit/f0b5ae4567637b24035ecda93a3240efc96b6dd9
msg344593 - (view) Author: miss-islington (miss-islington) Date: 2019-06-04 15:25
New changeset 12c178799a23b47c5f8ebc072cbdf09a370649ae by Miss Islington (bot) in branch '3.7':
bpo-30699: Improve example on datetime tzinfo instances (GH-4290)
https://github.com/python/cpython/commit/12c178799a23b47c5f8ebc072cbdf09a370649ae
msg344594 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2019-06-04 15:29
Thanks Mario Corchero for the doc enhancement, and Paul for the review!

Python 2.7 is not affected: datetime has no timeinfo class.
History
Date User Action Args
2019-06-04 15:29:34vstinnersetstatus: open -> closed
versions: + Python 3.7, Python 3.8, - Python 2.7, Python 3.6
messages: + msg344594

resolution: fixed
stage: patch review -> resolved
2019-06-04 15:25:20miss-islingtonsetnosy: + miss-islington
messages: + msg344593
2019-06-04 15:18:37miss-islingtonsetpull_requests: + pull_request13697
2019-06-04 15:18:17vstinnersetnosy: + vstinner
messages: + msg344592
2017-11-06 13:47:34berker.peksagsetnosy: + belopolsky
2017-11-05 19:58:56mariocj89setnosy: + mariocj89
2017-11-05 19:57:17mariocj89setkeywords: + patch
stage: patch review
pull_requests: + pull_request4253
2017-06-18 22:15:56Robert.Tasarzcreate