Jinja Templates

import logging
import tempfile
from pathlib import Path

from flask import Flask, render_template, render_template_string

TMP = Path(tempfile.mkdtemp(prefix="bookshelf-templates-"))


def make_app(files, name="bookshelf", **options):
    """Write {relative name: source} under a temp folder and build an app on it."""
    root = TMP / name
    for rel, source in files.items():
        target = root / rel
        target.parent.mkdir(parents=True, exist_ok=True)
        target.write_text(source, encoding="utf-8")
    return Flask(name, template_folder=str(root), **options)


app = make_app({
    "hello.html": "<h1>{{ title }}</h1><p>{{ books|length }} books</p>",
    "fallback.html": "<p>fallback for {{ title }}</p>",
})

with app.test_request_context():
    html = render_template("hello.html", title="Bookshelf", books=["A", "B"])
    assert html == "<h1>Bookshelf</h1><p>2 books</p>"

    # a list picks the first template that exists
    html = render_template(["missing.html", "fallback.html"], title="Bookshelf")
    assert html == "<p>fallback for Bookshelf</p>"

    # a template from a string
    html = render_template_string("<b>{{ n }} copies</b>", n=3)
    assert html == "<b>3 copies</b>"


@app.get("/")
def home():
    return render_template("hello.html", title="Bookshelf", books=[])


reply = app.test_client().get("/")
assert reply.mimetype == "text/html"
assert reply.get_data(as_text=True) == "<h1>Bookshelf</h1><p>0 books</p>"

from markupsafe import Markup, escape

app = make_app({
    "page.html": "<p>{{ comment }}</p><p>{{ comment|safe }}</p><p>{{ trusted }}</p>",
    "note.txt": "{{ comment }} | {{ comment|e }}",
})

hostile = "<script>alert('x')</script>"

with app.test_request_context():
    html = render_template("page.html", comment=hostile, trusted=Markup("<em>fine</em>"))
    assert html.startswith("<p>&lt;script&gt;alert(&#39;x&#39;)&lt;/script&gt;</p>")  # escaped
    assert "<p><script>alert('x')</script></p>" in html                                  # |safe: dangerous
    assert html.endswith("<p><em>fine</em></p>")                                         # Markup: not escaped

    text = render_template("note.txt", comment=hostile)    # .txt is not escaped, only |e is
    assert text.startswith("<script>") and text.endswith("&lt;/script&gt;")

    # Markup.format escapes its arguments, so building HTML from user data stays safe
    snippet = Markup("<b>{}</b>").format(hostile)
    assert snippet == "<b>&lt;script&gt;alert(&#39;x&#39;)&lt;/script&gt;</b>"
    assert escape(snippet) == snippet                       # already safe, not escaped twice

import secrets

from flask import flash, session

app = make_app({
    "ctx.html": (
        "{% import 'helpers.html' as helpers %}"
        "path={{ request.path }}|endpoint={{ request.endpoint }}|"
        "debug={{ config['DEBUG'] }}|user={{ session.get('user', 'anonymous') }}|"
        "g={{ g.theme }}|url={{ url_for('home') }}|"
        "{% for category, text in get_flashed_messages(with_categories=true) %}"
        "{{ category }}:{{ text }};{% endfor %}"
        "|imported={{ helpers.where() }}|local={{ helpers.local_value() }}"
    ),
    "helpers.html": (
        "{% macro where() %}{{ request.path }}{% endmacro %}"
        "{% macro local_value() %}{{ title|default('no title') }}{% endmacro %}"
    ),
})
app.secret_key = secrets.token_hex()  # the real key comes from config, see the configuration page


@app.get("/")
def home():
    from flask import g
    g.theme = "dark"
    session["user"] = "ada"
    flash("Saved", "success")
    return render_template("ctx.html", title="Shown only to the including template")


reply = app.test_client().get("/")
assert reply.get_data(as_text=True) == (
    "path=/|endpoint=home|debug=False|user=ada|g=dark|url=/|success:Saved;|imported=/|local=no title"
)
assert "Cookie" in reply.headers["Vary"]

