Add Python 3.14 t-string support with tstr backport

evhub · claude · evhub · commit 74943d1b9dd6 · 2025-12-29T21:39:45.000-08:00
Resolves #866. - Add native t-string (template string) support for Python 3.14+ - Backport t-strings to Python 3.10+ using tstr library - T-strings compile to native syntax on 3.14+, _coconut.tstr.t() on older versions - Add py310_spec_test and py314_test for template string verification - Update grammar to recognize t"..." and rt"..." string prefixes 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
diff --git a/.claude/settings.local.json b/.claude/settings.local.json
@@ -2,14 +2,19 @@
   "permissions": {
     "allow": [
       "Bash(cat:*)",
-      "Bash(make:*)",
       "Bash(python:*)",
       "Bash(xonsh:*)",
       "Bash(gh:*)",
+      "Bash(pip:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(make test-tests:*)",
       "WebSearch",
       "WebFetch(domain:coconut.readthedocs.io)",
       "WebFetch(domain:github.com)",
-      "WebFetch(domain:peps.python.org)"
+      "WebFetch(domain:peps.python.org)",
+      "WebFetch(domain:pypi.org)",
+      "WebFetch(domain:discuss.python.org)"
     ]
   }
 }
diff --git a/DOCS.md b/DOCS.md
@@ -364,6 +364,7 @@ In addition to the newer Python features that Coconut can backport automatically
 - [`aenum`](https://pypi.org/project/aenum) for backporting [`enum`](https://docs.python.org/3/library/enum.html).
 - [`async_generator`](https://github.com/python-trio/async_generator) for backporting [`async` generators](https://peps.python.org/pep-0525/) and [`asynccontextmanager`](https://docs.python.org/3/library/contextlib.html#contextlib.asynccontextmanager).
 - [`trollius`](https://pypi.python.org/pypi/trollius) for backporting [`async`/`await`](https://docs.python.org/3/library/asyncio-task.html) and [`asyncio`](https://docs.python.org/3/library/asyncio.html).
+- [`tstr`](https://github.com/ilotoki0804/tstr) for backporting [template strings (`t"..."`)](https://peps.python.org/pep-0750/) on Python < 3.14.
 
 Note that, when distributing compiled Coconut code, if you use any of these backports, you'll need to make sure that the requisite backport module is included as a dependency.
 
diff --git a/_coconut/__init__.pyi b/_coconut/__init__.pyi
@@ -59,6 +59,13 @@ else:
 
 if sys.version_info >= (3, 5):
     import async_generator as _async_generator  # type: ignore
+else:
+    _async_generator = ...  # type: ignore
+
+if sys.version_info >= (3, 14):
+    import tstr as _tstr  # type: ignore
+else:
+    _tstr = ...  # type: ignore
 
 try:
     import numpy as _numpy  # type: ignore
@@ -95,6 +102,7 @@ copyreg = _copyreg
 asyncio = _asyncio
 asyncio_Return = StopIteration
 async_generator = _async_generator
+tstr = _tstr
 pickle = _pickle
 if sys.version_info >= (2, 7):
     OrderedDict = collections.OrderedDict
diff --git a/coconut/compiler/compiler.py b/coconut/compiler/compiler.py
@@ -858,6 +858,7 @@ def bind(cls):
         cls.testlist_star_namedexpr <<= attach(cls.testlist_star_namedexpr_tokens, cls.method("testlist_star_expr_handle"))
         cls.ellipsis <<= attach(cls.ellipsis_tokens, cls.method("ellipsis_handle"))
         cls.f_string <<= attach(cls.f_string_tokens, cls.method("f_string_handle"))
+        cls.t_string <<= attach(cls.t_string_tokens, cls.method("t_string_handle"))
         cls.funcname_typeparams <<= attach(cls.funcname_typeparams_tokens, cls.method("funcname_typeparams_handle"))
 
         # standard handlers of the form name <<= attach(name_ref, method("name_handle"))
@@ -4644,8 +4645,8 @@ def cases_stmt_handle(self, original, loc, tokens):
             out += "if not " + check_var + default
         return out
 
-    def f_string_handle(self, original, loc, tokens):
-        """Process Python 3.6 format strings."""
+    def f_string_handle(self, original, loc, tokens, is_t=False):
+        """Process Python 3.6 format strings and Python 3.14 template strings."""
         string, = tokens
 
         # strip raw r
@@ -4662,7 +4663,7 @@ def f_string_handle(self, original, loc, tokens):
 
         # warn if there are no exprs
         if not exprs:
-            self.strict_err_or_warn("f-string with no expressions", original, loc)
+            self.strict_err_or_warn(("t" if is_t else "f") + "-string with no expressions", original, loc)
 
         # handle Python 3.8 f string = specifier
         for i, expr in enumerate(exprs):
@@ -4683,22 +4684,39 @@ def f_string_handle(self, original, loc, tokens):
                 raise CoconutDeferredSyntaxError("illegal complex expression in format string: " + co_expr, loc)
             compiled_exprs.append(py_expr)
 
-        # reconstitute string
-        #  (though f strings are supported on 3.6+, nested strings with the same strchars are only
-        #   supported on 3.12+, so we should only use the literal syntax there)
-        if self.target_info >= (3, 12):
+        # handle t-strings
+        if is_t:
             new_text = interleaved_join(string_parts, compiled_exprs)
-            return "f" + ("r" if raw else "") + self.wrap_str(new_text, strchar)
+            if self.target_info >= (3, 14):
+                # Native t-string syntax
+                return "t" + ("r" if raw else "") + self.wrap_str(new_text, strchar)
+            else:
+                # Use tstr backport - tstr.t() uses caller's frame for variable lookup
+                # Will raise runtime error if tstr not available (works with universal target)
+                template_str = ("r" if raw else "") + self.wrap_str(new_text, strchar)
+                return "_coconut.tstr.t(" + template_str + ")" + self.type_ignore_comment()
 
         else:
-            names = [format_var + "_" + str(i) for i in range(len(compiled_exprs))]
-            new_text = interleaved_join(string_parts, names)
-
-            # generate format call
-            return ("r" if raw else "") + self.wrap_str(new_text, strchar) + ".format(" + ", ".join(
-                name + "=(" + self.wrap_passthrough(expr) + ")"
-                for name, expr in zip(names, compiled_exprs)
-            ) + ")"
+            # reconstitute string
+            #  (though f strings are supported on 3.6+, nested strings with the same strchars are only
+            #   supported on 3.12+, so we should only use the literal syntax there)
+            if self.target_info >= (3, 12):
+                new_text = interleaved_join(string_parts, compiled_exprs)
+                return "f" + ("r" if raw else "") + self.wrap_str(new_text, strchar)
+
+            else:
+                names = [format_var + "_" + str(i) for i in range(len(compiled_exprs))]
+                new_text = interleaved_join(string_parts, names)
+
+                # generate format call
+                return ("r" if raw else "") + self.wrap_str(new_text, strchar) + ".format(" + ", ".join(
+                    name + "=(" + self.wrap_passthrough(expr) + ")"
+                    for name, expr in zip(names, compiled_exprs)
+                ) + ")"
+
+    def t_string_handle(self, original, loc, tokens):
+        """Process Python 3.14 template strings."""
+        return self.f_string_handle(original, loc, tokens, is_t=True)
 
     def decorators_handle(self, loc, tokens):
         """Process decorators."""
diff --git a/coconut/compiler/grammar.py b/coconut/compiler/grammar.py
@@ -929,20 +929,23 @@ class Grammar(object):
 
         u_string = Forward()
         f_string = Forward()
+        t_string = Forward()
 
         bit_b = caseless_literal("b")
         raw_r = caseless_literal("r")
         unicode_u = caseless_literal("u", suppress=True)
         format_f = caseless_literal("f", suppress=True)
+        template_t = caseless_literal("t", suppress=True)
 
         string = combine(Optional(raw_r) + string_item)
         # Python 2 only supports br"..." not rb"..."
         b_string = combine((bit_b + Optional(raw_r) | fixto(raw_r + bit_b, "br")) + string_item)
         # ur"..."/ru"..." strings are not suppored in Python 3
         u_string_ref = combine(unicode_u + string_item)
         f_string_tokens = combine((format_f + Optional(raw_r) | raw_r + format_f) + string_item)
+        t_string_tokens = combine((template_t + Optional(raw_r) | raw_r + template_t) + string_item)
         nonbf_string = string | u_string
-        nonb_string = nonbf_string | f_string
+        nonb_string = nonbf_string | f_string | t_string
         any_string = nonb_string | b_string
         moduledoc = any_string + newline
         docstring = condense(moduledoc)
@@ -2862,7 +2865,7 @@ class Grammar(object):
             | fixto(end_of_line, "misplaced newline (maybe missing ':')")
         )
 
-        start_f_str_regex = compile_regex(r"\br?fr?$")
+        start_f_str_regex = compile_regex(r"\br?[ft]r?$")
         start_f_str_regex_len = 4
 
         end_f_str_expr = StartOfStrGrammar(combine(rbrace | colon | bang).leaveWhitespace())
diff --git a/coconut/compiler/header.py b/coconut/compiler/header.py
@@ -766,6 +766,17 @@ def Return(self, obj):
             ''',
             indent=1,
         ),
+        import_tstr=pycondition(
+            (3, 14),
+            if_lt='''
+try:
+    import tstr
+except ImportError as tstr_import_err:
+    tstr = _coconut_missing_module(tstr_import_err)
+            ''',
+            if_ge='',
+            indent=1,
+        ),
         class_amap=pycondition(
             (3, 3),
             if_lt='''
diff --git a/coconut/compiler/templates/header.py_template b/coconut/compiler/templates/header.py_template
@@ -27,6 +27,7 @@ class _coconut{object}:{COMMENT.EVERYTHING_HERE_MUST_BE_COPIED_TO_STUB_FILE}
         import async_generator
     except ImportError as async_generator_import_err:
         async_generator = _coconut_missing_module(async_generator_import_err)
+{import_tstr}
 {import_pickle}
 {import_OrderedDict}
 {import_collections_abc}
diff --git a/coconut/constants.py b/coconut/constants.py
@@ -968,6 +968,7 @@ def get_path_env_var(env_var, default):
         ("dataclasses", "py==36"),
         ("typing", "py<35"),
         ("async_generator", "py35"),
+        ("tstr", "py310"),
         ("exceptiongroup", "py37;py<311"),
         ("anyio", "py36"),
         "setuptools",
@@ -1086,6 +1087,7 @@ def get_path_env_var(env_var, default):
     ("pygments", "py>=39"): (2, 19),
     ("xonsh", "py311"): (0, 22),
     ("async_generator", "py35"): (1, 10),
+    ("tstr", "py310"): (0, 4),
     ("exceptiongroup", "py37;py<311"): (1,),
     ("ipython", "py>=311"): (9,),
     "py-spy": (0, 4),
diff --git a/coconut/root.py b/coconut/root.py
@@ -26,7 +26,7 @@
 VERSION = "3.1.2"
 VERSION_NAME = None
 # False for release, int >= 1 for develop
-DEVELOP = 9
+DEVELOP = 10
 ALPHA = False  # for pre releases rather than post releases
 
 assert DEVELOP is False or DEVELOP >= 1, "DEVELOP must be False or an int >= 1"
diff --git a/coconut/tests/main_test.py b/coconut/tests/main_test.py
@@ -659,6 +659,19 @@ def comp_311(args=[], always_sys=False, **kwargs):
     comp(path="cocotest", folder="target_311", args=["--target", "311" if not always_sys else "sys"] + args, **kwargs)
 
 
+def comp_314(args=[], always_sys=False, **kwargs):
+    """Compiles target_314."""
+    # remove --mypy checking when running on Python 3.14 since MyPy can't parse t-strings
+    if sys.version_info < (3, 14):
+        try:
+            mypy_ind = args.index("--mypy")
+        except ValueError:
+            pass
+        else:
+            args = args[:mypy_ind]
+    comp(path="cocotest", folder="target_314", args=["--target", "314" if not always_sys else "sys"] + args, **kwargs)
+
+
 def comp_sys(args=[], **kwargs):
     """Compiles target_sys."""
     comp(path="cocotest", folder="target_sys", args=["--target", "sys"] + args, **kwargs)
@@ -719,6 +732,8 @@ def run(
                         comp_38(args, **spec_kwargs)
                     if sys.version_info >= (3, 11):
                         comp_311(args, **spec_kwargs)
+                    if sys.version_info >= (3, 14):
+                        comp_314(args, **spec_kwargs)
 
                 if not run_directory:
                     comp_agnostic(agnostic_args, **kwargs)
@@ -776,6 +791,7 @@ def comp_all(args=[], agnostic_target=None, **kwargs):
     comp_36(args, **kwargs)
     comp_38(args, **kwargs)
     comp_311(args, **kwargs)
+    comp_314(args, **kwargs)
     comp_sys(args, **kwargs)
     # do non-strict at the end so we get the non-strict header
     comp_non_strict(args, **kwargs)
diff --git a/coconut/tests/src/cocotest/agnostic/main.coco b/coconut/tests/src/cocotest/agnostic/main.coco
@@ -65,6 +65,7 @@ def run_main(outer_MatchError, test_easter_eggs=False) -> bool:
         py36_spec_test,
         py37_spec_test,
         py38_spec_test,
+        py310_spec_test,
     )
     if sys.version_info >= (2, 7):
         assert non_py26_test() is True
@@ -80,6 +81,8 @@ def run_main(outer_MatchError, test_easter_eggs=False) -> bool:
         assert py37_spec_test() is True
     if sys.version_info >= (3, 8):
         assert py38_spec_test() is True
+    if sys.version_info >= (3, 10):
+        assert py310_spec_test() is True
 
     print_dot()  # .....
     from .suite import suite_test, tco_test
@@ -112,6 +115,11 @@ def run_main(outer_MatchError, test_easter_eggs=False) -> bool:
         if sys.version_info >= (3, 11):
             from .py311_test import py311_test
             assert py311_test() is True
+        if sys.version_info >= (3, 14):
+            # use dynamic import to avoid MyPy parsing t-string syntax on older Python
+            from importlib import import_module
+            py314_test = import_module(".py314_test", __package__).py314_test
+            assert py314_test() is True
 
     print_dot()  # ........
     from .target_sys_test import TEST_ASYNCIO, target_sys_test
diff --git a/coconut/tests/src/cocotest/agnostic/specific.coco b/coconut/tests/src/cocotest/agnostic/specific.coco
@@ -201,3 +201,40 @@ def py38_spec_test() -> bool:
     from itertools import accumulate
     assert range(5) |> accumulate$(?, (+), initial=10) |> list == [10, 10, 11, 13, 16, 20]
     return True
+
+
+def py310_spec_test() -> bool:
+    """Tests for any py310+ version (t-string backport)."""
+    # Test basic t-string with tstr backport
+    name = "World"
+    template = t"Hello {name}!"
+    assert type(template).__name__ == "Template"
+    assert template.strings == ("Hello ", "!")
+    assert len(template.interpolations) == 1
+    assert template.interpolations[0].value == "World"
+
+    # Test t-string with Coconut syntax
+    template2 = t"Result: {[1,2,3] |> len}"
+    assert template2.strings == ("Result: ", "")
+    assert template2.interpolations[0].value == 3
+
+    # Test t-string with = specifier (debug syntax)
+    x = 42
+    template3 = t"{x=}"
+    assert template3.interpolations[0].value == 42
+
+    # Test raw t-string
+    template4 = rt"\n{x}"
+    assert template4.strings == ("\\n", "")
+    assert template4.interpolations[0].value == 42
+
+    # Test multiple interpolations
+    a, b = 1, 2
+    template5 = t"{a} + {b} = {a + b}"
+    assert template5.strings == ("", " + ", " = ", "")
+    assert len(template5.interpolations) == 3
+    assert template5.interpolations[0].value == 1
+    assert template5.interpolations[1].value == 2
+    assert template5.interpolations[2].value == 3
+
+    return True
diff --git a/coconut/tests/src/cocotest/target_314/py314_test.coco b/coconut/tests/src/cocotest/target_314/py314_test.coco
@@ -0,0 +1,35 @@
+def py314_test() -> bool:
+    """Performs Python-3.14-specific tests."""
+    # Test basic t-string
+    name = "World"
+    template = t"Hello {name}!"
+    assert type(template).__name__ == "Template"
+    assert template.strings == ("Hello ", "!")
+    assert len(template.interpolations) == 1
+    assert template.interpolations[0].value == "World"
+
+    # Test t-string with Coconut syntax
+    template2 = t"Result: {[1,2,3] |> len}"
+    assert template2.strings == ("Result: ", "")
+    assert template2.interpolations[0].value == 3
+
+    # Test t-string with = specifier (debug syntax)
+    x = 42
+    template3 = t"{x=}"
+    assert template3.interpolations[0].value == 42
+
+    # Test raw t-string
+    template4 = rt"\n{x}"
+    assert template4.strings == ("\\n", "")
+    assert template4.interpolations[0].value == 42
+
+    # Test multiple interpolations
+    a, b = 1, 2
+    template5 = t"{a} + {b} = {a + b}"
+    assert template5.strings == ("", " + ", " = ", "")
+    assert len(template5.interpolations) == 3
+    assert template5.interpolations[0].value == 1
+    assert template5.interpolations[1].value == 2
+    assert template5.interpolations[2].value == 3
+
+    return True
