Improve suport for template strings

Delgan · Delgan · commit 4df1e096b033 · 2026-04-06T17:45:35.000+02:00
Notably:
- Fix support for t-strings with `opt(colors=True)`
- Handle nested t-strings properly
- Implement formatting of t-string in tracebacks (new tokens)
- Update the type hints stub to accept t-strings
- Mention t-strings in documentation
- Add many more unit tests in dedicated file
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -3,6 +3,7 @@
 
 - Change the default log format to include the timezone offset since it produces less ambiguous logs (`#856 <https://github.com/Delgan/loguru/pull/856>`_, thanks `@tim-x-y-z <https://github.com/tim-x-y-z>`_).
 - Add new ``logger.reinstall()`` method to automatically set up the ``logger`` in spawned child processes (`#818 <https://github.com/Delgan/loguru/issues/818>`_, thanks `@monchin <https://github.com/monchin>`_).
+- Add support for template strings used as log messages (`#1397 <https://github.com/Delgan/loguru/issues/1397>`_, thanks `@TurtleOrangina <https://github.com/TurtleOrangina>`_).
 - Fix incorrect microsecond value when formatting the log timestamp using ``{time:x}`` (`#1440 <https://github.com/Delgan/loguru/issues/1440>`_).
 - Fix hex color short code expansion (`#1426 <https://github.com/Delgan/loguru/issues/1426>`_, thanks `@turkoid <https://github.com/turkoid>`_).
 - Fix possible internal error when dealing with (rare) frame objects missing a ``f_lineno`` value (`#1435 <https://github.com/Delgan/loguru/issues/1435>`_).
@@ -17,7 +18,6 @@
 - Make ``logger.catch()`` usable as an asynchronous context manager (`#1084 <https://github.com/Delgan/loguru/issues/1084>`_).
 - Make ``logger.catch()`` compatible with asynchronous generators (`#1302 <https://github.com/Delgan/loguru/issues/1302>`_).
 - Improve feedback for invalid format keys in logger format strings (`#1450 <https://github.com/Delgan/loguru/issues/1450>`_, thanks `@Krishnachaitanyakc <https://github.com/Krishnachaitanyakc>`_).
-- Support python-3.14 template strings as log messages. The comfort of f-string syntax combined with the performance of lazily evaluated formatting. (`#1397 <https://github.com/Delgan/loguru/issues/1302>`_).
 
 
 `0.7.3`_ (2024-12-06)
diff --git a/README.md b/README.md
@@ -20,7 +20,7 @@
     </a>
 </p>
 
----
+______________________________________________________________________
 
 **Loguru** is a library which aims to bring enjoyable logging in Python.
 
@@ -109,24 +109,17 @@ logger.add("file_Y.log", compression="zip")    # Save some loved space
 
 ### Modern string formatting using braces style
 
-For python-3.14 and higher, you can pass a template string, which will be evaluated lazily. The behavior is the same as with a f-string, but the performance is better: Messages that are never emitted won't pay the cost of evaluation.
+Loguru favors the much more elegant and powerful `{}` formatting over `%`, logging functions are actually equivalent to `str.format()`.
 
 ```python
-version = 3.14
-feature = "t-strings"
-logger.info(t"If you're using Python {version}, prefer {feature} of course!")
+logger.info("If handler level exceeds {}, formatting is {action}", 20, action="skipped")
 ```
 
