Structuring Large Applications in Flask with Blueprints and Application Factory
July 12, 2021
There are various techniques adopted by software developers to structure a Flask application. However, when building a small or medium-scale app, the structure of such application might not be of immense importance, especially if using the package structure technique.
In building large applications, the use of package structure in structuring your application will result in a tactless codebase which inevitably results in issues such as circular imports.
To avoid the obstacles resulting in structuring a large application poorly, there are two main techniques used in structuring applications with Flask, which are: Blueprints and Application Factory.
The prerequisites for this article includes an understanding of the following concepts:
- Intermediate usage and implementation of a Flask web app
- Understanding of Object-Oriented Programming concepts with Python
- Understanding of Flask views and templates
- Intermediate knowledge with the use of terminals
- Intermediate understanding of databases
Table of Contents
- Work Environment Setup
- Examining a Basic Flask Application Structure
- Introduction to Blueprints
- Introduction to Application Factory
- Working with Configuration and Environment Variable
- Structuring Applications with Blueprint and Application Factory
Work environment setup
In this tutorial, the use of PyCharm Integrated Development Environment is recommended, because it has all the features required to set up a basic application.
However, if you have a different preference in terms of IDE, then you should consider installing a virtual environment and installing Flask.
To keep the introductory section of this article concise, I won’t cover how to set up a Flask web application. However, if you have no prior knowledge of setting up a Flask web application, read my article on the Flask framework here.
Examining a Basic Flask Application Structure
Before we delve into the structuring of a large-scale Flask application, let’s first understand how a basic Flask application is structured.
To examine the basic structure of a Flask web application, let’s clone this repository here
In the cloned repository, we have the
app.py file, the
static folder, and the
templates folder. The
app.py file consists of the
app route and the
run statement, while the
static folder stores the CSS, JS, and image files we would require in building our web application. The templates folder consists of the HTML files to be rendered to the user.
As an intermediate developer, running this application will result in a “Hello World” statement printed out on your web browser. While this basic application structure suffices for building small-scale applications, what happens if we need to start implementing additional features such as Authentication, Email, Errors, Database, User Profile, and many more as the application demands.
It would prove inefficient to write the code for each feature in the
app folder or to store all the HTML files for each feature in the template directory without appropriate structure, this will result in conflict and it also makes debugging difficult.
To avoid the cons of building large-scale applications with the basic structure of flask, we need to understand Blueprints and Application Factory.
Introduction to Blueprints
Blueprints aid in organizing components of our web applications into distinct components. The definition of Blueprints doesn’t exactly illustrate how it works, let’s take an example with a web application.
In a web application, we have the registration component and the user profile component. We can assign an unique identifier to each component such that any sub-component can be referenced with the unique identifier of their base component.
For example, the registration component can be registered with a Blueprint called ‘Reg’ then any template, views can be accessed via the Blueprint name, and the same thing applies to the user profile component.
The advantage of blueprint over the basic application structure is that the basic application structure utilizes a
view.py file to store all views and routes for the web application.
However, the problem with this is that if we have an index route for both the registration and user profile component, how does Flask know which route to load when the user navigates to either of the components? It doesn’t, but with blueprints, it can.
Blueprint code sample
Let’s go about a step-by-step process of creating a simple blueprint for ‘authentication’.
To create a Blueprint for a particular feature or component, it is a solid design approach to have a short name for it, and in the developer society, authentication is also commonly referred to as ‘auth’.
First, we create a package in our Flask application and name it ‘auth’.
Note that a package has to be initialized with the
__init__.pyfile. We can also add the views and form file, but ensure they are prefixed with the package name, e.g
Next, in the
__init__.py file, we import the blueprint and create a blueprint object with the variable
auth, then below the blueprint object, we import the views, forms, and other files.
auth __init__.py file should look like this:
from flask import Blueprint auth = Blueprint('auth', __name__) from . import auth_forms, auth_views
Now that we have created the blueprint, we need to register them. To register our blueprints, we require the creation of an application factory. So, let’s proceed to an introduction to the application factory.
Introduction to Application Factory
The application factory is a function that wraps the creation of the app object and returns it. This pattern of structuring Flask applications gives the developer the unique flexibility of loading different configuration files for the same application.
Throughout the instantiation and configuration of the Flask application, blueprints and other extensions are handled in a function called the Application Factory function.
The use of this method of instantiating extensions and components of the application ensures that the developer configures the application before instantiating it, which resolves the circular import bug.
Application Factory Code Sample
The application factory takes the form of a function commonly named
create_app. It takes the configuration argument. Then, the body of the function instantiates the flask app and the app configuration.
The application factory function also initializes extension instances with the
init_app method which can be used to initialize the application while taking an argument of the flask application
Note that all extensions required by the application are instantiated in the format above.
Lastly, the final component of the application factory function is the Blueprint registration. Here, we import the individual blueprint components of the application and register them with the
register_ blueprint() method.
Below is the code template of the application factory:
def application_factory_method(config): app = Flask(__name__) #load application configuration from its object app.config.from_object(config) #initialize installed extension instances #as an example, initialize database extension db.init_app(app) db.app = app #as an example, initialize flask mail extension mail.init_app(app) Mail.app = app #register blueprints of applications #from app.blueprint_package import blueprint_object as dummy_name # register blueprint #code sample using the auth blueprint sample from app.auth import auth as auth_bp app.register_blueprint(auth_bp) #return the app object return app
The above is a code template of the implementation of the application factory. In the final section of the article, we will put together all components of the application to understand how large applications are structured in Flask.
Let’s proceed to work with app configuration and environmental variables.
Working with configuration and environmental variables
The configuration variables are required parameters for our application, and they retrieve sensitive information from our environmental variables. Therefore, we need to access the required variables for the scope of the application without loading and setting these variables individually during runtime.
A good analogy for the importance of configuration variables is when we want to run different states of your application. For example, in a production environment, we would need to have Debug set to false, the database uniform resource identifier, and other configuration variables specific to the production environment.
The developer would also like to have unique configuration parameters for a testing environment and a development environment.
Configuration file code sample
When working with configuration parameters for your flask web application, we need to create a
config .py file in the base directory of our web application. In our config file, we will be working with the os package, therefore it has to be imported.
We also need to set the base directory to the absolute path of the path directory name, and this should look like this:
import os basedir = os.path.abspath(os.path.dirname(__name__))
The next step is to create a super class of Config, that inherits the class object.
The Config class is then inherently a base class of the object class which accepts no arguments and returns a new featureless instance that has no instance attributes.
The Config super class takes certain attributes which are the secret key and some database configuration attributes. The secret key attributes will be retrieved from the app environment, this would become clear when we start working with environmental configuration. The config class should look like this:
# Create the super class class Config(object): SECRET_KEY = os.environ.get('SECRET_KEY') SQLALCHEMY_COMMIT_ON_TEARDOWN = True SQLALCHEMY_TRACK_MODIFICATIONS = False
Next, we need to create each config class that inherits the super class config.
In web development, there are three standard configuration class which are the development config, testing config and production config. To save time, the config settings should look like this:
# Create the development config class DevelopmentConfig(Config): DEBUG = True SQLALCHEMY_DATABASE_URI = 'sqlite:///'+os.path.join(basedir, 'dev-data.db') SQLALCHEMY_TRACK_MODIFICATIONS = False MAIL_SERVER = os.environ.get('MAIL_SERVER') MAIL_PORT = os.environ.get('MAIL_PORT') MAIL_USERNAME = os.environ.get('MAIL_USERNAME') MAIL_PASSWORD = os.environ.get('MAIL_PASSWORD') MAIL_USE_TLS = os.environ.get('MAIL_USE_TLS') MAIL_USE_SSL = os.environ.get('MAIL_USE_SSL') # Create the testing config class TestingConfig(Config): DEBUG = False TESTING = True SQLALCHEMY_DATABASE_URI = 'sqlite:///' + os.path.join(basedir, 'test-data.db') SQLALCHEMY_TRACK_MODIFICATIONS = False # create the production config class ProductionConfig(Config): DEBUG = False SQLALCHEMY_DATABASE_URI = 'sqlite:///' + os.path.join(basedir, 'data.db') SQLALCHEMY_TRACK_MODIFICATIONS = False
The above code encapsulates the basic template for configuration files, as the developer, it is at your discretion to decide what goes under each config (production, development, and testing). Let’s proceed to the environmental variables.
Environmental file code sample
The environmental variable file is stored in the base directory of our web application. However, to work with environmental variables, we have to install the python-dotenv extension via pip.
pip install python-dotenv
Once we install the dotenv extension, create a
.env file in the base directory of our application. In the
.env file, we create variable names that will be required by our application and assign them a default value, this way we do not have to assign a value to these environmental variables every time we want to run our web application.
It is also crucial to know that variables that contain sensitive data are best stored in the environment (not readable and accessible by the public). Some of these variables are
MAIL_SERVER and other variables the developer would require.
Below is a sample of a
.env file content:
FLASK_APP = 'run.py' FLASK_ENV = development FLASK_DEBUG = True SECRET_KEY = '2a43ca5b42240a33dadc64beace65d1f' MAIL_SERVER = 'smtp.gmail.com' MAIL_PORT = 465 MAIL_USERNAME = ‘email@example.com' MAIL_PASSWORD = ‘demodeveloperpassword’
We’ve successfully been able to dissect the pieces that would come together to structure a large-scale application. Now, let’s proceed to place the pieces of the puzzle together to structure a demo social network application.
Structuring a large scale application
We now understand the components of structuring a large Flask application. Now, let’s place the pieces together to know how we can structure one.
The process of structuring a large flask application is quite straightforward. All we require are the following:
- The config file
- The .env file
- The features/components of our application
- Use of blueprints
- Implementing blueprints in an application factory
- The run file
We also know how to create a config file and an environmental variable file.
However, let’s cover how to handle the components of our application then couple them with blueprints and the application factory. Lastly, we implement the structure and code the run file.
The components of our application
When building a component of our application or a feature, the first thing we need to do is to create a package for the component.
For example, in a social network web application, we have the user authentication feature; so we create a package for user authentication, which is commonly attributed as
auth in web development.
In our auth package, we can add the views and forms file for this specific feature. It is best practice to use the feature name as a prefix to files within the package. E.g the
views.py for auth will be saved as
auth_views.py this way it eases recognition.
__init__.py file in the auth package, here are the things we need to do:
- Import Blueprint from flask
- Initialize an object of a blueprint and pass in the blueprint name for this specific component which in our case is ‘auth’
- Underneath the object initialization, we import all other components of this package/feature here such as
A complete implementation of this is as follows:
from flask import Blueprint auth = Blueprint('auth', __name__) from . import auth_forms, auth_views, auth_utils
The application factory
After creating components of our application and setting up blueprints, we have to register the blueprints in the application factory method.
In our app folder where we have the
__init__.py file for the application itself, we import all extensions and modules required for our application to function. We also create instances of our extensions installed.
Next, we create an application factory function commonly named
create_app() function takes a config argument from our
config.py file. The following outlines the process on the block of code that goes into the application factory function:
- Create an app variable and initialize Flask
- Load the application configuration as an object from the
config.pypassed into the function
- Initialize extension instances created outside our application factory function
- Register the blueprints
- Return the app variable
The implementation of this logic is as follows:
from flask import Flask from config import DevelopmentConfig from flask_mail import Mail #instances of extensions Mail = Mail() #creating the application factory def create_app(config=DevelopmentConfig): app = Flask(__name__) app.config.from_object(config) #initialization of extension instances mail.init_app(app) mail.app = app # register the authentication blueprint from app.auth import auth as auth_bp app.register_blueprint(auth_bp) return app
The run file
The run file is where we have the code instructions to run our flask application.
Here, we do the following:
- Import the application factory from the app
- Import the application config classes
- Create an instance of the application and pass it to the app variable name
- Create the main block to run the application
The implementation of this code instruction is as follows:
# import the create app application factory from app import create_app # import the application config classes from config import DevelopmentConfig, ProductionConfig, TestingConfig app = create_app() if __name__ == '__main__': app.run()
This article covers all facets of structuring large applications and providing a unique perspective to the individual components. While there isn’t a codebase of this application, I find it a huge learning experience to examine the implementation of this mode of structuring application in a large-scale application.
The GitHub link here consists of a social network flask application structured by me. The goal isn’t for you to run the application, but for you to glean the structure and how the process described in this article knots to the structure of the codebase.
Your goal is to examine how the code connect and create a personal note of yours of how you best understand it, then structure a large application for your personal development.
Peer Review Contributions by: Srishilesh P S