gh-153056: Fix a data race compiling the string.Template pattern in free-threading builds

Template compiles its substitution pattern lazily and caches it on the class.  On the free-threaded build two concurrent first uses could race: a thread that observed the pattern another thread had just compiled would try to recompile it, and re.compile() rejects flags on an already-compiled pattern, raising a spurious ValueError.  Return the already-compiled pattern instead.

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

Author: tonghuaroot

Lib/string/__init__.py

@@ -84,6 +84,9 @@ def _compile_pattern(cls):
         import re  # deferred import, for performance
 
         pattern = cls.__dict__.get('pattern', _TemplatePattern)
+        if isinstance(pattern, re.Pattern):
+            # Already compiled; reuse it (re.compile() rejects flags on a Pattern).
+            return pattern
         if pattern is _TemplatePattern:
             delim = re.escape(cls.delimiter)
             id = cls.idpattern

Lib/test/test_free_threading/test_string_template_race.py

@@ -0,0 +1,38 @@
+import string
+import unittest
+from string import Template
+
+from test.support import threading_helper
+
+
+@threading_helper.requires_working_threading()
+class TestTemplateCompileRace(unittest.TestCase):
+    def test_concurrent_first_use(self):
+        # Template compiles its pattern lazily on first use and caches it on the
+        # class.  Race that lazy compile from many threads and confirm none hits
+        # a spurious ValueError from recompiling an already-compiled pattern.
+        # Use a throwaway subclass each round so the shared string.Template is
+        # never mutated; subclasses precompile in __init_subclass__, so restore
+        # the sentinel descriptor (string._TemplatePattern) to re-arm the lazy
+        # path before racing.
+        uncompiled = string._TemplatePattern
+        errors = []
+
+        def use_template(cls):
+            try:
+                cls("$x and ${y}").substitute(x=1, y=2)
+            except Exception as e:
+                errors.append(e)
+
+        for _ in range(20):
+            class T(Template):
+                pass
+            T.pattern = uncompiled
+            T.flags = None
+            threading_helper.run_concurrently(use_template, nthreads=10, args=(T,))
+
+        self.assertEqual(errors, [], msg=f"unexpected errors: {errors}")
+
+
+if __name__ == "__main__":
+    unittest.main()

Lib/test/test_string/test_string.py

@@ -299,6 +299,22 @@ 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).
+        # This is the non-threaded form of the free-threading lazy-compile race
+        # where a thread observes the pattern another thread just compiled.
+        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,2 @@
+Fix a race in :class:`string.Template` where concurrent first use of a
+template on the free-threaded build could raise a spurious :exc:`ValueError`.