Show Python results in a browser with Flask

LessonThis is a lesson restated in new words. Any figure in it is an example from the source, not this desk's record.

Flask is a small Python web framework that serves HTML to a browser, and Jinja is the template tool that inserts Python values into that HTML. The lesson builds the smallest version: an application on local port 5000, a home page that renders one template, and a variable passed into the template so the page shows a value computed on the server. That path is the whole introduction.

Why it matters

A script that computes a result still has to present it. Desktop windows are one route. A web page is the route the lesson prefers, because a browser is already the place people read dashboards. Flask is installed with pip install flask and stays light. The first milestone is a page that exists. The second is a page that contains a live Python value. Later lessons add Ajax so the value can change without a reload. This one stops at the first successful handoff from Python to HTML.

The idea in plain words

A Flask object is the application. Calling its run method starts a local server. The lesson sees the server come up on local address 127.0.0.1, using port 5000. Visiting that address before any route exists shows an empty app, because nothing has been mapped to a URL.

A route is a function plus a decorator. The decorator application.route("/") tells Flask to call that function for the site root. The function returns a rendered template. Flask looks for templates in a folder named templates beside the script. A file home.html placed there can contain ordinary text. Returning render_template("home.html") from the root function makes the browser show that text. The lesson's first file simply contains the words hello world, which is enough to prove the lookup.

Jinja is the step that replaces static text with a server value. If pip did not bring Jinja in with Flask, the lesson installs it as jinja2. In the template, double curly braces around a name mark a hole. In the render call, a keyword argument fills the hole. The Python variable and the template name can differ. The lesson uses a variable called name in Python and the same word inside the braces, and it notes that the template side could be called something else as long as the keyword matches the braces.

How to use it

Create main.py. Import Flask from flask and construct the app with the default name argument. Import render_template from flask as well. Write a function, attach @application.route("/"), and return render_template("home.html", name=name), where name is a Python variable you set in the script. Create a templates directory next to the script, and put home.html in it. Inside the file, write the double-brace placeholder for name, or write plain text first if you only want to test the route.

Run the script. Open http://127.0.0.1:5000/ or the localhost form of the same port. The lesson's check is a refresh after the variable is wired: the page shows the string that Python held. A useful next experiment, which the lesson suggests, is to compute something in Python and pass that result through the same keyword. The template does not calculate. It displays.

What usually goes wrong

The template folder name is templates, plural, and it has to sit beside the application script. A file left in the project root is invisible to render_template, and the route raises a template-not-found error. The string passed to render_template has to match the filename, including the.html suffix.

The brace name and the keyword have to match. A placeholder of name filled by a keyword of title stays blank. The lesson's point about renaming is only that both sides can use any word, provided they use the same word.

Running the app object without a route produces a server that accepts the connection and has nothing to show. That is the first state the lesson hits on purpose. Adding the route and forgetting to restart leaves the browser on the empty server. The value in the page is whatever Python assigned before run was called. This lesson does not update it after startup. A change to the variable requires a new process and a refresh, which is the limitation the next lesson removes.

Questions people ask

Where does the page get served?

On 127.0.0.1 port 5000, the default the lesson sees when the Flask app is run with no custom host or port.

How does a Python value reach the HTML?

render_template takes the filename and keyword arguments. Each keyword fills the double-brace placeholder of the same name in the template.

What belongs in the templates folder?

HTML files the routes render. The lesson starts with home.html containing a hello-world line, then a Jinja placeholder for the name variable.