app = make_app({
    "base.html": (
        "<!doctype html>\n<html lang=\"en\">\n<head>\n"
        "<title>{% block title %}Bookshelf{% endblock %}</title>\n"
        "<link rel=\"stylesheet\" href=\"{{ url_for('static', filename='site.css') }}\">\n"
        "</head>\n<body>\n"
        "<header><a href=\"{{ url_for('home') }}\">Bookshelf</a></header>\n"
        "{% block body %}{% endblock %}\n"
        "{% block scripts %}<script src=\"{{ url_for('static', filename='site.js') }}\"></script>{% endblock %}\n"
        "</body>\n</html>\n"
    ),
    "catalog/base.html": (
        "{% extends 'base.html' %}\n"
        "{% block title %}Catalog - {{ super() }}{% endblock %}\n"
        "{% block body %}<nav>shelves</nav><main>{% block content %}{% endblock %}</main>{% endblock %}"
    ),
    "catalog/list.html": (
        "{% extends 'catalog/base.html' %}\n"
        "{% block content %}<h1>{{ self.title() }}</h1>"
        "<ul>{% for b in books %}<li>{{ b }}</li>{% endfor %}</ul>{% endblock %}\n"
        "{% block scripts %}{{ super() }}<script src=\"{{ url_for('static', filename='list.js') }}\"></script>{% endblock %}"
    ),
})


@app.get("/")
def home():
    return render_template("catalog/list.html", books=["Dune", "Emma & Co"])


html = app.test_client().get("/").get_data(as_text=True)
assert "<title>Catalog - Bookshelf</title>" in html
assert "<nav>shelves</nav><main><h1>Catalog - Bookshelf</h1>" in html
assert "<li>Emma &amp; Co</li>" in html
assert html.index("site.js") < html.index("list.js")      # super() kept the parent's script first
assert 'href="/static/site.css"' in html

app = make_app({
    "_forms.html": (
        "{% macro field(name, label, value='', errors=(), type='text') -%}\n"
        "<div class=\"field{% if errors %} has-error{% endif %}\">"
        "<label for=\"{{ name }}\">{{ label }}</label>"
        "<input id=\"{{ name }}\" name=\"{{ name }}\" type=\"{{ type }}\" value=\"{{ value }}\">"
        "{% for message in errors %}<span class=\"error\">{{ message }}</span>{% endfor %}"
        "</div>\n"
        "{%- endmacro %}\n"
        "{% macro card(title) -%}\n"
        "<section><h2>{{ title }}</h2>{{ caller() }}</section>\n"
        "{%- endmacro %}"
    ),
    "new_book.html": (
        "{% from '_forms.html' import field, card %}\n"
        "{% call card('New book') %}\n"
        "{{ field('title', 'Title', value, errors) }}\n"
        "{{ field('isbn', 'ISBN') }}\n"
        "{% endcall %}\n"
        "{% include 'footer.html' ignore missing %}"
    ),
})

with app.test_request_context():
    html = render_template("new_book.html", value='A "quoted" <title>', errors=["Required"])
    assert 'value="A &#34;quoted&#34; &lt;title&gt;"' in html          # values inside a macro are escaped
    assert '<span class="error">Required</span>' in html
    assert "<section><h2>New book</h2>" in html and html.count('class="field') == 2

from datetime import date, datetime, timezone
from decimal import Decimal

from flask import Blueprint
from jinja2 import pass_context
from markupsafe import Markup

app = make_app({
    "book.html": (
        "{{ price|currency }} | {{ price|currency('GBP') }} | {{ published|time_tag }}\n"
        "{% if due is overdue %}OVERDUE{% else %}on time{% endif %}\n"
        "{{ shelf_label('Fiction') }} | {{ site_name }} | {{ now().year >= 2026 }} | {{ greet() }}"
    ),
})

SYMBOLS = {"EUR": "\u20ac", "GBP": "\u00a3", "USD": "$"}


