classification
Title: [doc] %z directive has no effect on the output of time.strptime
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.11
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: brett.cannon, docs@python, hugovk, iritkatriel, martin.panter, miss-islington, r.david.murray
Priority: normal Keywords: patch

Created on 2017-04-02 20:19 by Paul Pinterits, last changed 2022-01-15 09:26 by iritkatriel. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 30354 merged hugovk, 2022-01-03 11:32
PR 30608 merged miss-islington, 2022-01-14 22:49
PR 30609 merged miss-islington, 2022-01-14 22:49
Messages (12)
msg291041 - (view) Author: Paul Pinterits (Paul Pinterits) Date: 2017-04-02 20:19
%z is listed as a supported directive in the python 3 documentation (https://docs.python.org/3.5/library/time.html#time.strftime), but it doesn't actually do anything:

>>> from time import strptime
>>> strptime('+0000', '%z') == strptime('+0200', '%z')
True

As far as I can tell, there aren't any footnotes saying that %z might not be supported on some platforms, like it was back in python 2.

In case it matters, I'm using python 3.5.3 on linux.
msg291042 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2017-04-02 20:57
Are you sure? It works for me:

>>> strptime("+0200", "%z").tm_gmtoff
7200
>>> strptime("+0000", "%z").tm_gmtoff
0

The "struct_time" class is documented as a named tuple, but the time zone offset is not one of the tuple elements, so isn’t going to be checked for equality.
msg291043 - (view) Author: Paul Pinterits (Paul Pinterits) Date: 2017-04-02 21:42
I see. You're right, it does make a difference.

However, this behaviour is quite unexpected. Perhaps I just didn't read the docs carefully enough, but it wasn't clear to me that the time module had such half-baked support for time zones.

An unsuspecting user, like me, reads the documentation on strptime, which directs you to strftime. There you read that %z is a supported directive. Along the way you've come across the conversion table, which tells you that mktime() can convert struct_time objects to timestamps. But then when you try to parse a time string, the information gets lost somewhere along the way:

>>> mktime(strptime("+0000", "%z")) == mktime(strptime("+0200", "%z"))
True

If you visit the section about struct_time objects, you find this footnote:
"Changed in version 3.3: tm_gmtoff and tm_zone attributes are available on platforms with C library supporting the corresponding fields in struct tm."

But even after reading that, I'd still expect the tm_gmtoff attribute to have some sort of effect and not get silently discarded.
msg291044 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2017-04-02 22:32
As far as I can see, the documentation only claims that “mktime” converts local time. If you saw a suggestion that it supports arbitrary time zones, please point it out.
msg291045 - (view) Author: Paul Pinterits (Paul Pinterits) Date: 2017-04-02 22:53
No no, the docs are correct. This was definitely my mistake. I'm just trying to say that it's rather confusing how there's only partial support for time zones. When I saw that there is support for parsing the time zone offset, I assumed that the functions provided in the time module would be enough to solve my problem - having to rely on the datetime module to have proper time zone support caught me by surprise. It's quite counterintuitive.
msg291046 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2017-04-02 23:45
We could change this to a documentation issue if you have any suggestions to make the documentation clearer.

I understand the “time” module is mainly a wrapper or emulator of the OS’s own strptime, mktime, etc functions, which explains some of these quirks.
msg291086 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2017-04-03 17:49
Yes, that's exactly right.  'time' is a low-level os-function wrapper, and inherits many of the deficiencies of the platform.  datetime attempts to be a more comprehensive, portable solution.  (But even it has its quirks...timezones are *hard*.)
msg291093 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2017-04-03 20:39
There's actually a footnote pointing out that %z is not supported by all libc implementations: https://docs.python.org/3/library/time.html#id2. Probably adding a note for %z in the strftime() table would be good.
msg407368 - (view) Author: Irit Katriel (iritkatriel) * (Python committer) Date: 2021-11-30 12:06
See also Issue20281.
msg410605 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2022-01-14 22:49
New changeset 305588c67cdede4ef127ada90c1557bc1ef7c200 by Hugo van Kemenade in branch 'main':
bpo-20281, bpo-29964: update datetime docs to refer %z and %Z to a pre-existing footnote (GH-30354)
https://github.com/python/cpython/commit/305588c67cdede4ef127ada90c1557bc1ef7c200
msg410609 - (view) Author: miss-islington (miss-islington) Date: 2022-01-14 23:59
New changeset 93dc1654dc3c925c062e19f0ef8587aa8961ef8a by Miss Islington (bot) in branch '3.10':
bpo-20281, bpo-29964: update datetime docs to refer %z and %Z to a pre-existing footnote (GH-30354)
https://github.com/python/cpython/commit/93dc1654dc3c925c062e19f0ef8587aa8961ef8a
msg410611 - (view) Author: miss-islington (miss-islington) Date: 2022-01-15 00:00
New changeset f869b56fe4be416d356fffc94b8b18fe65039929 by Miss Islington (bot) in branch '3.9':
bpo-20281, bpo-29964: update datetime docs to refer %z and %Z to a pre-existing footnote (GH-30354)
https://github.com/python/cpython/commit/f869b56fe4be416d356fffc94b8b18fe65039929
History
Date User Action Args
2022-01-15 09:26:58iritkatrielsetstatus: open -> closed
resolution: works for me -> fixed
stage: patch review -> resolved
2022-01-15 00:00:01miss-islingtonsetmessages: + msg410611
2022-01-14 23:59:35miss-islingtonsetmessages: + msg410609
2022-01-14 22:58:53Paul Pinteritssetnosy: - Paul Pinterits
2022-01-14 22:49:28miss-islingtonsetpull_requests: + pull_request28811
2022-01-14 22:49:23brett.cannonsetmessages: + msg410605
2022-01-14 22:49:22miss-islingtonsetnosy: + miss-islington
pull_requests: + pull_request28809
2022-01-03 11:32:08hugovksetkeywords: + patch
nosy: + hugovk

pull_requests: + pull_request28568
stage: test needed -> patch review
2021-11-30 12:06:08iritkatrielsetassignee: docs@python
type: behavior -> enhancement

components: + Documentation, - Library (Lib)
title: %z directive has no effect on the output of time.strptime -> [doc] %z directive has no effect on the output of time.strptime
nosy: + iritkatriel, docs@python
versions: + Python 3.11, - Python 3.5
messages: + msg407368
2017-04-03 20:39:03brett.cannonsetnosy: + brett.cannon
messages: + msg291093
2017-04-03 17:49:36r.david.murraysetnosy: + r.david.murray
messages: + msg291086
2017-04-02 23:45:42martin.pantersetmessages: + msg291046
2017-04-02 22:53:05Paul Pinteritssetmessages: + msg291045
2017-04-02 22:32:57martin.pantersetmessages: + msg291044
2017-04-02 21:42:18Paul Pinteritssetmessages: + msg291043
2017-04-02 20:57:06martin.pantersetnosy: + martin.panter
messages: + msg291042

resolution: works for me
stage: test needed
2017-04-02 20:19:38Paul Pinteritscreate