Creating a Simple Flask Web Application

Overview

This blog posts is the first in a series of posts illustrating how I created my Kennedy Family Recipes application using the Flask framework.  This post will show you how to create a simple Flask web application, including setting up a virtual environment, getting the “Hello World!” to display, and getting slightly more advanced with HTML/CSS.

Virtual Environment

I’ve always found it really beneficial to create separate virtual environments for each of the Python projects that I’m working on.  Using the ‘virtualenvwrapper’ package just makes using virtual environments so easy… check out my blog post on Virtual Environments for how to setup ‘virtualenvwrapper’.

To get started, create a new directory in the workspace that you use for developing Python projects:

Next, navigate into that directory and determine where your installation of python3 is located (yes, please use python3! The end of life (EOL) for python2 is rapidly approaching in 2020):

With this information in hand, create a new virtual environment (named ffr_env, as a shortcut for Flask Family Recipes environment) with python3 specified as the version of python to use:

Let’s double-check that python3 is actually the default python interpreter in our virtual environment:

You should now see the ‘ffr_env’ tag to the left of your prompt, which indicates that you are working within the newly created virtual environment:

Since we’re going to be using the Flask framework, it’s a good idea to install the Flask package for the Python Package Index (PyPI) using pip:

This command will install a number of additional packages that Flask is dependent on.  Since we’ve got a decent collection of packages installed, now is a good time to save the configuration of all the Python packages:

This command saves the exact version of each installed Python package to a simple text file.  This is so powerful when you decide to install this project on a production server or if you add a collaborator(s) to your project.  Here’s an example of what my requirements.txt file looks like:

Directory/File Structure

Here is the structure of our project that we will be starting off with:

The ‘project’ directory will be used to store most of the functionality of the application at this point in the development (we’ll be switching to use Blueprints very soon).  The ‘__init__.py’ file in this directory not only indicates to the Python interpreter that this directory is a Python package, but it also creates the instance of the Flask module:

The ‘views.py’ file in the ‘project’ directory is used to store the initial routes for our web application.  This is one of the great parts of Flask; you can easily see how a address for a webpage is linked directly to a function within your application.  To get started, here’s a simple function that just returns the famous “Hello World!” when the user goes to the main address of the site (i.e., ‘/’):

Finally, the ‘run.py’ file in the top-level directory simply calls the run() method for the instance of the Flask module that was created in the ‘__init__.py’ file:

That’s it!  You’ve got everything you need to run a simple Flask web application.  Flask provides a really nice development server to allow you to test your application on your local machine.  Make sure you are in your top-level directory and run the ‘run.py’ file:

You can now open your favorite web browser (Chrome, Safari, etc.) and navigate to either http://127.0.0.1:5000/ or localhost:5000/ (equivalent addresses) to see the “Hello World!” display.

For extra credit, check out what gets written to the console after you navigate to the site:

127.0.0.1 – – [16/Jun/2016 22:13:28] “GET / HTTP/1.1” 200 –

This is showing that you’re executing a HTTP GET request to your web application, which makes sense as you’re getting the “Hello World!” response defined by the index() function in “views.py”.  The console output provides a nice check of what your application is doing at a high-level as you start adding more and more complexity into your application.

Adding HTML/CSS Files

Having the index() function return “Hello World!” is a nice example to get started, but it is unrealistic to have a function return actual text to display…. this process should utilize HTML and CSS files.  If you are unfamiliar with HTML and/or CSS, then I’d highly recommend the HTML/CSS course from Codecademy.  I am still shocked by how much HTML (and to a lesser degree CSS) that I’ve had to written for a web application that I thought I was going to be writing in Python!

In the directory structure from above, I already had the ‘static’ directory listed for storing CSS files and the ‘templates’ directory for storing the HTML-ish files.  The ‘templates’ directory is not called ‘HTML’ as you will actually be creating template files that are based on HTML but can also include Python code.  These template files are then processed by the Jinja2 templating engine to generate the HTML that is sent to the user.  If you check the ‘requirements.txt’ file, you’ll see that Flask includes the Jinja2 module as a dependency as this is a core piece of the Flask framework.

For the first HTML file to create a simple site, create a new file called ‘index.html’ in the templates directory with the following content:

Feel free to change the name of your site to something more applicable to you!  While this looks like a standard HTML file, check out the one line that links in the stylesheet:

This is the first example of including some Python code (the function url_for()) to enhance a basic HTML file for our web application.  The url_for() function provides the URL address for the specified directory/file and the Jinja2 templating engine will use this to generate a standard HTML file.

Just to get started with a simple CSS file, create a new file called ‘main.css’ in the ‘./project/static/css’ folder:

Now that we have the HTML/CSS files in place, we need to update the ‘views.py’ file to actually utilize these files.  The ‘views.py’ file should be changed to:

Instead of just returning “Hello World!”, the index() function is now rendering a HTML page based on the ‘index.html’ template.

As before, make sure you are in your top-level directory and run the ‘run.py’ file:

You should see the following in your web browser when you navigate to http://127.0.0.1:5000/ or localhost:5000/ (refresh the page if you already navigated to here!):

Great first step!

Conclusion

This post illustrated how to set up a virtual environment for a Python project, install the Flask module, get the “Hello World!” application working, and expand to actually utilize HTML/CSS files for generating a page. This is a great start to a Flask web application and we’ll continue to expand on this project in this series.