@app.template_filter()
def currency(amount, code="EUR"):
    return f"{SYMBOLS[code]}{Decimal(amount):,.2f}"


@app.template_filter("time_tag")
def time_tag(day):
    """A semantic <time> element. The attribute and the text are escaped; no script is generated."""
    iso = day.isoformat()
    return Markup('<time datetime="{}">{}</time>').format(iso, day.strftime("%d %b %Y"))


@app.template_test("overdue")
def is_overdue(day):
    return day < date(2026, 10, 7)


@app.template_global()
def shelf_label(name):
    return f"Shelf: {name}"


@app.template_global("now")
def now():
    return datetime.now(timezone.utc)


@app.template_global()
@pass_context
def greet(context):
    # a context function sees the template variables; here the request-independent title
    return f"Hello {context.get('title', 'reader')}"


app.jinja_env.globals["site_name"] = "Bookshelf"     # a constant global

with app.test_request_context():
    html = render_template("book.html", price=1234.5, published=date(2026, 1, 9),
                           due=date(2026, 1, 1), title="Ada")
    assert html.splitlines()[0] == '\u20ac1,234.50 | \u00a31,234.50 | <time datetime="2026-01-09">09 Jan 2026</time>'
    assert html.splitlines()[1] == "OVERDUE"
    assert html.splitlines()[2] == "Shelf: Fiction | Bookshelf | True | Hello Ada"
    # a filter returns plain text and lets autoescaping do its job; Markup.format escapes its arguments
    assert Markup("<b>{}</b>").format("<i>") == "<b>&lt;i&gt;</b>"

# the same registration from a blueprint, available app-wide
bp = Blueprint("ui", __name__)


@bp.app_template_filter()
def shout(value):
    return str(value).upper()        # plain str: autoescaping still applies to the result


app2 = make_app({"s.html": "{{ x|shout }}"}, name="shout")
app2.register_blueprint(bp)
with app2.test_request_context():
    assert render_template("s.html", x="<b>") == "&lt;B&gt;"

from flask import Blueprint, g, request

app = make_app({
    "page.html": "{{ site }}|{{ shelf_count() }}|{{ title }}|{{ area }}",
})
admin = Blueprint("admin", __name__, url_prefix="/admin")
calls = []


@app.context_processor
def inject_site():
    return {"site": "Bookshelf", "title": "from the processor", "area": "public"}


@admin.context_processor
def inject_admin():
    return {"area": "admin"}                      # only for templates rendered by admin views


@admin.app_context_processor
def inject_counter():
    def shelf_count():                           # evaluated lazily, only when called
        calls.append(request.path)
        return 7
    return {"shelf_count": shelf_count}


@app.get("/")
def home():
    return render_template("page.html", title="from the view")


@admin.get("/")
def dashboard():
    return render_template("page.html")


app.register_blueprint(admin)
client = app.test_client()
assert client.get("/").get_data(as_text=True) == "Bookshelf|7|from the view|public"
assert client.get("/admin/").get_data(as_text=True) == "Bookshelf|7|from the processor|admin"
assert calls == ["/", "/admin/"]

from flask import Response, stream_template

app = make_app({
    "report.html": (
        "<h1>{{ title }}</h1>\n"
        "{% for row in rows() %}<p>{{ loop.index }}. {{ row }} ({{ request.args.get('mode', 'full') }})</p>\n{% endfor %}"
    ),
})


def slow_rows():
    for name in ("Dune", "Emma", "Ulysses"):
        yield name


@app.get("/report")
def report():
    return Response(stream_template("report.html", title="Report", rows=slow_rows))


client = app.test_client()
reply = client.get("/report?mode=lazy")
body = reply.get_data(as_text=True)
assert body.startswith("<h1>Report</h1>")
assert "3. Ulysses (lazy)" in body
assert "Content-Length" not in reply.headers

from jinja2 import StrictUndefined, UndefinedError


class StrictFlask(Flask):
    jinja_options = {**Flask.jinja_options, "undefined": StrictUndefined,
                     "trim_blocks": True, "lstrip_blocks": True}


