t-strings
diff --git a/‎README.md‎
Lines changed: 1 addition & 4 deletions b/‎README.md‎
Lines changed: 1 addition & 4 deletions
diff --git a/‎tdom/escaping.py‎
Lines changed: 27 additions & 49 deletions b/‎tdom/escaping.py‎
Lines changed: 27 additions & 49 deletions
diff --git a/‎tdom/escaping_test.py‎
Lines changed: 41 additions & 0 deletions b/‎tdom/escaping_test.py‎
Lines changed: 41 additions & 0 deletions
diff --git a/‎tdom/format.py‎
Lines changed: 99 additions & 0 deletions b/‎tdom/format.py‎
Lines changed: 99 additions & 0 deletions
diff --git a/‎tdom/format_test.py‎
Lines changed: 99 additions & 0 deletions b/‎tdom/format_test.py‎
Lines changed: 99 additions & 0 deletions
@@ -599,15 +599,12 @@ used internally by the `html()` function but can also be used independently:
 
 ```python
 from string.templatelib import Interpolation
-from tdom.utils import format_interpolation, convert
+from tdom.format import convert
 
 # Test convert function
 assert convert("hello", "s") == "hello"
 assert convert("hello", "r") == "'hello'"
 assert convert(42, None) == 42
-
-# format_interpolation is used internally for custom format specifiers
-# The html() function uses this to implement :safe and :unsafe specifiers
 ```
 
 **`convert()`**: Applies conversion specifiers (`!a`, `!r`, `!s`) to values
 
@@ -1,38 +1,16 @@
 import re
-from string.templatelib import Interpolation
 
-from markupsafe import Markup
+from markupsafe import escape as markup_escape
 
-from .utils import format_interpolation as base_format_interpolation
+escape_html_text = markup_escape  # unify api for test of project
 
 
-def _format_safe(value: object, format_spec: str) -> str:
-    """Use Markup() to mark a value as safe HTML."""
-    assert format_spec == "safe"
-    return Markup(value)
+GT = "&gt;"
+LT = "&lt;"
 
 
-def _format_unsafe(value: object, format_spec: str) -> str:
-    """Convert a value to a plain string, forcing it to be treated as unsafe."""
-    assert format_spec == "unsafe"
-    return str(value)
-
-
-CUSTOM_FORMATTERS = (("safe", _format_safe), ("unsafe", _format_unsafe))
-
-
-def format_interpolation(interpolation: Interpolation) -> object:
-    return base_format_interpolation(
-        interpolation,
-        formatters=CUSTOM_FORMATTERS,
-    )
-
-
-def escape_html_comment(text):
+def escape_html_comment(text: str) -> str:
     """Escape text injected into an HTML comment."""
-    GT = "&gt;"
-    LT = "&lt;"
-
     if not text:
         return text
     # - text must not start with the string ">"
@@ -44,12 +22,9 @@ def escape_html_comment(text):
         text = "-" + GT + text[2:]
 
     # - nor contain the strings "<!--", "-->", or "--!>"
-    if (index := text.find("<!--")) and index != -1:
-        text = text[:index] + LT + text[index + 1]
-    if (index := text.find("-->")) and index != -1:
-        text = text[: index + 2] + GT + text[index + 3]
-    if (index := text.find("--!>")) and index != -1:
-        text = text[: index + 3] + GT + text[index + 4]
+    text = text.replace("<!--", LT + "!--")
+    text = text.replace("-->", "--" + GT)
+    text = text.replace("--!>", "--!" + GT)
 
     # - nor end with the string "<!-".
     if text[-3:] == "<!-":
@@ -58,16 +33,27 @@ def escape_html_comment(text):
     return text
 
 
-def escape_html_style(text):
-    LT = "&lt;"
-    close_str = "</style>"
-    close_str_re = re.compile(close_str, re.I | re.A)
-    replace_str = LT + close_str[1:]
-    return re.sub(close_str_re, replace_str, text)
+STYLE_RES = ((re.compile("</style>", re.I | re.A), LT + "/style>"),)
 
 
-def escape_html_script(text):
+def escape_html_style(text: str) -> str:
+    """Escape text injected into an HTML style element."""
+    for matche_re, replace_text in STYLE_RES:
+        text = re.sub(matche_re, replace_text, text)
+    return text
+
+
+SCRIPT_RES = (
+    (re.compile("<!--", re.I | re.A), "\x3c!--"),
+    (re.compile("<script", re.I | re.A), "\x3cscript"),
+    (re.compile("</script", re.I | re.A), "\x3c/script"),
+)
+
+
+def escape_html_script(text: str) -> str:
     """
+    Escape text injected into an HTML script element.
+
     https://html.spec.whatwg.org/multipage/scripting.html#restrictions-for-contents-of-script-elements
 
     (from link) The easiest and safest way to avoid the rather strange restrictions
@@ -76,15 +62,7 @@ def escape_html_script(text):
     - "<!--" as "\x3c!--"
     - "<script" as "\x3cscript"
     - "</script" as "\x3c/script"`
-
-    This does not make a script *run*; it just tries to prevent accidentally injecting
-    *another* SCRIPT tag into a SCRIPT tag being rendered.
     """