-Before python-3.14, you can still use lazily evaluated formatting and the elegant and powerful `{}` formatting: Use a str.format() style string and pass the parameters as additional arguments:
+For python-3.14 and higher, you can pass [a template string](https://peps.python.org/pep-0750/), which will be evaluated lazily and is preferable over f-strings:
 
 ```python
-logger.info("If you're using Python {}, prefer {feature} of course!", 3.6, feature="str.format() style strings")
-```
-
-Note that using f-strings in log messages is not considered best practice for performance reasons, as they are evaluated eagerly. Expensive conversion to string might occur even when in the end they are not needed:
-
-```python
-logger.debug(f"obj = {large_obj}") # Do not do this, prefer the above methods!
+feature = "t-string"
+logger.info(t"Modern Pythonistas can enjoy {feature}!")
 ```
 
 ### Exceptions catching within threads or main
diff --git a/loguru/__init__.pyi b/loguru/__init__.pyi
@@ -45,6 +45,13 @@ if sys.version_info >= (3, 8):
 else:
     from typing_extensions import Protocol, TypedDict
 
+if sys.version_info >= (3, 14):
+    import string.templatelib
+
+    LoggedStr = Union[str, string.templatelib.Template]
+else:
+    LoggedStr = str
+
 _T = TypeVar("_T")
 _F = TypeVar("_F", bound=Callable[..., Any])
 ExcInfo = Tuple[Optional[Type[BaseException]], Optional[BaseException], Optional[TracebackType]]
@@ -276,7 +283,7 @@ class Logger:
         onerror: Optional[Callable[[BaseException], None]] = ...,
         exclude: Optional[Union[Type[BaseException], Tuple[Type[BaseException], ...]]] = ...,
         default: Any = ...,
-        message: str = ...
+        message: LoggedStr = ...
     ) -> Catcher: ...
     @overload
     def catch(self, function: _F) -> _F: ...
@@ -344,40 +351,46 @@ class Logger:
         chunk: int = ...
     ) -> Generator[Dict[str, Any], None, None]: ...
     @overload
-    def trace(__self, __message: str, *args: Any, **kwargs: Any) -> None: ...  # noqa: N805
+    def trace(__self, __message: LoggedStr, *args: Any, **kwargs: Any) -> None: ...  # noqa: N805
     @overload
     def trace(__self, __message: Any) -> None: ...  # noqa: N805
     @overload
-    def debug(__self, __message: str, *args: Any, **kwargs: Any) -> None: ...  # noqa: N805
+    def debug(__self, __message: LoggedStr, *args: Any, **kwargs: Any) -> None: ...  # noqa: N805
     @overload
     def debug(__self, __message: Any) -> None: ...  # noqa: N805
     @overload
-    def info(__self, __message: str, *args: Any, **kwargs: Any) -> None: ...  # noqa: N805
+    def info(__self, __message: LoggedStr, *args: Any, **kwargs: Any) -> None: ...  # noqa: N805
     @overload
     def info(__self, __message: Any) -> None: ...  # noqa: N805
     @overload
-    def success(__self, __message: str, *args: Any, **kwargs: Any) -> None: ...  # noqa: N805
+    def success(__self, __message: LoggedStr, *args: Any, **kwargs: Any) -> None: ...  # noqa: N805
     @overload
     def success(__self, __message: Any) -> None: ...  # noqa: N805
     @overload
-    def warning(__self, __message: str, *args: Any, **kwargs: Any) -> None: ...  # noqa: N805
+    def warning(__self, __message: LoggedStr, *args: Any, **kwargs: Any) -> None: ...  # noqa: N805
     @overload
     def warning(__self, __message: Any) -> None: ...  # noqa: N805
     @overload
-    def error(__self, __message: str, *args: Any, **kwargs: Any) -> None: ...  # noqa: N805
+    def error(__self, __message: LoggedStr, *args: Any, **kwargs: Any) -> None: ...  # noqa: N805
     @overload
     def error(__self, __message: Any) -> None: ...  # noqa: N805
     @overload
-    def critical(__self, __message: str, *args: Any, **kwargs: Any) -> None: ...  # noqa: N805
+    def critical(__self, __message: LoggedStr, *args: Any, **kwargs: Any) -> None: ...  # noqa: N805
     @overload
     def critical(__self, __message: Any) -> None: ...  # noqa: N805
     @overload
-    def exception(__self, __message: str, *args: Any, **kwargs: Any) -> None: ...  # noqa: N805
+    def exception(
+        __self, __message: LoggedStr, *args: Any, **kwargs: Any  # noqa: N805
+    ) -> None: ...
     @overload
     def exception(__self, __message: Any) -> None: ...  # noqa: N805
     @overload
     def log(
-        __self, __level: Union[int, str], __message: str, *args: Any, **kwargs: Any  # noqa: N805
+        __self,  # noqa: N805
+        __level: Union[int, str],
+        __message: LoggedStr,
+        *args: Any,
+        **kwargs: Any
     ) -> None: ...
     @overload
     def log(__self, __level: Union[int, str], __message: Any) -> None: ...  # noqa: N805
diff --git a/loguru/_better_exceptions.py b/loguru/_better_exceptions.py
@@ -29,6 +29,21 @@ def is_exception_group(exc):
             return isinstance(exc, ExceptionGroup)
 
 