root = TMP / "strict"
root.mkdir(exist_ok=True)
(root / "t.html").write_text("{% if show %}\n  <p>{{ name }}</p>\n{% endif %}\n", encoding="utf-8")
strict = StrictFlask("strict", template_folder=str(root))

with strict.test_request_context():
    assert render_template("t.html", show=True, name="Ada") == "  <p>Ada</p>\n".replace("  ", "  ")
    try:
        render_template("t.html", show=True)             # forgot name
    except UndefinedError as exc:
        assert "'name' is undefined" in str(exc)
    else:
        raise AssertionError("StrictUndefined should have raised")

# auto reload follows debug unless TEMPLATES_AUTO_RELOAD is set
plain = Flask("plain")
assert plain.jinja_env.auto_reload is False
forced = Flask("forced")
forced.config["TEMPLATES_AUTO_RELOAD"] = True
assert forced.jinja_env.auto_reload is True
debugging = Flask("debugging")
debugging.debug = True
assert debugging.jinja_env.auto_reload is True

import io

from flask import Blueprint

bp_root = TMP / "bp_catalog" / "templates"
(bp_root / "catalog").mkdir(parents=True, exist_ok=True)
(bp_root / "catalog" / "list.html").write_text("catalog list", encoding="utf-8")
(bp_root / "shared.html").write_text("from the blueprint", encoding="utf-8")

catalog = Blueprint("catalog", "bp_catalog", root_path=str(bp_root.parent), template_folder="templates")

app = make_app({"shared.html": "from the app"}, name="loading")
app.register_blueprint(catalog)
app.config["EXPLAIN_TEMPLATE_LOADING"] = True

stream = io.StringIO()
handler = logging.StreamHandler(stream)
app.logger.addHandler(handler)
app.logger.setLevel(logging.INFO)

with app.test_request_context():
    assert render_template("catalog/list.html") == "catalog list"       # found in the blueprint folder
    assert render_template("shared.html") == "from the app"             # the application wins a name clash

log = stream.getvalue()
assert "Locating template 'catalog/list.html'" in log
assert "trying loader of blueprint 'catalog'" in log
assert "Warning: multiple loaders returned a match for the template." in log   # shared.html matched twice
app.logger.removeHandler(handler)

# the combined search path, listed by name
names = sorted(app.jinja_env.list_templates())
assert names == ["catalog/list.html", "shared.html"]

from jinja2 import ChoiceLoader, DictLoader


class ThemedFlask(Flask):
    def create_global_jinja_loader(self):
        return ChoiceLoader([super().create_global_jinja_loader(), DictLoader({"theme/footer.html": "theme footer"})])


themed = ThemedFlask("themed", template_folder=str(TMP / "none"))
with themed.test_request_context():
    assert render_template("theme/footer.html") == "theme footer"

import secrets

app = Flask("ssti")
app.config["SECRET_KEY"] = secret = secrets.token_hex(8)    # a stand-in; real keys come from the environment

with app.test_request_context():
    name = "{{ config['SECRET_KEY'] }}"                  # what an attacker sends as ?name=...

    unsafe = render_template_string("Hello " + name)    # WRONG: the data became template code
    assert unsafe == "Hello " + secret

    safe = render_template_string("Hello {{ name }}", name=name)   # RIGHT: data stays data
    assert safe == "Hello {{ config['SECRET_KEY'] }}"

from flask import template_rendered


app = make_app({"detail.html": "<h1>{{ book['title'] }}</h1>"})


@app.get("/books/<int:book_id>")
def detail(book_id):
    return render_template("detail.html", book={"id": book_id, "title": "Dune"})


recorded = []


def record(sender, template, context, **extra):
    recorded.append((template.name, dict(context)))


with template_rendered.connected_to(record, app):
    reply = app.test_client().get("/books/7")

assert reply.status_code == 200
name, context = recorded[0]
assert name == "detail.html" and context["book"]["id"] == 7
assert "request" in context and "g" in context           # the standard context was merged in