gh-121237: Add %:z directive to strptime #122142

LucasEsposito · 2024-07-22T22:19:05Z

Issue: Support %:z in datetime.datetime.strptime #121237

The directive %:z was introduced in Python 3.12. It works as expected on strftime but fails on strptime, since it was not explicitely implemented there as a new directive.

This PR adds consistency across strftime and strptime (by implementing %:z on the later), while keeping backwards compatibility.

%z and %:z work as expected in strftime, so nothing was changed there.
%z does what it should in strptime (accepting strings formatted according to that directive), while in addition allowing %:z-formatted strings too. The later part of the behavior is a bug but at this point we should keep this behavior for backwards compatibility. I documented the issue in the docs, code and tests.
%:z failed when used in strptime. I implemented %:z directive to parse %:z-formatted strings and added the appropiate tests and changes in the docs.

📚 Documentation preview 📚: https://cpython-previews--122142.org.readthedocs.build/

…pport' folder

rruuaanng · 2024-09-28T03:00:54Z

Misc/NEWS.d/next/Library/2024-07-22-23-18-57.gh-issue-121237.WkbIpy.rst

@@ -0,0 +1 @@
+Accept "%:z" in strptime


When releasing, changes will be added to the changelog. You should describe your changes in detail but keep it concise. For example:

Added %:Z used for XXX to strptime.

(I'm sorry, I don't know what %:z does).

zuo

I like the code :)
What I propose mainly is to correct/supplement certain docs/tests-related details.

zuo · 2024-10-04T18:32:29Z

Doc/library/datetime.rst


 .. versionadded:: 3.12
-   ``%:z`` was added.
+   ``%:z`` was added for :meth:`~.datetime.strftime`


Suggested change

``%:z`` was added for :meth:`~.datetime.strftime`

``%:z`` was added for :meth:`~.datetime.strftime`.

zuo · 2024-10-04T18:32:44Z

Doc/library/datetime.rst

+   ``%:z`` was added for :meth:`~.datetime.strftime`
+
+.. versionadded:: 3.13
+   ``%:z`` was added for :meth:`~.datetime.strptime`


Suggested change

``%:z`` was added for :meth:`~.datetime.strptime`

``%:z`` was added for :meth:`~.datetime.strptime`.

zuo · 2024-10-04T19:15:37Z

Doc/library/datetime.rst

+.. versionadded:: 3.13
+   ``%:z`` was added for :meth:`~.datetime.strptime`
+
+.. warning::


IMHO, this entire warning is unnecessary, because:

There is no need to warn, only to describe certain details (see below). After all, the only inconsistency is that %z is little bit more liberal when it comes to parsing. That's all.

The statement that the behavior is unintended is inaccurate. The behavior is intended and sometimes very useful.

The recommendation to use %z directive only to parse strings formatted according to %z directive, while using %:z directive for strings formatted according to %:z is unnecessary (IMHO). If somebody needs to accept only :-based notation, they will parse their input with %:z. If somebody needs to be more liberal in respect to the input, they will parse their input with %z. Both approaches are perfectly OK, so there is no need to discourage people from anything here.

On the other hand, it is worth to describe certain details – but, IMHO, a better place to do so is the note (6) in the Technical Detail subsection (below). Namely, I propose to:

(1) Replace the following fragment of the %z description:

For example, ``'+01:00:00'`` will be parsed as an offset of one hour. In addition, providing ``'Z'`` is identical to ``'+00:00'``.

with the following text:

For example, both ``'+010000'`` and ``'+01:00:00'`` will be parsed as an offset of one hour. In addition, providing ``'Z'`` is identical to ``'+00:00'``.

(2) Replace the following fragment of the %:z description:

Behaves exactly as ``%z``, but has a colon separator added between hours, minutes and seconds.

with the following text:

When used with :meth:`~.datetime.strftime`, behaves exactly as ``%z``, except that a colon separator is added between hours, minutes and seconds. When used with :meth:`~.datetime.stpftime`, the UTC offset is *required* to have a colon as a separator between hours, minutes and seconds. For example, ``'+01:00:00'`` (but *not* ``'+010000'``) will be parsed as an offset of one hour. In addition, providing ``'Z'`` is identical to ``'+00:00'``.

(3) Do not add this Warning frame at all.

zuo · 2024-10-04T19:17:53Z

Lib/_strptime.py

            #XXX: Does 'Y' need to worry about having less or more than
            #     4 digits?
            'Y': r"(?P<Y>\d\d\d\d)",
+            # "z" shouldn't support colons. Both ":?" should be removed. However, for backwards


Suggested change

# "z" shouldn't support colons. Both ":?" should be removed. However, for backwards

# "z" might not support colons, if designed from scratch. However, for backwards

Again: the statement that it shoudn't support colons is too strong IMHO. It is perfectly OK, that it supports them.

zuo · 2024-10-04T19:30:22Z

Lib/test/test_strptime.py

        self.helper('j', 7)

-    def test_offset(self):
+    def test_z_directive_offset(self):


Not sure if this rename is necessary, considering the surrounding code's method naming convention.

zuo · 2024-10-04T19:33:20Z

Lib/test/test_zipfile/_path/test_path.py

 from ._functools import compose
 from ._itertools import Counter

-from ._test_params import parameterize, Invoked


Cosmetic detail: one more line should be removed here (to leave vertical space of 2 lines, rather than of 3 lines).

zuo · 2024-10-04T19:44:19Z

Misc/NEWS.d/next/Library/2024-07-22-23-18-57.gh-issue-121237.WkbIpy.rst

@@ -0,0 +1 @@
+Accept "%:z" in strptime


