Application Factory Pattern: Starting your Flask Project

When I was first tasked to start a Flask project, I am stumped about what to do. Flask very frequently advertise itself as a simple, lightweight framework for web development in python, which is completely true by the way. But this is where the problem comes in. When I searched ‘How to start a Flask project’ almost every single guide I found shows this single file called app.py.

from flask import Flask

app = Flask(__name__)

@app.route("/")
def hello():
    return "Hello World!"

Yes, with only this piece of code is enough for you to start running your server with flask run command. Many guides use this single file app to showcase the simplicity and the lightness of the framework. But this doesn’t help at all. Where should we put our models, routes, app, tests, etc? How should we structure our programs? Is using this app object is the best way?

The answer is up to you. Unlike django, there isn’t a start project command that will automatically generate all the files you need along with the suggested structure. Flask values the term ‘flexibility’ so much that I find many projects that have completely different structures. The guides often point out each other’s mistakes and calls their ideas as the best practices.

I wont debate on which pattern you should use. In this article I want to discuss about one of the pattern which interests me and is used in my current project. This pattern is also used as an example in the Flask repository itself, so maybe this is the best one. This pattern is called Application Factory Pattern.

The structure

After throwing away things I don’t need in my current project, this is more or less the core file structure that I use. If you search for another guide for Flask Application Factory, you will more or less get the same file structure. The key point here is __init__.py and wsgi.py These files are the core of application factory pattern. Notice that there aren’t any app.py, main.py, or any files like that.

/project
├── /application
│   ├── __init__.py
│   ├── db.py
│   ├── /views
│   ├── /models
└── wsgi.py

The Factory

Now, if you look at the structure I provided above carefully, which files should the factory be written? Maybe you would not guess it, it is in the __init__.py file! Yes, this file which is usually empty now have code written in them, the important ones even. Lets take a look at the code I use in my current project below.

There are 3 types of action that must be done in this factory.

1. Creating the app object. This files still needs to be created yes, as this is the app object itself.
2. Configure your app with environment variable and any settings that you want to change from the default
3. Initialize your plugins, in this code, we have database initialization, CORS configuration, and registering blueprints (app routes).

Why do we need to use factory pattern like this? If we use the first type of code I mentioned, there will be bound to be problems in the long run. The more you develop, the more code you will write. Sooner or later you have to break your codes into several files. So how can these files operate with each other while also referring to the same app object? You have to import your app object around, this prone to many problems like circular imports.

With factory pattern, the application context is set on create_app only. This also enables us use current_app object from flask. This is a proxy that can point to the current application context which keeps track on application-level data. These things prevents us from throwing the app objects around.

The Entry Point

If you are using flask run command, it will automatically detect create_app function in the paths defined. So there is no need for app = create_app().

However, sometimes we need to point directly to the app instance, not a function. For example deploying to Heroku requires the app object in the Procfile file. So what should we do?

The answer is wsgi.py that acts as the entry point. This is where the app is created, so if your deployment requires you to point to the app object, you can find the object inside the wsgi.py file.

Now you are all set to go!