Merge pull request #2698 from scauligi/tstrings

Templated strings

Author: scauligi

NEWS.rst

@@ -10,6 +10,8 @@ Supports Python 3.x – Python 3.y
 New Features
 ------------------------------
 * ``hyc`` now supports ``-q``/``--quiet`` to suppress progress messages.
+* Added support for t-strings from Python 3.14.
+* Added new pragma `bracketed-templates` to allow parsing `#[t[...]t]` and `#[t-<ident>[...]t-<ident>]` as template strings (analogous to bracketed f-strings).
 
 Bug Fixes
 ------------------------------
@@ -24,6 +26,7 @@ Bug Fixes
   and Complex models.
 * Fixed an importlib exception when using `hy.eval` on code that
   required other modules.
+* Invalid conversion chars in f-strings now properly raise a syntax error.
 
 1.2.0 ("Crackers and Snacks", released 2026-01-14)
 ======================================================================

docs/api.rst

@@ -187,6 +187,12 @@ Fundamentals
     dangerous, because other macros may call your new macro when they meant to
     refer to the core macro.
 
+    .. _bracketed-templates:
+
+  - ``:bracketed-templates``: If set, then :ref:`bracket strings
+    <bracket-strings>` using the delimiter "t" or any delimiter starting with
+    "t-" are parsed as :ref:`template strings <syntax-tstrings>`.
+
 Quoting
 ~~~~~~~~~~~~
 

docs/syntax.rst

@@ -347,7 +347,7 @@ The result is the model type :class:`String <hy.models.String>`.
 You may prefix a string literal with ``b`` to treat it as a sequence of bytes,
 producing :class:`Bytes <hy.models.Bytes>` instead.
 
-Unlike Python, Hy only recognizes string prefixes (``r``, ``b``, and ``f``) in
+Unlike Python, Hy only recognizes string prefixes (``r``, ``b``, ``f``, ``t``) in
 lowercase, and doesn't allow the no-op prefix ``u``.
 
 :ref:`F-strings <syntax-fstrings>` are a string-like compound construct
@@ -504,6 +504,28 @@ language. Thus e.g. ``f"{"a"}"`` is legal, and equivalent to ``"a"``.
 .. autoclass:: hy.models.FString
 .. autoclass:: hy.models.FComponent
 
+.. _syntax-tstrings:
+
+Template strings
+~~~~~~~~~~~~~~~~
+
+:py:mod:`Template strings <string.templatelib>` (aka "t-strings" or "template
+string literals") are similar to format strings, and parse to :class:`FString <hy.models.FString>`
+with the parameter ``:is_tstring`` set to ``True``.
+Template strings at runtime evaluate to instances of :py:class:`Template
+<string.templatelib.Template>` containing the sequence of string and
+expression components, without any interpolation.
+Template strings use the prefix "t" in front of a string. Otherwise, the syntax
+of t-strings are exactly the same as f-strings. ::
+
+    (setv tstr t"The sum is {(+ 1 1)}.")
+    tstr.strings      ; => #("The sum is " ".")
+    tstr.values       ; => #(2)
+
+If the :ref:`bracketed-templates <bracketed-templates>` pragma is set, then
+:ref:`bracket strings <bracket-strings>` using the delimiter "t" or any
+delimiter starting with "t-" are also parsed as template strings.
+
 .. _more-sugar:
 
 Additional sugar

hy/compat.py

@@ -7,6 +7,7 @@
 PY3_12 = sys.version_info >= (3, 12)
 PY3_12_6 = sys.version_info >= (3, 12, 6)
 PY3_13 = sys.version_info >= (3, 13)
+PY3_14 = sys.version_info >= (3, 14)
 PYPY = platform.python_implementation() == "PyPy"
 
 

hy/compiler.py

@@ -11,6 +11,7 @@
 from funcparserlib.parser import NoParseError, many
 
 import hy
+from hy.compat import PY3_14
 from hy.errors import HyCompileError, HyLanguageError, HySyntaxError
 from hy.macros import macroexpand
 from hy.model_patterns import FORM, KEYWORD, unpack
@@ -658,6 +659,12 @@ def compile_string(self, string):
 
     @builds_model(FComponent)
     def compile_fcomponent(self, fcomponent):
+        if not PY3_14 and fcomponent.is_tstring:
+            raise self._syntax_error(fcomponent, "Template string literals require Python 3.14 or later")
+        if fcomponent.conversion not in (None, 's', 'r', 'a'):
+            raise self._syntax_error(
+                fcomponent, f"Invalid conversion character {fcomponent.conversion!r}"
+            )
         conversion = ord(fcomponent.conversion) if fcomponent.conversion else -1
         root, *rest = fcomponent
         value = self.compile(root)
@@ -669,15 +676,18 @@ def compile_fcomponent(self, fcomponent):
         return (
             value
             + ret
-            + asty.FormattedValue(
-                fcomponent, value=value.expr, conversion=conversion, format_spec=spec
+            + (asty.Interpolation if fcomponent.is_tstring else asty.FormattedValue)(
+                fcomponent, value=value.expr, conversion=conversion, format_spec=spec,
+                **(dict(str=fcomponent.expression) if fcomponent.is_tstring else {}),
             )
         )
 
     @builds_model(FString)
     def compile_fstring(self, fstring):
+        if not PY3_14 and fstring.is_tstring:
+            raise self._syntax_error(fstring, "Template string literals require Python 3.14 or later")
         elts, ret, _ = self._compile_collect(fstring)
-        return ret + asty.JoinedStr(fstring, values=elts)
+        return ret + (asty.TemplateStr if fstring.is_tstring else asty.JoinedStr)(fstring, values=elts)
 
     @builds_model(List, Set)
     def compile_list(self, expression):

hy/core/hy_repr.hy

@@ -197,7 +197,7 @@
                         "}" "}}")
                       (hy-repr component)))
          "]" fstring.brackets "]")
