gh-121237: Add %:z directive to strptime

Author: LucasEsposito

Doc/library/datetime.rst

@@ -2538,7 +2538,21 @@ 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.13
+   ``%:z`` was added for :meth:`~.datetime.strptime`
+
+.. warning::
+
+   Since version 3.12, when ``%z`` directive is used in :meth:`~.datetime.strptime`,
+   strings formatted according ``%z`` directive are accepted and parsed correctly,
+   as well as strings formatted according to ``%:z``.
+   The later part of the behavior is unintended but it's still kept for backwards
+   compatibility.
+   Nonetheless, it's encouraged to use ``%z`` directive only to parse strings
+   formatted according to ``%z`` directive, while using ``%:z`` directive
+   for strings formatted according to ``%:z``.
 
 Technical Detail
 ^^^^^^^^^^^^^^^^

Lib/_strptime.py

@@ -202,7 +202,10 @@ def __init__(self, locale_time=None):
             #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
+            # compatibility, we must keep them (see gh-121237)
             '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(self.locale_time.f_month[1:], 'B'),
@@ -254,13 +257,16 @@ def pattern(self, format):
         year_in_format = False
         day_of_month_in_format = False
         while '%' in format:
-            directive_index = format.index('%')+1
-            format_char = format[directive_index]
+            directive_index = format.index('%') + 1
+            directive = format[directive_index]
+            if directive == ":":
+                # Special case for "%:z", which has an extra character
+                directive += format[directive_index + 1]
             processed_format = "%s%s%s" % (processed_format,
-                                           format[:directive_index-1],
-                                           self[format_char])
-            format = format[directive_index+1:]
-            match format_char:
+                                           format[:directive_index - 1],
+                                           self[directive])
+            format = format[directive_index + len(directive):]
+            match directive:
                 case 'Y' | 'y' | 'G':
                     year_in_format = True
                 case 'd':
@@ -446,16 +452,16 @@ def _strptime(data_string, format="%a %b %d %H:%M:%S %Y"):
                 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 == 'Z':
                 gmtoff = 0
             else:
                 if z[3] == ':':
                     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 {z}"
                             raise ValueError(msg)
                         z = z[:5] + z[6:]
                 hours = int(z[1:3])

Lib/test/test_strptime.py

@@ -12,6 +12,9 @@
 
 import _strptime
 
+from Lib.test.test_zipfile._path._test_params import parameterize
+
+
 class getlang_Tests(unittest.TestCase):
     """Test _getlang"""
     def test_basic(self):
@@ -354,7 +357,7 @@ def test_julian(self):
         # Test julian directives
         self.helper('j', 7)
 
-    def test_offset(self):
+    def test_z_directive_offset(self):
         one_hour = 60 * 60
         half_hour = 30 * 60
         half_minute = 30
@@ -370,22 +373,39 @@ 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")
+
+    @parameterize(
+        ["directive"],
+        [
+            ("%z",),
+            ("%:z",),
+        ]
+    )
+    def test_iso_offset(self, directive: str):
+        """
+        Tests offset for the '%:z' directive from ISO 8601.
+        Since '%z' directive also accepts '%:z'-formatted strings for backwards compatibility,
+        we're testing that here too.
+        """
+        one_hour = 60 * 60
+        half_hour = 30 * 60
+        half_minute = 30
+        (*_, 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", "%z")
+        (*_, 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", "%z")
+        (*_, 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", "%z")
+        (*_, 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", "%z")
+        (*_, offset), _, offset_fraction = _strptime._strptime("+01:30:30.001", directive)
         self.assertEqual(offset, one_hour + half_hour + half_minute)
         self.assertEqual(offset_fraction, 1000)
-        (*_, offset), _, offset_fraction = _strptime._strptime("Z", "%z")
+        (*_, offset), _, offset_fraction = _strptime._strptime("Z", directive)
         self.assertEqual(offset, 0)
         self.assertEqual(offset_fraction, 0)
 

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

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