This book will include code that is compatible with both Python 2 and Python 3 where possible. Unfortunately, since Python 3 is still relatively new as compared to Python 2, not all third-party packages used in this book are guaranteed to work seamlessly with Python 3. There is a lot of effort being put into making popular open-source libraries compatible with both versions but, at the time of writing, some libraries have still not been ported. For best results, ensure that the version of Python that you have installed on your system is 2.6 or above.

The de-facto Python package installer is pip . We will use it throughout the book to install Flask and other third-party libraries.

If you already have setuptools installed, you can install pip by simply running the following command:

$ sudo easy_install pip

After completing the installation, verify that pip is installed correctly:

$ pip --version
pip 1.2.1 from /usr/lib/python2.7/site-packages/pip-1.2.1-py2.7.egg (python 2.7)

The version numbers are likely to change, so for a definitive guide please consult the official instructions, which can be found at http://www.pip-installer.org/en/latest/installing.html.

Once pip is installed, we can proceed to install the most important tool in any Python developer's toolkit: virtualenv. Virtualenv makes it easy to produce isolated Python environments, complete with their own copies of system and third-party packages.

$ sudo pip install virtualenv
$ virtualenv --version
1.10.1

Now that we've verified that our virtualenv is set up correctly, we can install Flask.

When you are inside a virtualenv, you should never install packages with administrator privileges. If you receive a permission error when attempting to install Flask, double-check that you have activated your virtualenv correctly (you should see (hello_flask) in your command prompt).

(hello_flask) $ pip install Flask

You will see some text scroll by as pip downloads the Flask package and the related dependencies before installing it into your virtualenv. Flask depends on a couple of additional third-party libraries, which pip will automatically download and install for you. Let's verify that everything is installed properly:

(hello_flask) $ python
>>> import flask
>>> flask.__version__
'0.10.1'
>>> flask
<module 'flask' from '/home/charles/projects/hello_flask/lib/python2.7/site-packages/flask/__init__.pyc'>

Congratulations! You've installed Flask and now we are ready to start coding.

Create a new file in the hello_flask virtualenv named app.py. Using your favorite text editor or IDE, enter the following code:

from flask import Flask

app = Flask(__name__)

@app.route('/')
def index():
    return 'Hello, Flask!'

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

Save the file and then execute app.py by running it from the command line. You will need to ensure that you have activated the hello_flask virtualenv:

$ cd ~/projects/hello_flask
(hello_flask) $ python app.py
* Running on http://127.0.0.1:5000/

