Web pages with Flask

Templates

A template is an HTML file with gaps that Jinja fills in. {{ ... }} prints a value, and {% ... %} runs logic like loops and ifs. Most importantly, Jinja escapes every value it prints in an HTML template, so a name with <script> in it shows as text instead of running.

from flask import Flask, render_template
from jinja2 import DictLoader

app = Flask(__name__)
app.jinja_loader = DictLoader({
    "trails.html": """
<h1>{{ title }}</h1>
{% if trails %}
<ul>
  {% for t in trails %}
  <li>{{ t.name }}: {{ t.km }} km{% if t.km > 10 %} <strong>(long)</strong>{% endif %}</li>
  {% endfor %}
</ul>
{% else %}
<p>No trails yet.</p>
{% endif %}
""",
})

@app.route("/")
def trails():
    data = [{"name": "Fern Hollow", "km": 6}, {"name": "Red Mesa <ridge>", "km": 11}]
    return render_template("trails.html", title="Trails & tips", trails=data)

print(app.test_client().get("/").get_data(as_text=True))

In a real project, templates live as files in a templates/ folder next to the app, and render_template("trails.html", ...) finds them there. Here a DictLoader holds them in a dictionary instead, which behaves the same way.

Look at the output: "Red Mesa <ridge>" came out as Red Mesa <ridge> and "&" as &. You didn't call html.escape; the template did it for you. That's the main reason to use templates for HTML.

One layout for every page: inheritance

Every page of a site shares the same frame: the head, the navigation, the footer. Template inheritance writes that frame once in a base template with named blocks, and each page fills in the blocks it needs:

from flask import Flask, render_template, url_for
from jinja2 import DictLoader

app = Flask(__name__)
app.jinja_loader = DictLoader({
    "base.html": """<!doctype html>
<html lang="en"><head><title>{% block title %}Trail Notes{% endblock %}</title></head>
<body>
<nav><a href="{{ url_for('home') }}">Home</a> <a href="{{ url_for('trail', slug='red-mesa') }}">Red Mesa</a></nav>
<main>{% block content %}{% endblock %}</main>
</body></html>""",
    "home.html": """{% extends "base.html" %}
{% block content %}<h1>Welcome</h1>{% endblock %}""",
    "trail.html": """{% extends "base.html" %}
{% block title %}{{ name }} | Trail Notes{% endblock %}
{% block content %}<h1>{{ name }}</h1>{% endblock %}""",
})

@app.route("/")
def home():
    return render_template("home.html")

@app.route("/trails/<slug>")
def trail(slug):
    return render_template("trail.html", name=slug.replace("-", " ").title())

with app.test_request_context():
    print(url_for("trail", slug="fern-hollow"), url_for("home"))
print(app.test_client().get("/trails/red-mesa").get_data(as_text=True))

{% extends "base.html" %} makes a page start from the base, and each {% block %} replaces the base's version. url_for("trail", slug="red-mesa") builds the address from the view's name and its parameters. If the route changes from /trails/<slug> to /t/<slug>, every link updates by itself, instead of breaking in twenty places.

Error pages and testing

Flask's default 404 page is plain. @app.errorhandler(404) replaces it with your own, but remember to return the status code too, or the browser will think the missing page exists:

@app.errorhandler(404)
def not_found(error):
    return render_template("404.html"), 404

A view can return a tuple of (body, status) like this one, or (body, status, headers).

Testing pages works like testing any function: send a request with the test client, then check the status and the content. Parsing the HTML with Beautiful Soup, as the scraping lesson did, makes checks precise: "the page has three post links" rather than "the text contains the word post". Test the edges as well: an unknown slug, a name with < and & in it, a page with nothing to list.

A Flask project on your own computer

On your own machine, a small Flask project is a folder like this:

trail-notes/
  app.py              # the Flask app and its views
  templates/          # base.html, home.html, post.html, 404.html
  static/             # style.css, images, scripts
  tests/test_pages.py # test-client tests, run with pytest

flask --app app run --debug starts a development server that reloads when you save a file and shows a detailed error page when a view crashes. That error page can run code, so never turn on debug mode on a public server; production apps run behind a real server such as Gunicorn, which a later lesson covers. Stylesheets and images in static/ get their addresses from url_for("static", filename="style.css"), like any other link.

Many tutorials end app.py with if __name__ == "__main__": app.run(debug=True). Inside the academy there's no server to start, so app.run() shows your app's home page under the output instead, through the test client. Your code doesn't need to change:

from flask import Flask

app = Flask(__name__)

@app.route("/")
def home():
    return "<h1>Trail Notes</h1><p>Stories and gear tips from the practice shop.</p>"

if __name__ == "__main__":
    app.run(debug=True)

from flask import Flask, render_template, url_for
from jinja2 import DictLoader

SUMMIT_M = 2741

app = Flask(__name__)
app.jinja_loader = DictLoader({
    "guess.html": """<h1>{{ message }}</h1>
{% if hint %}<p><a href="{{ url_for('guess', meters=hint) }}">Try {{ hint }} m</a></p>{% endif %}
<p><a href="{{ url_for('start') }}">Start again</a></p>""",
})

@app.route("/")
def start():
    return render_template("guess.html", message="How high is Red Mesa? Guess with /guess/<meters>", hint=1500)

@app.route("/guess/<int:meters>")
def guess(meters):
    if meters == SUMMIT_M:
        return render_template("guess.html", message=f"{meters} m is right!", hint=None)
    step = max(1, abs(SUMMIT_M - meters) // 2)
    nxt = meters + step if meters < SUMMIT_M else meters - step
    word = "higher" if meters < SUMMIT_M else "lower"
    return render_template("guess.html", message=f"{meters} m: go {word}", hint=nxt)

client = app.test_client()
path = "/guess/1500"
for _ in range(12):
    page = client.get(path).get_data(as_text=True)
    first_line = page.strip().splitlines()[0]
    print(path, "->", first_line.replace("<h1>", "").replace("</h1>", ""))
    if "right" in page:
        break
    path = page.split('href="')[1].split('"')[0]

import yaml
from jinja2 import DictLoader, Environment, select_autoescape

CONTENT = yaml.safe_load("""
name: Sam Rivera
bio: I build small, useful tools in Python.
projects:
  - title: Pack Train
    slug: pack-train
    summary: A grid arcade game with a saved best score.
    tags: [python, games]
""")

TEMPLATES = {
    "base.html": "<!doctype html><title>{% block title %}{% endblock %}</title><main>{% block body %}{% endblock %}</main>",
    "index.html": "{% extends 'base.html' %}{% block title %}{{ name }}{% endblock %}{% block body %}<h1>{{ name }}</h1>{% endblock %}",
}
env = Environment(loader=DictLoader(TEMPLATES), autoescape=select_autoescape())
print(env.get_template("index.html").render(**CONTENT))
# your code: more content, every page, the site/ folder and the link check