Pyjo.String.Template - Template string with escaping

from Pyjo.String.Template import t

name = '<script>'

# A t-string of Python 3.14
print(t(t'<p>{name}</p>'))

# The same on any Python
print(t('<p>{name}</p>'))
print(t('<p>{name}</p>', name=name))

# A template in a template is markup
def link_to(text, url):
    return t(t'<a href="{url}">{text}</a>')

print(t(t'<li>{link_to(name, "/user")}</li>'))

Pyjo.String.Template is a template string, a t-string of PEP 750, which renders into Pyjo.String.HTML, escaping the values that it interpolates, unless they are markup. t() wraps a t-string of Python 3.14, and on any Python it takes a string with the fields of str.format(), whose values it finds as a t-string would.

The template has the interface of string.templatelib.Template, its strings, interpolations and values, and it is a string, the rendered one, as Pyjo.String.Mixin makes it: str(template), print and comparisons render it. Interpolation of this module is string.templatelib.Interpolation on Python 3.14, and a class with the same interface on an older Python, so that a t-string and t() have the same interpolations.

import Pyjo.String.Template

from Pyjo.String.Template import Interpolation

# "<p>&lt;script&gt;</p>"
Pyjo.String.Template.new('<p>', Interpolation(name, 'name'), '</p>')

A value is rendered by its type:

  • a template, of Pyjo.String.Template or of Python 3.14: it is rendered as it is, not escaped;

  • markup, an object with the method __html__, as Pyjo.String.HTML, Markup of markupsafe or a template: it is inserted as it is;

  • None: nothing;

  • an iterable, as a list, a Pyjo.Collection or a generator, which is not a string, bytes or a mapping: each of its items by these rules;

  • anything else: it is formatted with format() and escaped.

A conversion (!r, !s, !a) or a format specification (:>10) of the field makes a string of the value, which is escaped.

# "<ul><li>&lt;b&gt;</li><li>&lt;i&gt;</li></ul>"
tags = ['<b>', '<i>']
t(t'<ul>{[t"<li>{tag}</li>" for tag in tags]}</ul>')

A string of t() has no code, so that a string of a user cannot run any: a field is a name, followed by .attribute and [key], as in str.format(), but not by an attribute that starts with _, which would reach the internals of Python. The value of the name is the keyword argument of the name, or the variable of the caller: a local one, a global one or a builtin, as a t-string sees them. A function sees the variables of the functions around it only where it uses them itself, so a variable that only the template uses is passed as a keyword argument.

# "<p>&lt;b&gt;</p>"
t('<p>{user.name}</p>', user=user)

# "<p>&lt;b&gt;</p>"
t('<p>{user[name]}</p>', user={'name': '<b>'})

See also

Pyjoyment, https://mojolicious.org.

Inspired by PEP 750.

Classes

class Pyjo.String.Template.Pyjo_String_Template(*args: str | Interpolation[Any])[source]
template = Pyjo.String.Template.new('<p>', Interpolation(name, 'name'), '</p>')

A template of strings and interpolations, as string.templatelib.Template makes it. Pyjo.String.Template inherits all methods from Pyjo.String.Mixin and implements the following new ones.

property interpolations: tuple[Interpolation[Any], ...][source]
interpolations = template.interpolations

The interpolations of the template.

render() → Pyjo_String_HTML[source]
string = template.render()

Render the template into Pyjo.String.HTML.

property strings: tuple[str, ...][source]
strings = template.strings

The strings of the template, one more than the interpolations: the one before each of them and the one at the end, which can be empty.

to_str() → Pyjo_String_HTML[source]
string = template.to_str()

The rendered template, as render() gives it.

property values: tuple[Any, ...][source]
values = template.values

The values of the interpolations.

Pyjo.String.Template.escape(value: Anything) → str[source]
string = escape(value)

Render a value as an interpolation without a conversion and a format specification, escaping it unless it is markup.

# "&lt;b&gt;<i>"
escape(['<b>', html('<i>')])
Pyjo.String.Template.is_template(value: Anything) → TypeGuard[Iterable[str | Interpolation[Any]]][source]
boolean = is_template(value)

Check if a value is a template, of Pyjo.String.Template or a t-string of Python 3.14.

# True
is_template(t('<p>{name}</p>'))

# False
is_template('<p>{name}</p>')
Pyjo.String.Template.raw(value: Anything) → str[source]
string = raw(value)

Render a value as escape() does, but without escaping it.

# "<b><i>"
raw(['<b>', html('<i>')])
Pyjo.String.Template.t(template: Anything, /, **values: Anything) → Pyjo_String_Template[source]
template = t(t'<p>{name}</p>')
template = t('<p>{name}</p>')
template = t('<p>{name}</p>', name=name)

Construct a new Pyjo.String.Template object from a t-string of Python 3.14, or from a string with the fields of str.format(), whose values are the keyword arguments, or the variables of the caller.