Skip to content

gh-121237: Add %:z directive to datetime.strptime #136961

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 9 commits into from
Sep 19, 2025
Merged

gh-121237: Add %:z directive to datetime.strptime #136961

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
e842519
gh-121237: Add %:z directive to strptime
donBarbos Jul 21, 2025
221ba98
and time.strptime
donBarbos Jul 22, 2025
57098db
Fix method name
donBarbos Jul 22, 2025
ed63eed
Accept suggestions
donBarbos Sep 15, 2025
f499dee
Accept suggestions from @StanFromIreland
donBarbos Sep 15, 2025
75c1bd1
Add to time docs
donBarbos Sep 15, 2025
bb92e82
Merge branch 'main' into issue-121237
donBarbos Sep 15, 2025
fa4d19c
Remove from time doc
donBarbos Sep 16, 2025
4bc5181
Apply suggestions
donBarbos Sep 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 14 additions & 5 deletions Doc/library/datetime.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2629,7 +2629,10 @@ differences between platforms in handling of unsupported format specifiers.
``%G``, ``%u`` and ``%V`` were added.

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

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

Technical Detail
^^^^^^^^^^^^^^^^
Expand Down Expand Up @@ -2724,12 +2727,18 @@ Notes:
When the ``%z`` directive is provided to the :meth:`~.datetime.strptime` method,
the UTC offsets can have a colon as a separator between hours, minutes
and seconds.
For example, ``'+01:00:00'`` will be parsed as an offset of one hour.
In addition, providing ``'Z'`` is identical to ``'+00:00'``.
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'``.