-    match_to_replace = (
-        (re.compile("<!--", re.I | re.A), "\x3c!--"),
-        (re.compile("<script", re.I | re.A), "\x3cscript"),
-        (re.compile("</script", re.I | re.A), "\x3c/script"),
-    )
-    for match_re, replace_text in match_to_replace:
+    for match_re, replace_text in SCRIPT_RES:
         text = re.sub(match_re, replace_text, text)
     return text
@@ -0,0 +1,41 @@
+from .escaping import escape_html_comment, escape_html_script, escape_html_style
+
+
+def test_escape_html_comment_empty() -> None:
+    assert escape_html_comment("") == ""
+
+
+def test_escape_html_comment_no_special() -> None:
+    assert escape_html_comment("This is a comment.") == "This is a comment."
+
+
+def test_escape_html_comment_starts_with_gt() -> None:
+    assert escape_html_comment(">This is a comment.") == "&gt;This is a comment."
+
+
+def test_escape_html_comment_starts_with_dash_gt() -> None:
+    assert escape_html_comment("->This is a comment.") == "-&gt;This is a comment."
+
+
+def test_escape_html_comment_contains_special_strings() -> None:
+    input_text = "This is <!-- a comment --> with --!> special strings."
+    expected_output = "This is &lt;!-- a comment --&gt; with --!&gt; special strings."
+    assert escape_html_comment(input_text) == expected_output
+
+
+def test_escape_html_comment_ends_with_lt_dash() -> None:
+    assert escape_html_comment("This is a comment<!-") == "This is a comment&lt;!-"
+
+
+def test_escape_html_style() -> None:
+    input_text = "body { color: red; }</style> p { font-SIZE: 12px; }</STYLE>"
+    expected_output = (
+        "body { color: red; }&lt;/style> p { font-SIZE: 12px; }&lt;/style>"
+    )
+    assert escape_html_style(input_text) == expected_output
+
+
+def test_escape_html_script() -> None:
+    input_text = "<!-- <script>var a = 1;</script> </SCRIPT>"
+    expected_output = "\x3c!-- \x3cscript>var a = 1;\x3c/script> </script>"
+    assert escape_html_script(input_text) == expected_output
@@ -0,0 +1,99 @@
+import typing as t
+from string.templatelib import Interpolation, Template
+
+
+@t.overload
+def convert[T](value: T, conversion: None) -> T: ...
+
+
+@t.overload
+def convert(value: object, conversion: t.Literal["a", "r", "s"]) -> str: ...
+
+
+def convert[T](value: T, conversion: t.Literal["a", "r", "s"] | None) -> T | str:
+    """
+    Convert a value according to the given conversion specifier.
+
+    In the future, something like this should probably ship with Python itself.
+    """
+    if conversion == "a":
+        return ascii(value)
+    elif conversion == "r":
+        return repr(value)
+    elif conversion == "s":
+        return str(value)
+    else:
+        return value
+
+
+type FormatMatcher = t.Callable[[str], bool]
+"""A predicate function that returns True if a given format specifier matches its criteria."""
+
+type CustomFormatter = t.Callable[[object, str], str]
+"""A function that takes a value and a format specifier and returns a formatted string."""
+
+type MatcherAndFormatter = tuple[str | FormatMatcher, CustomFormatter]
+"""
+A pair of a matcher and its corresponding formatter.
+
+The matcher is used to determine if the formatter should be applied to a given 
+format specifier. If the matcher is a string, it must exactly match the format
+specifier. If it is a FormatMatcher, it is called with the format specifier and
+should return True if the formatter should be used.
+"""
+
+
+def _matcher_matches(matcher: str | FormatMatcher, format_spec: str) -> bool:
+    """Check if a matcher matches a given format specifier."""
+    return matcher == format_spec if isinstance(matcher, str) else matcher(format_spec)
+
+
+def _format_interpolation(
+    value: object,
+    format_spec: str,
+    conversion: t.Literal["a", "r", "s"] | None,
+    *,
+    formatters: t.Sequence[MatcherAndFormatter],
+) -> object:
+    converted = convert(value, conversion)
+    if format_spec:
+        for matcher, formatter in formatters:
+            if _matcher_matches(matcher, format_spec):
+                return formatter(converted, format_spec)
+        return format(converted, format_spec)
+    return converted
+
+
+def format_interpolation(
+    interpolation: Interpolation,
+    *,
+    formatters: t.Sequence[MatcherAndFormatter] = tuple(),
+) -> object:
+    """
+    Format an Interpolation's value according to its format spec and conversion.
+
+    PEP 750 allows t-string processing code to decide whether, and how, to
+    interpret format specifiers. This function takes an optional sequence of
+    (matcher, formatter) pairs. If a matcher returns True for the given format
+    spec, the corresponding formatter is used to format the value. If no
+    matchers match, the default formatting behavior is used.
+
+    Conversions are always applied before formatting.
+    """
+    return _format_interpolation(
+        interpolation.value,
+        interpolation.format_spec,
+        interpolation.conversion,
+        formatters=formatters,
+    )
+
+
+def format_template(template: Template) -> str:
+    """Fully render a template by formatting its interpolations."""
+    parts: list[str] = []
+    for part in template:
+        if isinstance(part, str):
+            parts.append(part)
+        else:
+            parts.append(str(format_interpolation(part)))
+    return "".join(parts)
@@ -0,0 +1,99 @@
+from string.templatelib import Interpolation
+
+from .format import convert, format_interpolation, format_template
+
+
+class Convertible:
+    def __str__(self) -> str:
+        return "Convertible str"
+
+    def __repr__(self) -> str:
+        return "Convertible repr"
+
+
+def test_convert_none():
+    value = Convertible()
+    assert convert(value, None) is value
+
+
+def test_convert_a():
+    value = Convertible()
+    assert convert(value, "a") == "Convertible repr"
+    assert convert("Café", "a") == "'Caf\\xe9'"
+
+
+def test_convert_r():
+    value = Convertible()
+    assert convert(value, "r") == "Convertible repr"
+
+
+def test_convert_s():
+    value = Convertible()
+    assert convert(value, "s") == "Convertible str"
+
+
+def test_format_interpolation_no_formatting():
+    value = Convertible()
+    interp = Interpolation(value, expression="", conversion=None, format_spec="")
+    assert format_interpolation(interp) is value
+
+
+def test_format_interpolation_a():
+    value = Convertible()
+    interp = Interpolation(value, expression="", conversion="a", format_spec="")
+    assert format_interpolation(interp) == "Convertible repr"
+
+
+def test_format_interpolation_r():
+    value = Convertible()
+    interp = Interpolation(value, expression="", conversion="r", format_spec="")
+    assert format_interpolation(interp) == "Convertible repr"
+
+
+def test_format_interpolation_s():
+    value = Convertible()
+    interp = Interpolation(value, expression="", conversion="s", format_spec="")
+    assert format_interpolation(interp) == "Convertible str"
+
+
+def test_format_interpolation_default_formatting():
+    value = 42
+    interp = Interpolation(value, expression="", conversion=None, format_spec="5d")
+    assert format_interpolation(interp) == "   42"
+
+
+def test_format_interpolation_custom_formatter_match_exact():
+    value = 42
+    interp = Interpolation(value, expression="", conversion=None, format_spec="custom")
+
+    def formatter(val: object, spec: str) -> str:
+        return f"formatted-{val}-{spec}"
+
+    assert (
+        format_interpolation(interp, formatters=[("custom", formatter)])
+        == "formatted-42-custom"
+    )
+
+
+def test_format_interpolation_custom_formatter_match_predicate():
+    value = 42
+    interp = Interpolation(
+        value, expression="", conversion=None, format_spec="custom123"
+    )
+
+    def matcher(spec: str) -> bool:
+        return spec.startswith("custom")
+
+    def formatter(val: object, spec: str) -> str:
+        return f"formatted-{val}-{spec}"
+
+    assert (
+        format_interpolation(interp, formatters=[(matcher, formatter)])
+        == "formatted-42-custom123"
+    )
+
+
+def test_format_template():
+    t = t"Value: {42.19:.1f}, Text: {Convertible()!s}, Raw: {Convertible()!r}"
+    result = format_template(t)
+    assert result == "Value: 42.2, Text: Convertible str, Raw: Convertible repr"