January 2, 2013 09:58 pm GMT

An Introduction to Pythons Flask Framework

Flask is a small and powerful web framework for Python. It’s easy to learn and simple to use, enabling you to build your web app in a short amount of time.

In this article, I’ll show you how to build a simple website, containing two static pages with a small amount of dynamic content. While Flask can be used for building complex, database-driven websites, starting with mostly static pages will be useful to introduce a workflow, which we can then generalize to make more complex pages in the future. Upon completion, you’ll be able to use this sequence of steps to jumpstart your next Flask app.

---

Installing Flask

Before getting started, we need to install Flask. Because systems vary, things can sporadically go wrong during these steps. If they do, like we all do, just Google the error message or leave a comment describing the problem.

Install virtualenv

Virtualenv is a useful tool that creates isolated Python development environments where you can do all your development work.

We’ll use virtualenv to install Flask. Virtualenv is a useful tool that creates isolated Python development environments where you can do all your development work. Suppose you come across a new Python library that you’d like to try. If you install it system-wide, there is the risk of messing up other libraries that you might have installed. Instead, use virtualenv to create a sandbox, where you can install and use the library without affecting the rest of your system. You can keep using this sandbox for ongoing development work, or you can simply delete it once you’ve finished using it. Either way, your system remains organized and clutter-free.

It’s possible that your system already has virtualenv. Refer to the command line, and try running:

$ virtualenv --version

If you see a version number, you’re good to go and you can skip to this “Install Flask” section. If the command was not found, use easy_install or pip to install virtualenv. If running Linux or Mac OS X, one of the following should work for you:

$ sudo easy_install virtualenv

or:

$ sudo pip install virtualenv

or:

$ sudo apt-get install python-virtualenv

If you don’t have either of these commands installed, there are several tutorials online, which will show you how to install it on your system. If you’re running Windows, follow the “Installation Instructions” on this page to get easy_install up and running on your computer.

Install Flask

After installing virtualenv, you can create a new isolated development environment, like so:

$ virtualenv flaskapp

Here, virtualenv creates a folder, flaskapp/, and sets up a clean copy of Python inside for you to use. It also installs the handy package manager, pip.

Enter your newly created development environment and activate it so you can begin working within it.

$ cd flaskapp$ . bin/activate

Now, you can safely install Flask:

$ pip install Flask

---

Setting up the Project Structure

Let’s create a couple of folders and files within flaskapp/ to keep our web app organized.

.. app    static       css       img       js    templates    routes.py    README.md

Within flaskapp/, create a folder, app/, to contain all your files. Inside app/, create a folder static/; this is where we’ll put our web app’s images, CSS, and JavaScript files, so create folders for each of those, as demonstrated above. Additionally, create another folder, templates/, to store the app’s web templates. Create an empty Python file routes.py for the application logic, such as URL routing.

And no project is complete without a helpful description, so create a README.md file as well.

Now, we know where to put our project’s assets, but how does everything connect together? Let’s take a look at “Fig. 1″ below to see the big picture:

Fig. 1

1. A user issues a request for a domain’s root URL / to go to its home page
2. routes.py maps the URL / to a Python function
3. The Python function finds a web template living in the templates/ folder.
4. A web template will look in the static/ folder for any images, CSS, or JavaScript files it needs as it renders to HTML
5. Rendered HTML is sent back to routes.py
6. routes.py sends the HTML back to the browser

We start with a request issued from a web browser. A user types a URL into the address bar. The request hits routes.py, which has code that maps the URL to a function. The function finds a template in the templates/ folder, renders it to HTML, and sends it back to the browser. The function can optionally fetch records from a database and then pass that information on to a web template, but since we’re dealing with mostly static pages in this article, we’ll skip interacting with a database for now.

Now that we know our way around the project structure we set up, let’s get started with making a home page for our web app.

Creating a Home Page

When you write a web app with a couple of pages, it quickly becomes annoying to write the same HTML boilerplate over and over again for each page. Furthermore, what if you need to add a new element to your app, such as a new CSS file? You would have to go into every single page and add it in. This is time consuming and error prone. Wouldn’t it be nice if, instead of repeatedly writing the same HTML boilerplate, you could define your page layout just once, and then use that layout to make new pages with their own content? This is exactly what web templates do!

Web templates are simply text files that contain variables and control flow statements (if..else, for, etc), and end with an .html or .xml extension.

The variables are replaced with your content, when the web template is evaluated. Web templates remove repetition, separate content from design, and make your application easier to maintain. In other, simpler words, web templates are awesome and you should use them! Flask uses the Jinja2 template engine; let’s see how to use it.

As a first step, we’ll define our page layout in a skeleton HTML document layout.html and put it inside the templates/ folder:

app/templates/layout.html

<!DOCTYPE html><html>  <head>    <title>Flask App</title>  </head>  <body>    <header>      <div class="container">        <h1 class="logo">Flask App</h1>      </div>    </header>    <div class="container">      {% block content %}      {% endblock %}    </div>  </body></html>

This is simply a regular HTML file…but what’s going on with the {% block content %}{% endblock %} part? To answer this, let’s create another file home.html:

app/templates/home.html

{% extends "layout.html" %}{% block content %}  <div class="jumbo">    <h1>Welcome to the Flask app<h1>    <h2>This is the home page for the Flask app<h2>  </div>{% endblock %} 

The file layout.html defines an empty block, named content, that a child template can fill in. The file home.html is a child template that inherits the markup from layout.html and fills in the “content” block with its own text. In other words, layout.html defines all of the common elements of your site, while each child template customizes it with its own content.

This all sounds cool, but how do we actually see this page? How can we type a URL in the browser and “visit” home.html? Let’s refer back to Fig. 1. We just created the template home.html and placed it in the templates/ folder. Now, we need to map a URL to it so we can view it in the browser. Let’s open up routes.py and do this:

app/routes.py

from flask import Flask, render_templateapp = Flask(__name__)@app.route('/')def home():  return render_template('home.html')if __name__ == '__main__':  app.run(debug=True)  

That’s it for routes.py. What did we do?

1. First. we imported the Flask class and a function render_template.
2. Next, we created a new instance of the Flask class.
3. We then mapped the URL / to the function home(). Now, when someone visits this URL, the function home() will execute.
4. The function home() uses the Flask function render_template() to render the home.html template we just created from the templates/ folder to the browser.
5. Finally, we use run() to run our app on a local server. We’ll set the debug flag to true, so we can view any applicable error messages if something goes wrong, and so that the local server automatically reloads after we’ve made changes to the code.

We’re finally ready to see the fruits of our labors. Return to the command line, and type:
$ python routes.py[/python]

Visit https://localhost:5000/ in your favorite web browser.