-      (+ "f\""
+      (+ (if fstring.is-tstring "t" "f") "\""
          #* (lfor component fstring
                   :setv s (hy-repr component)
                   (if (isinstance component hy.models.String)

hy/core/result_macros.py

@@ -58,7 +58,7 @@
     as_model,
     is_unpack,
 )
-from hy.reader import mangle
+from hy.reader import mangle, HyReader
 from hy.scoping import OuterVar, ScopeFn, ScopeGen, ScopeLet, is_function_scope, is_inside_function_scope, nearest_python_scope
 
 # ------------------------------------------------
@@ -186,6 +186,11 @@ def compile_pragma(compiler, expr, root, kwargs):
             compiler.local_state_stack[-1]['warn_on_core_shadow'] = (
                 bool(compiler.eval(value)))
 
+        elif kw == Keyword("bracketed-templates"):
+            reader = HyReader.current_reader(create=False)
+            if reader:
+                reader.bracketed_templates = bool(compiler.eval(value))
+
         else:
             raise compiler._syntax_error(kw, f"Unknown pragma `{kw}`. Perhaps it's implemented by a newer version of Hy.")
 
@@ -252,10 +257,18 @@ def render_quoted_form(compiler, form, level):
             contents.append(f_contents)
         body = [List(contents)]
 
-        if isinstance(form, FString) and form.brackets is not None:
-            body.extend([Keyword("brackets"), String(form.brackets)])
-        elif isinstance(form, FComponent) and form.conversion is not None:
-            body.extend([Keyword("conversion"), String(form.conversion)])
+        if isinstance(form, FString):
+            if form.brackets is not None:
+                body.extend([Keyword("brackets"), String(form.brackets)])
+            if form.is_tstring:
+                body.extend([Keyword("is_tstring"), Symbol("True")])
+        elif isinstance(form, FComponent):
+            if form.conversion is not None:
+                body.extend([Keyword("conversion"), String(form.conversion)])
+            if form.expression is not None:
+                body.extend([Keyword("expression"), String(form.expression)])
+            if form.is_tstring:
+                body.extend([Keyword("is_tstring"), Symbol("True")])
 
     elif isinstance(form, Symbol):
         body = [String(form), Keyword("from_parser"), Symbol("True")]

hy/hy_inspect.py

@@ -11,14 +11,13 @@
 
 import inspect
 import linecache
-import sys
 from contextlib import suppress
 
 from hy.compat import PY3_13
 from hy.errors import HySyntaxError
-from hy.models import as_model, Expression, Lazy, Object
+from hy.models import Expression, Lazy
 from hy.reader import HyReader, read
-from hy.reader.exceptions import LexException, PrematureEndOfInput
+from hy.reader.exceptions import LexException
 
 
 class HySafeReader(HyReader):

hy/models.py

@@ -4,9 +4,12 @@
 from itertools import groupby
 from math import isinf, isnan
 
-from hy import _initialize_env_var
+from hy.compat import PY3_14
 from hy.errors import HyWrapperError
 
+if PY3_14:
+    from string.templatelib import Interpolation, Template
+
 PRETTY = True
 
 
@@ -464,22 +467,28 @@ class FComponent(Sequence):
     format spec (if any).
     """
 
-    _extra_kwargs = ("conversion",)
+    _extra_kwargs = ("conversion", "expression", "is_tstring")
 
-    def __new__(cls, s=None, conversion=None):
+    def __new__(cls, s=None, conversion=None, expression=None, is_tstring=False):
         value = super().__new__(cls, s)
         value.conversion = conversion
+        value.expression = expression
+        value.is_tstring = is_tstring
         return value
 
     def replace(self, other, recursive=True):
         super().replace(other, recursive)
-        if hasattr(other, "conversion"):
-            self.conversion = other.conversion
+        for attr in self._extra_kwargs:
+            if hasattr(other, attr):
+                setattr(self, attr, getattr(other, attr))
         return self
 
     def __repr__(self):
         return "hy.models.FComponent({})".format(
-            super(Object, self).__repr__() + ", conversion=" + repr(self.conversion)
+            (super(Object, self).__repr__()
+             + ", conversion=" + repr(self.conversion)
+             + ", expression=" + repr(self.expression)
+             + ", is_tstring=" + repr(self.is_tstring))
         )
 
 
@@ -498,11 +507,12 @@ class FString(Sequence):
     and :class:`hy.models.FComponent`. The design mimics :class:`ast.JoinedStr`.
 
     :ivar brackets: As in :class:`hy.models.String`.
+    :ivar is_tstring: Whether this represents a template string rather than a format string.
     """
 
-    _extra_kwargs = ("brackets",)
+    _extra_kwargs = ("brackets", "is_tstring")
 
-    def __new__(cls, s=None, brackets=None):
+    def __new__(cls, s=None, brackets=None, is_tstring=False):
         value = super().__new__(
             cls,
             # Join adjacent string nodes for the sake of equality
@@ -519,6 +529,7 @@ def __new__(cls, s=None, brackets=None):
         if brackets is not None and _string_in_node(f"]{brackets}]", value):
             raise ValueError(f"Syntactically illegal bracket string: {s!r}")
         value.brackets = brackets
+        value.is_tstring = is_tstring
         return value
 
     def __repr__(self):
@@ -528,13 +539,19 @@ def __str__(self):
         return self._suffixize(super().__str__())
 
     def _suffixize(self, x):
-        if self.brackets is None:
+        if self.brackets is None and not self.is_tstring:
             return x
-        return "{}{}brackets={!r})".format(
-            x[:-1],  # Clip off the final close paren
-            "" if x[-2] == "(" else ", ",
-            self.brackets,
-        )
+        args = []
+        if self.brackets is not None:
+            args.append(f"brackets={self.brackets!r}")
+        if PY3_14 and self.is_tstring:
+            args.append(f"is_tstring={self.is_tstring!r}")
+        s = x[:-1]  # Clip off the final close paren
+        if s[-1] != "(":
+            s += ", "
+        s += ", ".join(args)
+        s += ")"
+        return s
 
 
 class List(Sequence):
@@ -562,9 +579,19 @@ def lambda_to_return(l):
 
 
 _wrappers[FComponent] = recwrap(FComponent)
+if PY3_14:
+    _wrappers[Interpolation] = lambda interp: FComponent(
+            [as_model(interp.value), as_model(interp.format_spec)],
+            conversion=interp.conversion,
+            expression=interp.expression,
+            is_tstring=True)
 _wrappers[FString] = lambda fstr: FString(
-    (as_model(x) for x in fstr), brackets=fstr.brackets
+    (as_model(x) for x in fstr),
+    brackets=fstr.brackets,
+    is_tstring=fstr.is_tstring,
 )
+if PY3_14:
+    _wrappers[Template] = recwrap(lambda els: FString(els, is_tstring=True))
 _wrappers[List] = recwrap(List)
 _wrappers[list] = recwrap(List)