Open your favorite web-browser and navigate to the URL displayed (http://127.0.0.1:5000). You should see the message Hello, Flask! displayed on a blank white page. By default, the Flask development server runs locally on 127.0.0.1, bound to port 5000.

Your first Flask app.

We just created a very basic Flask app. To understand what's happening let's take this code apart line-by-line.

from flask import Flask

Our app begins by importing the Flask class. This class represents a single WSGI application and is the central object in any Flask project.

WSGI is the Python standard web server interface, defined in PEP 333. You can think of WSGI as a set of behaviors and methods that, when implemented, allow your web app to just work with a large number of webservers. Flask handles all the implementation details for you, so you can focus on writing you web app.

app = Flask(__name__)

In this line, we create an application instance in the variable app and pass it the name of our module. The variable app can of course be anything, however app is a common convention for most Flask applications. The application instance is the central registry for things such as views, URL routes, template configuration, and much more. We provide the name of the current module so that the application is able to find resources by looking inside the current folder. This will be important later when we want to render templates or serve static files.

@app.route('/')
def index():
    return 'Hello, Flask!'

In the preceding lines, we are instructing our Flask app to route all requests for / (the root URL) to this view function (index). A view is simply a function or a method that returns a response of some kind. Whenever you open a browser and navigate to the root URL of our app, Flask will call this view function and send the return value to the browser.

There are a few things to note about these lines of code:

Right now our Flask app isn't much fun, so let's look at the different ways in which we can add more interesting behavior to our web app. One common way is to add responsive behavior so that our app will look at values in the URL and handle them. Let's add a new route to our Hello Flask app called hello. This new route will display a greeting to the person whose name appears in the URL:

from flask import Flask

app = Flask(__name__)

@app.route('/')
def index():
    return 'Hello, Flask!'

@app.route('/hello/<name>')
def hello(name):
    return 'Hello, %s' % name

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

Again, let's run our app and open it up in a web browser. We can now navigate to a URL such as http://127.0.0.1/hello/Charlie and see our custom message:

Our Flask app displaying a custom message

In the preceding example, the route we added specifies a single parameter: name. This parameter also appears in the function declaration as the sole argument. Flask is automatically matching the URL /hello/Charlie to the hello view; this is known as mapping. It then passes the string Charlie into our view function as an argument.

What happens if we navigate to http://127.0.0.1:5000/hello/ without specifying a name? As you can see, the Flask development server will return a 404 response, indicating that the URL did not match any known routes.

Flask 404 page

Reading values from the request

In addition to the URL, values can be passed to your app in the query string. The query string is made up of arbitrary keys and values that are tacked onto the URL, using a question-mark:

URL	Argument Values
/hello/?name=Charlie	name: Charlie
/hello/?name=Charlie&favorite_color=green	name: Charlie favorite_color: green

In order to access these values inside your view functions, Flask provides a request object that encapsulates all sorts of information about the current HTTP request. In the following example, we will modify our hello view to also respond to names passed in via the query string. If no name is specified either on the query-string or in the URL, we will return a 404.

from flask import Flask, abort, request

app = Flask(__name__)

@app.route('/')
def index():
    return 'Hello, Flask!'

@app.route('/hello/<name>')
@app.route('/hello/')
def hello(name=None):
    if name is None:
        # If no name is specified in the URL, attempt to retrieve it
        # from the query string.
        name = request.args.get('name')
        if name:
            return 'Hello, %s' % name
    else:
        # No name was specified in the URL or the query string.
        abort(404)

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

As you can see, we have added another route decorator to our hello view: Flask allows you to map multiple URL routes to the same view. Because our new route does not contain a name parameter, we need to modify the argument signature of our view function to make name an optional parameter, which we accomplish by providing a default value of None.

The function body of our view has also been modified to check for the presence of a name in the URL. If no name is specified, we will abort with a 404 page not found status code.

Greet someone using the query string

It is inevitable that, sooner or later, we will introduce a bug into our code. Since bugs are inevitable, the best thing we can hope for as developers is good tools that help us diagnose and fix bugs quickly. Luckily, Flask comes bundled with an extremely powerful web-based debugger. The Flask debugger makes it possible to introspect the state of your application the moment an error occurs, removing the need to sprinkle in print statements or breakpoints.

This can be enabled by telling the Flask app to run in debug mode at run time. We can do this in a few ways but we have actually already done this through the following code:

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

In order to try it out, let's introduce a bug to the hello_flask app by creating a typo. Here I have simply deleted the trailing e from the variable name:

@app.route('/hello/<name>')
@app.route('/hello/')
def hello(name=None):
    if nam is None:
        # No name was specified in the URL or the query string.
        abort(404)

When we fire up the development server and attempt to access our view, we are now presented with the debugging page:

The Flask interactive debugger running in a web browser

This list of code is called a Traceback and it is made up of the call stack, the nested list of function calls that preceded the actual error. The traceback usually provides a very good clue as to what may have happened. At the very bottom we see the line of code we intentionally mistyped along with the actual Python error, which is a NameError exception telling us that nam is not defined.

Traceback detail showing our typo and a description of the error

The real magic happens when you place your mouse on the highlighted line with the mouse. On the right-hand side you will see two small icons representing a terminal and a source code file. Clicking the Source Code icon will expand the source code surrounding the line that contained the error. This is very useful for establishing some context when interpreting an error.

The terminal icon is the most interesting. When you click the Terminal icon, a small console appears with the standard Python prompt. This prompt allows you to inspect, in real-time, the values of the local variables at the time of the exception. Try typing in name and hitting Enter—it should display the value, if any, that was specified in the URL. We can also introspect the current request arguments as follows:

Introspecting variables using the debugging console

As you work through the chapters and experiment on your own, being able to quickly diagnose and correct any bugs will be an extremely valuable skill. We will return to the interactive debugger in Chapter 8, Testing Flask Apps but, for now, be aware that it exists and can be used to introspect your code when and where it breaks.

It's always a good idea when starting a large project to have a functional specification in mind. For the blogging site, our spec will simply be the list of features that we want our blog to have. These features are based on my experience in building my personal blog:

While this list is not exhaustive, it covers the core functionality of our blogging site and you will hopefully find it both fun and challenging to build. At the end of the book, I will present some ideas for additional features that you might add, but first you need to become comfortable working with Flask. I'm sure you're eager to get started, so let's set up our blogging project.

Let's start by creating a new project within our working directory; on my laptop this is /home/charles/projects, or on a Unix system ~/projects, for short. This is exactly what we did when we created the hello_flask app:

$ cd ~/projects
$ mkdir blog
$ cd blog

We will then need to set up our virtualenv environment. This differs from what we did earlier as this is a more structured way of using virtualenv:

$ virtualenv blog

The next step will be to install Flask into our virtualenv. To do this, we will activate the virtualenv and use pip to install Flask:

$ source blog/bin/activate
(blog) $ pip install Flask

Up until now, all of this should be somewhat familiar to you. However, instead of creating a single file for our app, which we are definitely allowed to do and that makes sense for very small apps, we can also create a new folder named app that will allow us to make our app modular and more logical. Inside that folder, we will create five empty files named __init__.py, app.py, config.py, main.py, and views.py as follows:

mkdir app
touch app/{__init__,app,config,main,views}.py

This last command uses a little trick of your shell to create multiple files with the names within the brackets. If you use version control, you will want to treat the app directory as the root of your repository. The app directory will contain the source code, templates, and static assets for the blog app. If you haven't used version control, now would be a great time to give it a try. Pro Git is a great resource and is available for free at http://git-scm.com/book.

What are these files that we just created? As you will see, each file serves an important purpose. Hopefully their names provide a clue as to their purpose, but here is a brief overview of each module's responsibility:

A barebones Flask app

Let's fill in these files with the minimum amount of code needed to create a runnable Flask app. This will get our project in good shape for the second chapter, in which we'll start working on the code to store and retrieve blog entries from the database.

We will start with the config.py module. This module will contain a Configuration class that instructs Flask that we want to run our app in the DEBUG mode. Add the following two lines of code to the config.py module as follows:

class Configuration(object):
    DEBUG = True

Next we will create our Flask app and instruct it to use the configuration values specified in the config module. Add the following code to the app.py module:

from flask import Flask

from config import Configuration  # import our configuration data.

app = Flask(__name__)
app.config.from_object(Configuration)  # use values from our Configuration object.

The views module will contain a single view mapped to the root URL of the site. Add the following code to views.py:

from app import app

@app.route('/')
def homepage():
    return 'Home page'

As you probably noticed, we are still missing our call to app.run(). We will put that code in main.py, which we will use as the entry-point into our app. Add the following code to the main.py module:

from app import app  # import our Flask app
import views

if __name__ == '__main__':
    app.run()

We do not call app.run(debug=True) because we have already instructed Flask to run our app in the debug mode in the Configuration object.

You can run the app from the command-line by executing the main module as follows:

$ python main.py
 * Running on http://127.0.0.1:5000/
* Restarting with reloader

From humble beginnings...

The import flow

Execution starts when you run python main.py from the command line. The first line of code that the Python interpreter runs into imports the app object from the app module. Now we're inside app.py, which imports Flask and our Configuration object. The rest of the app.py module is read and interpreted, and we're back into main.py again. The second line of main.py imports the views module. Now we're in views.py, which depends on app.py for @app.route and is, in fact, already available from main.py. The URL route and view are registered as the views module is interpreted, and we're back into main.py again. Since we are running main.py directly, the 'if' check will evaluate to True and our app will run.

Import flow when executing main.py