+def _get_string_tokens():
+    strings = {tokenize.STRING}
+    string_middles = set()
+
+    if sys.version_info >= (3, 12):
+        strings |= {tokenize.FSTRING_START, tokenize.FSTRING_END, tokenize.FSTRING_MIDDLE}
+        string_middles.add(tokenize.FSTRING_MIDDLE)
+
+    if sys.version_info >= (3, 14):
+        strings |= {tokenize.TSTRING_START, tokenize.TSTRING_END, tokenize.TSTRING_MIDDLE}
+        string_middles.add(tokenize.TSTRING_MIDDLE)
+
+    return frozenset(strings), frozenset(string_middles)
+
+
 class SyntaxHighlighter:
     _default_style = frozenset(
         {
@@ -49,14 +64,7 @@ class SyntaxHighlighter:
     _constants = frozenset({"True", "False", "None"})
     _punctuation = frozenset({"(", ")", "[", "]", "{", "}", ":", ",", ";"})
 
-    if sys.version_info >= (3, 12):
-        _strings = frozenset(
-            {tokenize.STRING, tokenize.FSTRING_START, tokenize.FSTRING_MIDDLE, tokenize.FSTRING_END}
-        )
-        _fstring_middle = tokenize.FSTRING_MIDDLE
-    else:
-        _strings = frozenset({tokenize.STRING})
-        _fstring_middle = None
+    _strings, _string_middles = _get_string_tokens()
 
     def __init__(self, style=None):
         self._style = style or dict(self._default_style)
@@ -69,7 +77,7 @@ def highlight(self, source):
         for token in self.tokenize(source):
             type_, string, (start_row, start_column), (_, end_column), line = token
 
-            if type_ == self._fstring_middle:
+            if type_ in self._string_middles:
                 # When an f-string contains "{{" or "}}", they appear as "{" or "}" in the "string"
                 # attribute of the token. However, they do not count in the column position.
                 end_column += string.count("{") + string.count("}")
diff --git a/loguru/_logger.py b/loguru/_logger.py
@@ -136,14 +136,16 @@ def isasyncgenfunction(func):
         return False
 
 
-try:
-    from string.templatelib import Interpolation as _Interpolation
-    from string.templatelib import Template as _Template
-    from string.templatelib import convert as _tmpl_convert
-except ImportError:
-    _Template = None  # type: ignore[assignment,misc]
-    _Interpolation = None  # type: ignore[assignment,misc]
-    _tmpl_convert = None  # type: ignore[assignment,misc]
+if sys.version_info >= (3, 14):
+    from string import templatelib
+
+    def is_template(obj):
+        return isinstance(obj, templatelib.Template)
+
+else:
+
+    def is_template(obj):
+        return False
 
 
 Level = namedtuple("Level", ["name", "no", "color", "icon"])  # noqa: PYI024
@@ -443,7 +445,8 @@ def add(
 
         Note that while calling a logging method, the keyword arguments (if any) are automatically
         added to the ``extra`` dict for convenient contextualization (in addition to being used for
-        formatting).
+        formatting). Also, if the base message is a template string (Python 3.14+), it will first be
+        converted to a regular string.
 
         .. _levels:
 
@@ -2036,22 +2039,16 @@ def _find_iter(fileobj, regex, chunk):
                 yield from matches[:-1]
 
     @staticmethod
-    def _message_to_string(message):
-        """Message can be a string, Any or a Template (for python>=3.14).
-
-        For templates, we convert them into a string analogously to how f-string work.
-        Everything else is just converted to string via str(message).
-        """
-        if _Template is None or not isinstance(message, _Template):
-            return str(message)
+    def _template_to_string(template):
 
-        # Code follows PEP-750 example "implementing f-strings with t-strings"
         def item_to_string(item):
-            if isinstance(item, _Interpolation):
-                return format(_tmpl_convert(item.value, item.conversion), item.format_spec)
+            if isinstance(item, templatelib.Interpolation):
+                if isinstance(item.value, templatelib.Template):
+                    return Logger._template_to_string(item.value)
+                return format(templatelib.convert(item.value, item.conversion), item.format_spec)
             return item
 
-        return "".join(item_to_string(item) for item in message)
+        return "".join(item_to_string(item) for item in template)
 
     def _log(self, level, from_decorator, options, message, args, kwargs):
         core = self._core
@@ -2138,6 +2135,9 @@ def _log(self, level, from_decorator, options, message, args, kwargs):
         else:
             exception = None
 
+        if is_template(message):
+            message = self._template_to_string(message)
+
         log_record = {
             "elapsed": elapsed,
             "exception": exception,
@@ -2146,7 +2146,7 @@ def _log(self, level, from_decorator, options, message, args, kwargs):
             "function": co_name,
             "level": RecordLevel(level_name, level_no, level_icon),
             "line": f_lineno,
-            "message": Logger._message_to_string(message),
+            "message": str(message),
             "module": splitext(file_name)[0],
             "name": name,
             "process": RecordProcess(process.ident, process.name),
diff --git a/tests/exceptions/output/modern/t_string.txt b/tests/exceptions/output/modern/t_string.txt
@@ -0,0 +1,18 @@
+
+[33m[1mTraceback (most recent call last):[0m
+
+  File "[32mtests/exceptions/source/modern/[0m[32m[1mt_string.py[0m", line [33m21[0m, in [35m<module>[0m
+    [1mhello[0m[1m([0m[1m)[0m
+    [36m└ [0m[36m[1m<function hello at 0xDEADBEEF>[0m
+
+  File "[32mtests/exceptions/source/modern/[0m[32m[1mt_string.py[0m", line [33m11[0m, in [35mhello[0m
+    [1moutput[0m [35m[1m=[0m [36mt"[0m[36mHello[0m[36m"[0m [35m[1m+[0m [36mt'[0m[36m [0m[36m'[0m [35m[1m+[0m [36mt"""[0m[36mWorld[0m[36m"""[0m [35m[1mand[0m [1mworld[0m[1m([0m[1m)[0m
+    [36m                                            └ [0m[36m[1m<function world at 0xDEADBEEF>[0m
+
+  File "[32mtests/exceptions/source/modern/[0m[32m[1mt_string.py[0m", line [33m17[0m, in [35mworld[0m
+    [36mt"[0m[1m{[0m[1mname[0m[1m}[0m[36m -> [0m[1m{[0m [1mt[0m [1m}[0m[36m"[0m [35m[1mand[0m [1m{[0m[1m}[0m [35m[1mor[0m [36mt'[0m[36m{{[0m[36m [0m[1m{[0m[1mt[0m [35m[1m/[0m [34m[1m0[0m[1m}[0m[36m }}[0m[36m'[0m
+    [36m   │          │                    └ [0m[36m[1m1[0m
+    [36m   │          └ [0m[36m[1m1[0m
+    [36m   └ [0m[36m[1m'world'[0m
+
+[31m[1mZeroDivisionError[0m:[1m division by zero[0m
diff --git a/tests/exceptions/source/modern/t_string.py b/tests/exceptions/source/modern/t_string.py
@@ -0,0 +1,21 @@
+# fmt: off
+import sys
+
+from loguru import logger
+
+logger.remove()
+logger.add(sys.stderr, format="", colorize=True, backtrace=False, diagnose=True)
+
+
+def hello():
+    output = t"Hello" + t' ' + t"""World""" and world()
+
+
+def world():
+    name = "world"
+    t = 1
+    t"{name} -> { t }" and {} or t'{{ {t / 0} }}'
+
+
+with logger.catch():
+    hello()
diff --git a/tests/test_exceptions_formatting.py b/tests/test_exceptions_formatting.py
@@ -261,6 +261,7 @@ def test_exception_others(filename):
         ("grouped_max_length", (3, 11)),
         ("grouped_max_depth", (3, 11)),
         ("f_string", (3, 12)),  # Available since 3.6 but in 3.12 the lexer for f-string changed.
+        ("t_string", (3, 14)),
     ],
 )
 def test_exception_modern(filename, minimum_python_version):
diff --git a/tests/test_formatting.py b/tests/test_formatting.py
@@ -4,7 +4,6 @@
 import pytest
 
 from loguru import logger
-from loguru._logger import _Interpolation, _Template
 
 
 @pytest.mark.parametrize(
@@ -267,35 +266,3 @@ def test_invalid_format_key_raises_enhanced_error_without_catch(format_, coloriz
     logger.add(lambda msg: None, format=format_, catch=False, colorize=colorize)
     with pytest.raises(ValueError, match=r"Failed to format log record: key 'missing' not found."):
         logger.opt(colors=colors).info("Hello")
-
-
-@pytest.mark.skipif(_Template is None, reason="Template Strings not supported")
-def test_template_string(writer):
-    # We can't just use t"2**8 = {2**8}", because its a syntax error before python-3.14
-    logger.add(writer)
-    logger.info(_Template("2**8 = ", _Interpolation(2**8)))
-    result = writer.read()
-    assert result.endswith("2**8 = 256\n")
-
-
-@pytest.mark.skipif(_Template is None, reason="Template Strings not supported")
-def test_template_string_is_lazy(writer):
-    # We can't just use t"debug = {debug_tracker}", because its a syntax error before python-3.14
-    class StrCalledTracker:
-        def __init__(self):
-            self.str_called = False
-
-        def __str__(self):
-            self.str_called = True
-            return "xxx"
-
-    logger.add(writer, level="INFO")
-    debug_tracker = StrCalledTracker()
-    info_tracker = StrCalledTracker()
-    logger.debug(_Template("debug = ", _Interpolation(debug_tracker)))  # Should be ignored (debug)
-    logger.info(_Template("info = ", _Interpolation(info_tracker)))  # Should be logged (info)
-    result = writer.read()
-    assert len(result.strip().split("\n")) == 1
-    assert result.endswith("info = xxx\n")
-    assert not debug_tracker.str_called
-    assert info_tracker.str_called
diff --git a/tests/test_template_strings.py b/tests/test_template_strings.py
diff --git a/tests/typesafety/test_logger.yml b/tests/typesafety/test_logger.yml

-Original file line number
+Diff line change
@@ @@ -0,0 +1,18 @@ @@
++
 +[33m[1mTraceback (most recent call last):[0m
++
 +  File "[32mtests/exceptions/source/modern/[0m[32m[1mt_string.py[0m", line [33m21[0m, in [35m<module>[0m
 +    [1mhello[0m[1m([0m[1m)[0m
 +    [36m└ [0m[36m[1m<function hello at 0xDEADBEEF>[0m
++
 +  File "[32mtests/exceptions/source/modern/[0m[32m[1mt_string.py[0m", line [33m11[0m, in [35mhello[0m
 +    [1moutput[0m [35m[1m=[0m [36mt"[0m[36mHello[0m[36m"[0m [35m[1m+[0m [36mt'[0m[36m [0m[36m'[0m [35m[1m+[0m [36mt"""[0m[36mWorld[0m[36m"""[0m [35m[1mand[0m [1mworld[0m[1m([0m[1m)[0m
 +    [36m                                            └ [0m[36m[1m<function world at 0xDEADBEEF>[0m
++
 +  File "[32mtests/exceptions/source/modern/[0m[32m[1mt_string.py[0m", line [33m17[0m, in [35mworld[0m
 +    [36mt"[0m[1m{[0m[1mname[0m[1m}[0m[36m -> [0m[1m{[0m [1mt[0m [1m}[0m[36m"[0m [35m[1mand[0m [1m{[0m[1m}[0m [35m[1mor[0m [36mt'[0m[36m{{[0m[36m [0m[1m{[0m[1mt[0m [35m[1m/[0m [34m[1m0[0m[1m}[0m[36m }}[0m[36m'[0m
 +    [36m   │          │                    └ [0m[36m[1m1[0m
 +    [36m   │          └ [0m[36m[1m1[0m
 +    [36m   └ [0m[36m[1m'world'[0m
++
 +[31m[1mZeroDivisionError[0m:[1m division by zero[0m
Original file line number	Diff line number	Diff line change
`@@ -261,6 +261,7 @@ def test_exception_others(filename):`
`261`	`261`	`("grouped_max_length", (3, 11)),`
`262`	`262`	`("grouped_max_depth", (3, 11)),`
`263`	`263`	`("f_string", (3, 12)), # Available since 3.6 but in 3.12 the lexer for f-string changed.`
	`264`	`+ ("t_string", (3, 14)),`
`264`	`265`	`],`
`265`	`266`	`)`
`266`	`267`	`def test_exception_modern(filename, minimum_python_version):`