[3.13] gh-153056: Backport the relevant bits of (#153057) (#153369)

gh-153056: Backport the relevant bits of (#153057)

The data race for compiling the string.Template pattern in free-threading builds is not relevant for
3.13, due to the older string.Template and string.py module implementation.  However, the secondary
bug identified by that isue is still relevant here, and fixed in this branch:

    As a side effect, a subclass that supplies an already-compiled pattern now works too; previously
    it raised the same ValueError at class definition.

* Document that the pattern attribute accepts a string or a compiled regex
* Comment the three states of pattern and note the documented-behavior fix in NEWS
* Update Doc/library/string.rst

---------


(cherry picked from commit 4572903)

Co-authored-by: tonghuaroot (童话) <tonghuaroot@gmail.com>

Author: warsaw

Doc/library/string.rst

@@ -943,7 +943,8 @@ attributes:
 
 Alternatively, you can provide the entire regular expression pattern by
 overriding the class attribute *pattern*.  If you do this, the value must be a
-regular expression object with four named capturing groups.  The capturing
+regular expression pattern string, or a compiled regular expression
+object, with four named capturing groups.  The capturing
 groups correspond to the rules given above, along with the invalid placeholder
 rule:
 

Lib/string.py

@@ -70,6 +70,11 @@ def __init_subclass__(cls):
         super().__init_subclass__()
         if 'pattern' in cls.__dict__:
             pattern = cls.pattern
+            if isinstance(pattern, _re.Pattern):
+                # An already-compiled pattern (which the documentation allows)
+                # is used as-is; re.compile() rejects flags on a compiled
+                # pattern.
+                return
         else:
             delim = _re.escape(cls.delimiter)
             id = cls.idpattern

Lib/test/test_string.py

@@ -272,6 +272,20 @@ def test_SafeTemplate(self):
         eq(s.safe_substitute(dict(who='tim', what='ham', meal='dinner')),
            'tim likes ham for dinner')
 
+    def test_precompiled_pattern(self):
+        # A subclass may supply an already-compiled pattern; it must be reused,
+        # not recompiled (re.compile() rejects flags on a compiled pattern).
+        import re
+        compiled = re.compile(
+            r'\$(?:(?P<escaped>\$)|(?P<named>[a-z]+)|'
+            r'\{(?P<braced>[a-z]+)\}|(?P<invalid>))')
+        class MyTemplate(Template):
+            pattern = compiled
+        self.assertIs(MyTemplate.pattern, compiled)
+        self.assertEqual(
+            MyTemplate('$who likes $what').substitute(who='tim', what='ham'),
+            'tim likes ham')
+
     def test_invalid_placeholders(self):
         raises = self.assertRaises
         s = Template('$who likes $')

Misc/NEWS.d/next/Library/2026-07-05-12-00-00.gh-issue-153056.tMpLat.rst

@@ -0,0 +1,3 @@
+Fix :class:`string.Template` raising a spurious :exc:`ValueError` when the
+*pattern* attribute is a compiled regular expression object, which the
+documentation allows.