Welcome to the Discover Flask series …

Series Overview

Visit http://discoverflask.com for the series summary – links to blog posts and videos.


Flask is a micro web framework powered by Python. It’s API is fairly small, making it easy to learn and simple to use. But don’t let this fool you, as it’s powerful enough to support enterprise-level applications handling large amounts of traffic. You can start small with an app contained entirely in one file, then slowly scale up to multiple files and folders in a well-structured manner as your site becomes more and more complex.

It’s an excellent framework to start with, which you’ll be learning in true “Real Python-style”: with hands-on, practical examples that are interesting and fun.

Note: This tutorial was original posted on 01/29/2013. We revamped it and due to the number of changes made, it was decided to “retire” the old tutorial and create an entirely new one. If you are interested in viewing the code and video for the old tutorial, please visit this repo.

Check out the accompanying video.

Requirements

This tutorial assumes you have Python 2.7.x, pip, and virtualenv installed.

Ideally, you should have basic knowledge of the command line or terminal and Python in general. If not, you will learn enough to get by, then as you continue working with Flask, your development skills will advanced as well. If you do want additional help, check out the Real Python series to learn Python and web development from the ground up.

You also need a code editor or IDE such as Sublime Text, gedit, Notepad++, or VIM, etc. If you’re ensure what to use, check out Sublime Text, which is a lightweight, yet powerful cross-platform code editor.

Conventions

  1. All examples in this tutorial utilize a Unix-style prompt: $ python hello-world.py. Remember that the dollar sign is not part of the command, and the equivalent command in Windows is: C:\Sites> python hello-world.py.

  2. All examples are coded in Sublime Text 3.

  3. All examples utilize Python 2.7.7. You can use any version of 2.7.x, though.

  4. Additional requirements and dependency versions are listed in the requirements.txt file found within the Github repo.

Setup

  1. Navigate to a convenient directory, such as the “Desktop” or “Documents” folder
  2. Create a new directory called “flask-intro” to house your project
  3. Activate a virtualenv
  4. Install Flask with Pip $ pip install Flask

Structure

If you’re familiar with Django, web2py, or any other high-level (or full-stack) framework, then you know that each impose a specific structure. Due to it’s minimalist nature, however, Flask does not provide a set structure, which can be difficult for beginners. Fortunately, it’s fairly easy to figure out, especially if you use a single file for the Flask components.

Create the following project structure within the “flask-intro” folder:

1
2
3
4
.
├── app.py
├── static
└── templates

Here, we simply have a single file for our Flask app called app.py and then two folders, “static” and “templates”. The former houses our stylesheets, Javascript files, and images, while the latter is for HTML files. This is a good base to start with. We’re already thinking in terms of front vs. back-end. The app.py will utilize the Model-View-Controller (MVC) design pattern in the back-end to handle requests and dish out responses to the end user.

Put simply, when a request comes in, the controller, which handles our app’s business logic, decides how to handle it.

For example, the controller could communicate directly with a database (like MySQL, SQLite, PostgreSQL, MongoDB, etc.) to obtain the requested data and return a response, via the views, with the appropriate data in the appropriate format (like HTML or JSON). Or perhaps the end user’s request is for a resource that does not exist – in which case the controller will respond with a 404 error.

Starting with this structure will help with scaling your app out into separate files and folders, since there’s already a logical separation between the front and back-end. If you’re unfamiliar with the MVC pattern, read more about it here. Get used to it as almost every web framework utilizes some form of MVC.

Routes

Open your favorite editor and add the following code to your app.py file:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# import the Flask class from the flask module
from flask import Flask, render_template

# create the application object
app = Flask(__name__)

# use decorators to link the function to a url
@app.route('/')
def home():
    return "Hello, World!"  # return a string

@app.route('/welcome')
def welcome():
    return render_template('welcome.html')  # render a template

# start the server with the 'run()' method
if __name__ == '__main__':
    app.run(debug=True)

This is fairly straightforward.

After importing the Flask class, we create (or instantiate) the application object, define the views to respond to requests, then start the server.

The route decorators are used to associate (or map) a URL to a function. The URL / is associated with the home() function, so when the end user requests that URL, the view will respond with a string. Similarly, when the /welcome URL is requested, the view will render the welcome.html template.

In short, the main application object is instantiated which is then used to map URLs to functions.

For a more detailed explanation, read Flask’s quick-start tutorial.

Test

Time for a sanity check. Fire up your development server:

1
$ python app.py

Navigate to http://localhost:5000/. You should see “Hello, World!” staring back at you. Then request the next URL, http://localhost:5000/welcome. You should see, a “TemplateNotFound” error. Why? Because we have not set up our template, welcome.html. Flask is looking for it, but it’s not there. Let’s do that. First, kill the server by pressing CTRL+C from your terminal.

For more on the actual response, check out the video accompanying this post.

Templates

Create a new file in your templates directory called welcome.html. Open this file in your code editor, then add the following HTML:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
<!DOCTYPE html>
<html>
  <head>
    <title>Flask Intro</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
  </head>
  <body>
    <div class="container">
      <h1>Welcome to Flask!</h2>
      <br>
      <p>Click <a href="/">here</a> to go home.</p>
    </div>
  </body>
</html>

Save. Run your server again. What do you see now when you request http://localhost:5000/welcome? Test the link. It works but it’s not very pretty. Let’s change that. This time leave the server running as we make the changes.

Bootstrap

Okay. Let’s utilize those static folders by adding a stylesheet. Have you heard of Bootstrap? If your answer is no, then check out this blog post for details.

Download Bootstrap, then add the bootstrap.min.css and bootstrap.min.js files to your “static” folder.

Update the template:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<!DOCTYPE html>
<html>
  <head>
    <title>Flask Intro</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <link href="static/bootstrap.min.css" rel="stylesheet" media="screen">
  </head>
  <body>
    <div class="container">
      <h1>Welcome to Flask!</h2>
      <br>
      <p>Click <a href="/">here</a> to go home.</p>
    </div>
  </body>
</html>

We just included the CSS stylesheet; we’ll add the Javascript file in a latter tutorial.

Return to your browser.

Remember that we left the server running? Well, when Flask is in debug mode, app.run(debug=True), there’s an auto-reload mechanism that kicks in on code changes. Thus, we can just press refresh in our browser and we should see the new template staring right back at us.

Nice.

Conclusion

What are your initial thoughts? Comment below. Grab the code. Watch the video.

In under thirty minutes, you learned the Flask basics and set the ground work for a larger app. If you’ve worked with Django before, you probably noticed immediately that Flask stays out of your way as you develop, leaving you free to structure and design your app how you see fit. Because of the lack of structure, true beginners may struggle a bit, however it’s an invaluable learning experience that will benefit you in the long run, regardless of whether you continue working with Flask or move on to a higher-level framework.

In the next tutorial we’ll look at adding some dynamic content.

Cheers!

Video

Comments