``%:z``
Behaves exactly as ``%z``, but has a colon separator added between
hours, minutes and seconds.
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.strptime`, 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'``.

``%Z``
In :meth:`~.datetime.strftime`, ``%Z`` is replaced by an empty string if
Expand Down
16 changes: 9 additions & 7 deletions Lib/_strptime.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -371,7 +371,9 @@ def __init__(self, locale_time=None):
# W is set below by using 'U'
'y': r"(?P<y>\d\d)",
'Y': r"(?P<Y>\d\d\d\d)",
# See gh-121237: "z" must support colons for backwards compatibility.
'z': r"(?P<z>([+-]\d\d:?[0-5]\d(:?[0-5]\d(\.\d{1,6})?)?)|(?-i:Z))?",
':z': r"(?P<colon_z>([+-]\d\d:[0-5]\d(:[0-5]\d(\.\d{1,6})?)?)|(?-i:Z))?",
'A': self.__seqToRE(self.locale_time.f_weekday, 'A'),
'a': self.__seqToRE(self.locale_time.a_weekday, 'a'),
'B': self.__seqToRE(_fixmonths(self.locale_time.f_month[1:]), 'B'),
Expand Down Expand Up @@ -459,16 +461,16 @@ def pattern(self, format):
year_in_format = False
day_of_month_in_format = False
def repl(m):
format_char = m[1]
match format_char:
directive = m.group()[1:] # exclude `%` symbol
match directive:
case 'Y' | 'y' | 'G':
nonlocal year_in_format
year_in_format = True
case 'd':
nonlocal day_of_month_in_format
day_of_month_in_format = True
return self[format_char]
format = re_sub(r'%[-_0^#]*[0-9]*([OE]?\\?.?)', repl, format)
return self[directive]
format = re_sub(r'%[-_0^#]*[0-9]*([OE]?[:\\]?.?)', repl, format)
if day_of_month_in_format and not year_in_format:
import warnings
warnings.warn("""\
Expand Down Expand Up @@ -662,8 +664,8 @@ def parse_int(s):
week_of_year_start = 0
elif group_key == 'V':
iso_week = int(found_dict['V'])
elif group_key == 'z':
z = found_dict['z']
elif group_key in ('z', 'colon_z'):
z = found_dict[group_key]
if z:
if z == 'Z':
gmtoff = 0
Expand All @@ -672,7 +674,7 @@ def parse_int(s):
z = z[:3] + z[4:]
if len(z) > 5:
if z[5] != ':':
msg = f"Inconsistent use of : in {found_dict['z']}"
msg = f"Inconsistent use of : in {found_dict[group_key]}"
raise ValueError(msg)
z = z[:5] + z[6:]
hours = int(z[1:3])
Expand Down
18 changes: 16 additions & 2 deletions Lib/test/datetimetester.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2895,6 +2895,12 @@ def test_strptime(self):
strptime("-00:02:01.000003", "%z").utcoffset(),
-timedelta(minutes=2, seconds=1, microseconds=3)
)
self.assertEqual(strptime("+01:07", "%:z").utcoffset(),
1 * HOUR + 7 * MINUTE)
self.assertEqual(strptime("-10:02", "%:z").utcoffset(),
-(10 * HOUR + 2 * MINUTE))
self.assertEqual(strptime("-00:00:01.00001", "%:z").utcoffset(),
-timedelta(seconds=1, microseconds=10))
# Only local timezone and UTC are supported
for tzseconds, tzname in ((0, 'UTC'), (0, 'GMT'),
(-_time.timezone, _time.tzname[0])):
Expand Down Expand Up @@ -2973,7 +2979,7 @@ def test_strptime_leap_year(self):
self.theclass.strptime('02-29,2024', '%m-%d,%Y')

def test_strptime_z_empty(self):
for directive in ('z',):
for directive in ('z', ':z'):
string = '2025-04-25 11:42:47'
format = f'%Y-%m-%d %H:%M:%S%{directive}'
target = self.theclass(2025, 4, 25, 11, 42, 47)
Expand Down Expand Up @@ -4041,6 +4047,12 @@ def test_strptime_tz(self):
strptime("-00:02:01.000003", "%z").utcoffset(),
-timedelta(minutes=2, seconds=1, microseconds=3)
)
self.assertEqual(strptime("+01:07", "%:z").utcoffset(),
1 * HOUR + 7 * MINUTE)
self.assertEqual(strptime("-10:02", "%:z").utcoffset(),
-(10 * HOUR + 2 * MINUTE))
self.assertEqual(strptime("-00:00:01.00001", "%:z").utcoffset(),
-timedelta(seconds=1, microseconds=10))
# Only local timezone and UTC are supported
for tzseconds, tzname in ((0, 'UTC'), (0, 'GMT'),
(-_time.timezone, _time.tzname[0])):
Expand Down Expand Up @@ -4070,9 +4082,11 @@ def test_strptime_tz(self):
self.assertEqual(strptime("UTC", "%Z").tzinfo, None)

def test_strptime_errors(self):
for tzstr in ("-2400", "-000", "z"):
for tzstr in ("-2400", "-000", "z", "24:00"):
with self.assertRaises(ValueError):
self.theclass.strptime(tzstr, "%z")
with self.assertRaises(ValueError):
self.theclass.strptime(tzstr, "%:z")

def test_strptime_single_digit(self):
# bpo-34903: Check that single digit times are allowed.
Expand Down
49 changes: 28 additions & 21 deletions Lib/test/test_strptime.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -406,34 +406,41 @@ def test_offset(self):
(*_, offset), _, offset_fraction = _strptime._strptime("-013030.000001", "%z")
self.assertEqual(offset, -(one_hour + half_hour + half_minute))
self.assertEqual(offset_fraction, -1)
(*_, offset), _, offset_fraction = _strptime._strptime("+01:00", "%z")
self.assertEqual(offset, one_hour)
self.assertEqual(offset_fraction, 0)
(*_, offset), _, offset_fraction = _strptime._strptime("-01:30", "%z")
self.assertEqual(offset, -(one_hour + half_hour))
self.assertEqual(offset_fraction, 0)
(*_, offset), _, offset_fraction = _strptime._strptime("-01:30:30", "%z")
self.assertEqual(offset, -(one_hour + half_hour + half_minute))
self.assertEqual(offset_fraction, 0)
(*_, offset), _, offset_fraction = _strptime._strptime("-01:30:30.000001", "%z")
self.assertEqual(offset, -(one_hour + half_hour + half_minute))
self.assertEqual(offset_fraction, -1)
(*_, offset), _, offset_fraction = _strptime._strptime("+01:30:30.001", "%z")
self.assertEqual(offset, one_hour + half_hour + half_minute)
self.assertEqual(offset_fraction, 1000)
(*_, offset), _, offset_fraction = _strptime._strptime("Z", "%z")
self.assertEqual(offset, 0)
self.assertEqual(offset_fraction, 0)
for directive in ("%z", "%:z"):
(*_, offset), _, offset_fraction = _strptime._strptime("+01:00",
directive)
self.assertEqual(offset, one_hour)
self.assertEqual(offset_fraction, 0)
(*_, offset), _, offset_fraction = _strptime._strptime("-01:30",
directive)
self.assertEqual(offset, -(one_hour + half_hour))
self.assertEqual(offset_fraction, 0)
(*_, offset), _, offset_fraction = _strptime._strptime("-01:30:30",
directive)
self.assertEqual(offset, -(one_hour + half_hour + half_minute))
self.assertEqual(offset_fraction, 0)
(*_, offset), _, offset_fraction = _strptime._strptime("-01:30:30.000001",
directive)
self.assertEqual(offset, -(one_hour + half_hour + half_minute))
self.assertEqual(offset_fraction, -1)
(*_, offset), _, offset_fraction = _strptime._strptime("+01:30:30.001",
directive)
self.assertEqual(offset, one_hour + half_hour + half_minute)
self.assertEqual(offset_fraction, 1000)

def test_bad_offset(self):
with self.assertRaises(ValueError):
_strptime._strptime("-01:30:30.", "%z")
for directive in ("%z", "%:z"):
with self.assertRaises(ValueError):
_strptime._strptime("-01:30:30.", directive)
with self.assertRaises(ValueError):
_strptime._strptime("-01:30:30.1234567", directive)
with self.assertRaises(ValueError):
_strptime._strptime("-01:30:30:123456", directive)
with self.assertRaises(ValueError):
_strptime._strptime("-0130:30", "%z")
with self.assertRaises(ValueError):
_strptime._strptime("-01:30:30.1234567", "%z")
with self.assertRaises(ValueError):
_strptime._strptime("-01:30:30:123456", "%z")
with self.assertRaises(ValueError) as err:
_strptime._strptime("-01:3030", "%z")
self.assertEqual("Inconsistent use of : in -01:3030", str(err.exception))
Comment on lines 446 to 448
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The error message should be improved for this case, i.e. lack of colons, (see my previous review for the current state) and tested in this pr IMO.

Copy link
Contributor Author

@donBarbos donBarbos Sep 16, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

After thinking about it, I realized that the “unconverted data remains” error does not happen with %:z because, in your example, the string doesn’t fully match the expected format. With %z, however, the same string is considered valid. The difference comes from how the use of colons is handled, this consistency check is specific to %z, since %:z always requires colons by definition (it's by regex rule).
I can probably add a hack to check for this, but it seems like it's just not the right message since it's an additional check to match and it would be weird to use an additional rule for %z to %:z.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I understand why you suggested that (because it seems to indicate a lack of colons), but it's actually a %z-specific check that checks for consistency.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oof. This does seem symmetrical with the %z case, but it does seem annoying to fix in the current regex-based system. I think special-casing it is fine as long as it's not too messy, but if there's no clean way to do it we can maybe just accept this and see if anyone complains.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For reference, it currently raises:

>>> datetime.strptime("-01:3030", "%:z")
ValueError: unconverted data remains: 30

I have a good feeling people will complain, as the message isn't helpful and also makes it seem like %:z doesn't support seconds.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I accepted all suggestions, including trying to carefully write a hack for this case, and taking advantage of the fact that the error was actually different and in other place, I clarified what the error was.
But I also want to note that if the : between HH and MM is missing (for example -0130:30), the error will be uncovered data ..., but for %z there is also a different error (ValueError: invalid literal for int() with base 10: ':3').

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have a good feeling people will complain, as the message isn't helpful and also makes it seem like %:z doesn't support seconds.

I suspect you are right, but also I am kind of hoping that at some point in the future we will do a teardown rewrite of strftime and strptime that uses a state machine or something else other than a bunch of regexes, at which point it would be much easier to make these errors nice (and probably make strptime/strftime dramatically faster, and I think that this PR is an improvement over the status quo even with this particular corner case having a funky error message.

Expand Down
2 changes: 2 additions & 0 deletions Misc/NEWS.d/next/Library/2025-07-21-20-00-42.gh-issue-121237.DyxNqo.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
Support ``%:z`` directive for :meth:`~datetime.datetime.strptime` and
:meth:`~datetime.time.strptime`. Patch by Lucas Esposito and Semyon Moroz.
Loading