Structuring a Flask Project

Introduction

Flask provides such great flexibility when developing a web application, including the structure of the application. Flask applications can range from a single file to larger projects with multiple Blueprints. In this blog post, I’m going to describe how I like to structure a Flask application using Blueprints and an Application Factory function.

For reference, the project that I created as part of writing this blog post is available on GitLab: Flask User Management Example.

Blueprints

Blueprints allow you to cleanly organize the source code of your Flask application. Each Blueprint encapsulates a significant piece of functionality in your application. For example, I like to have a separate Blueprint for handling the user management of a Flask application.

I like to create a separate package (ie. a directory that includes the __init__.py file) for each Blueprint. For example, here is the structure of the Flask User Management example that contains two Blueprints (recipes and users):

Taking a look at a single Blueprint (users), it encapsulates all of components to handle the user management aspects of the application (defining routes, handling forms, generating templates):

The subfolders for storing the template files may look strange, but this structure (…/blueprint_name/templates/blueprint_name/) is recommended in the Flask documentation. The template directory for each Blueprint gets added to the search path for template files within your Flask application. With this structure, you can define the templates for each Blueprint within the Blueprint, but still import a base template (in …/project/templates/) that gets shared by all the Blueprints. With this structure, the template file for a Blueprint can be accessed using ‘users/login.html’.

In order to create the Blueprint, an object of the Blueprint class gets instantiated in the __init__.py file of the Blueprint folder:

This instantiation of the Blueprint specifies the name of the Blueprint (users) and it specifies the location of the template files within the Blueprint. Additionally, the last line imports the routes created in routes.py.

The users_blueprint that was created in __init__.py is then imported in the routes.py file:

This import allows the routes that are being created in routes.py to be specified with ‘@users_blueprint’:

After creating a Blueprint (and registering it), you can check that the routes are being created successfully by checking the mapping of the URLs to specific functions. The best way to see this is to bring up the Python interpreter with the key Flask components loaded using flask shell:

This shows that the URLs are being mapped correctly to the functions in the Blueprints.

Application Factory

The initialization of a Flask project requires the following steps:

• Creating the Flask application as an instance of the Flask class
• Configuring the Flask application
• Initializing the extensions to be used
• Registering the Blueprints in the project

These steps can be put together in a single function called an Application Factory function (an implementation of the Factory method pattern). In addition to making it clear what steps need to be taken to initialize a Flask application, the Application Factory function allows different Flask applications to be created with different configurations. This flexibility becomes very useful during testing, where the configuration can often be different from development or production.

The Application Factory function is created in the …/project/__init__.py file. To start, import all of the modules (including the Flask extensions) that are needed for the Flask project:

Next, create the instances of each of the Flask extensions without initializing them:

Next, the actual Application Factory function (create_app) is defined:

The function to initialize each Flask extension passes in the Flask application to each extension:

Finally, all of the Blueprints are registered with the Flask application:

After creating the Application Factory function, it gets used in the …/main.py file:

Now the Flask application is ready to run using:

Overall Structure

The overall structure for this project is shown below:

The Blueprints are defined in separate modules in the …/project folder. The Application Factory function is defined in the …/project/__init__.py file. The actual Flask application is then created in …/main.py.

Conclusion

This blog post described how to use Blueprints and an Application Factory function to help structure a Flask project. Blueprints provide a great tool to organize your project into major pieces of functionality. An Application Factory function provides a clean method for creating the Flask application. Put together, these are the two primary ideas that I use to structure a Flask project.