I'd propose something along the lines:

Suggested change

Accept "%:z" in strptime

:meth:`~datetime.datetime.strptime` now supports the ``%:z`` format code.

zuo · 2024-10-04T19:49:15Z

Lib/test/test_strptime.py

        self.assertEqual(offset_fraction, -1)
-        (*_, offset), _, offset_fraction = _strptime._strptime("+01:00", "%z")
+
+    @parameterize(


This test LGTM. :)

Yet, it would also be nice to extend (appropriately) relevant tests in Lib/test/datetimetester.py (which regard both implementations of the datetime module) – namely:

TestDateTime:

test_strptime()

TestTime:

test_strptime_tz()

test_strptime_errors()

zuo · 2024-10-04T19:59:03Z

The later part of the behavior is a bug but at this point we should keep this behavior for backwards compatibility. I documented the issue in the docs, code and tests.

I don't think it's a bug. IMHO it's a legitimate part of the module's interface and behavior (even if not to be so useful after merging this PR).

And I agree that this PR brings an improvement. :)

zuo · 2024-10-05T03:58:48Z

Doc/library/datetime.rst

-   ``%:z`` was added.
+   ``%:z`` was added for :meth:`~.datetime.strftime`
+
+.. versionadded:: 3.13


Suggested change

.. versionadded:: 3.13

.. versionadded:: 3.14

StanFromIreland · 2025-03-20T20:37:53Z

What do all the itertools changes have to do with strptime?

StanFromIreland

This has several conflicts and has multiple completely unrelated changes. If you would like to continue with this pr, please tidy it up.

donBarbos · 2025-07-21T10:06:28Z

@LucasEsposito Thank you for PR, but could you please reply if you're going to continue working on it? (it's just been exactly a year since your last activity in current thread)
To clarify that other people can continue working.

LucasEsposito · 2025-07-21T12:19:38Z

@donBarbos

I've been meaning to continue working on this for a while, but it just hasn’t happened.

Given that I’m currently short on time and this seems to be blocking others from contributing, I’ll step back and leave the issue open so that anyone interested can pick it up.

pganssle · 2025-09-19T09:45:09Z

Closing this in favor of #136961, which is now merged! Thanks everyone! 🎉

LucasEsposito requested review from abalkin and pganssle as code owners July 22, 2024 22:19

bedevere-app bot mentioned this pull request Jul 22, 2024

Support %:z in datetime.datetime.strptime #121237

Closed

bedevere-app bot added the awaiting review label Jul 22, 2024

LucasEsposito requested review from jaraco and rhettinger as code owners July 22, 2024 23:08

LucasEsposito added 3 commits July 23, 2024 02:26

pythongh-121237: Add %:z directive to strptime

3ae4449

Fix error message

4a73231

Moved some tests utilities from 'test_zipfile/...' to the general 'su…

43a8c13

…pport' folder

LucasEsposito force-pushed the gh-121237-iso_8601_tz_directive_parsing branch from f6227ad to 43a8c13 Compare July 23, 2024 00:26

rhettinger removed their request for review July 30, 2024 15:23

rruuaanng reviewed Sep 28, 2024

View reviewed changes

zuo suggested changes Oct 4, 2024

View reviewed changes

bedevere-app bot added awaiting core review and removed awaiting review labels Oct 4, 2024

zuo reviewed Oct 5, 2024

View reviewed changes

StanFromIreland requested changes Jun 29, 2025

View reviewed changes

donBarbos added a commit to donBarbos/cpython that referenced this pull request Jul 21, 2025

pythongh-122142: Add %:z directive to strptime

827de60

pganssle closed this Sep 19, 2025

	``%:z`` was added for :meth:`~.datetime.strftime`
	``%:z`` was added for :meth:`~.datetime.strftime`.

	# "z" shouldn't support colons. Both ":?" should be removed. However, for backwards
	# "z" might not support colons, if designed from scratch. However, for backwards

	Accept "%:z" in strptime
	:meth:`~datetime.datetime.strptime` now supports the ``%:z`` format code.

Uh oh!

gh-121237: Add %:z directive to strptime #122142

gh-121237: Add %:z directive to strptime #122142

Uh oh!

Conversation

LucasEsposito commented Jul 22, 2024 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rruuaanng Sep 28, 2024

Choose a reason for hiding this comment

Uh oh!

zuo left a comment

Choose a reason for hiding this comment

Uh oh!

zuo Oct 4, 2024

Choose a reason for hiding this comment

Uh oh!

zuo Oct 4, 2024

Choose a reason for hiding this comment

Uh oh!

zuo Oct 4, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zuo Oct 4, 2024

Choose a reason for hiding this comment

Uh oh!

zuo Oct 4, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zuo Oct 4, 2024

Choose a reason for hiding this comment

Uh oh!

zuo Oct 4, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zuo Oct 4, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zuo commented Oct 4, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

zuo Oct 5, 2024

Choose a reason for hiding this comment

Uh oh!

StanFromIreland commented Mar 20, 2025

Uh oh!

StanFromIreland left a comment

Choose a reason for hiding this comment

Uh oh!

donBarbos commented Jul 21, 2025

Uh oh!

LucasEsposito commented Jul 21, 2025

Uh oh!

pganssle commented Sep 19, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

LucasEsposito commented Jul 22, 2024 •

edited by github-actions bot

Loading

zuo Oct 4, 2024 •

edited

Loading

zuo Oct 4, 2024 •

edited

Loading

zuo Oct 4, 2024 •

edited

Loading

zuo Oct 4, 2024 •

edited

Loading

zuo commented Oct 4, 2024 •

edited

Loading