Skip to content

Misleading descriptions in the introduce of "Template" #137119

Closed as duplicate
Closed as duplicate
Misleading descriptions in the introduce of "Template"#137119
Labels
docsDocumentation in the Doc dir

Description

@Locked-chess-official
Locked-chess-official
opened on Jul 26, 2025

Documentation

The template can then be combined with functions that operate on the template’s structure to produce a str or a string-like result. For example, sanitizing input:

template = t"<p>{evil}</p>"
assert html(template) == "<p>&lt;script&gt;alert('evil')&lt;/script&gt;</p>"

As another example, generating HTML attributes from data:

template = t"<img {attributes}>"
assert html(template) == '<img src="shrubbery.jpg" alt="looks nice" />'

Compared to using an f-string, the html function has access to template attributes containing the original information: static strings, interpolations, and values from the original scope. Unlike existing templating approaches, t-strings build from the well-known f-string syntax and rules. Template systems thus benefit from Python tooling as they are much closer to the Python language, syntax, scoping, and more.

In PEP-750, the author assumed that you had defined the function html:

For example, imagine we want to generate some HTML. Using template strings, we can define an html() function that allows us to automatically sanitize content:

template = t"<p>{evil}</p>"
assert html(template) == "<p>&lt;script&gt;alert('evil')&lt;/script&gt;</p>"

Likewise, our hypothetical html() function can make it easy for developers to add attributes to HTML elements using a dictionary:

template = t"<img {attributes} />"
assert html(template) == '<img src="shrubbery.jpg" alt="looks nice" />'

However, in the document, the operation "define" was gone, so that some users will mistakenly think that there is a function html that has been defined.

I think that it is better to explain that the function html should be defined by user, like this:

The template can then be combined with functions that operate on the template’s structure to produce a str or a string-like result. For example, sanitizing input (assuming that you have defined a function html that can deal with the input to html):

Activity

  1. Locked-chess-official
    added
    docsDocumentation in the Doc dir
    on Jul 26, 2025
  2. github-project-automation
    added this to docs issueson Jul 26, 2025
  3. github-project-automation
    moved this to Todo in docs issueson Jul 26, 2025
  4. StanFromIreland
    added
    triagedThe issue has been accepted as valid by a triager.
    and removed
    triagedThe issue has been accepted as valid by a triager.
    on Jul 26, 2025

  5. StanFromIreland commented on Jul 26, 2025

    @StanFromIreland
    StanFromIreland
    on Jul 26, 2025
    Member

    cc @davepeck @lysnikolaou @pauleveritt

    I think the example in the What's New (To be clear: I am not talking about the PEP) would be improved if it featured the implementation. For reference, the current text in the What's New 3.14 is:

    The template can then be combined with functions that operate on the template’s structure to produce a str or a string-like result. For example, sanitizing input:

    evil = "<script>alert('evil')</script>"
template = t"<p>{evil}</p>"
assert html(template) == "<p>&lt;script&gt;alert('evil')&lt;/script&gt;</p>"

  6. davepeck commented on Jul 29, 2025

    @davepeck
    davepeck
    on Jul 29, 2025
    Contributor

    Thanks all. I agree that we should probably improve the "What's New" section for 3.14 now that the rest of t-string documentation is starting to take shape. On my "to do" list for the week!

  7. blaisep commented on Jul 30, 2025

    @blaisep
    blaisep
    on Jul 30, 2025
    Contributor

    I find this distinction helpful, along with any others that might illustrate the difference from f-strings

    Compared to using an f-string, the html function has access to template attributes containing the original information: static strings, interpolations, and values from the original scope. Unlike existing templating approaches, t-strings build from the well-known f-string syntax and rules. Template systems thus benefit from Python tooling as they are much closer to the Python language, syntax, scoping, and more.

    In fact, I'm thinking that a two column table would be nice. I realize I may be volunteering, but as much as I dislike tables in .rST, I can give it a go.

  8. pauleveritt commented on Jul 31, 2025

    @pauleveritt
    pauleveritt
    on Jul 31, 2025
    Contributor

    Thanks @blaisep for any help you can give. Feel free to ask me questions. If I don't have the answer, I can find it.

  9. davepeck commented on Jul 31, 2025

    @davepeck
    davepeck
    on Jul 31, 2025
    Contributor

    @blaisep @pauleveritt Just saw your comments here. I've got a first pass at this in this PR but still think it needs some work.

  10. StanFromIreland commented on Nov 24, 2025

    @StanFromIreland
    StanFromIreland
    on Nov 24, 2025
    Member

    It was updated in #139543.

  11. StanFromIreland
    closed this as a duplicateof Implement PEP 750 – Template Strings #132661 on Nov 24, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    docsDocumentation in the Doc dir

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions