A skill that fascinates me is how far some developers can get in their careers while sidestepping a basic understanding of what they do. I might be a poster child for this phenomenon, as I've somehow managed to fool you (and thousands of others) into thinking I'm qualified enough to write trustworthy tutorials. Thanks for reading, by the way.

I bring up blissful ignorance because of how upsetting I find most Flask tutorials. I'm mostly referring to how Flask is commonly introduced as a super simple framework where all source code and business logic belong in a single file called app.py. If you've ever come across a Flask tutorial with a file named app.py, I'm willing to bet it looked something like this:

from flask import Flask, render_template


app = Flask(__name__)
app.config['FLASK_DEBUG'] = True


@app.route("/")
def home():
    return render_template("index.html")
    

@app.route("/about")
def about():
    return render_template("about.html")
    
    
@app.route("/contact")
def contact():
    return render_template("contact.html")

It's easy to think there's nothing wrong with the example above. It's readable and works fine for an app with three pages... yet therein lies the rub: nobody aspires to learn a web framework for the purpose of building a three-page app. You're going to add more pages... a lot more. You're going to want to pull data from a database. You may even want to handle forms and user logins. If we built an app where all that logic lived in a file called app.py, our app would be as much of a monster as it would be a monument to our ineptitude. Uploading this abomination to a public Github repo is a great way to ensure you never get hired.

Flask's official documentation itself undoubtedly compounds the problem. Instead of guiding users toward best practices, Flask's documentation reads like a distracted child attempting to explain everything in the universe. The Flask community heavily emphasizes the ease of deploying uselessly small apps. It fails to mention that this "micro-framework" can easily scale to build apps as large and feature-heavy as any app -even those built with Django.

Flask's "Application Factory" and "Application Context"

Well-structured web apps separate logic between files and modules, typically with separation of concerns in mind. This seems tricky with Flask at first glance because our app depends on an "app object" that we create via app = Flask(__name__). Separating logic between modules means we'd be importing this app object all over the place, eventually leading to problems like circular imports. The Flask Application Factory refers to a common "pattern" for solving this dilemma.

The reason why the Application Factory is so important has to do with something called Flask's Application Context. Our app's "context" takes the assortment of Python files and modules that make up our app and brings them together so that they see and work with one another. For Flask to recognize the data models we have in models.py, our Blueprints, or anything else, Flask needs to be told that these things exist after the app is "created" with app = Flask(__name__).

Here's Flask's take on Application factories:

If you are already using packages and blueprints for your application (Modular Applications with Blueprints) there are a couple of really nice ways to further improve the experience. A common pattern is creating the application object when the blueprint is imported.

And here's their description of the Application context:

The application context keeps track of the application-level data during a request, CLI command, or other activity. Rather than passing the application around to each function, the current_app and g proxies are accessed instead.

That's not entirely useful if we don't understand what the terminology is referring to. Let's fix that.

Top-Down View of an Application Factory App

Are you the type of person to start an app by first creating an app.py file in our base directory? If so, please stop - this isn't a realistic way to build production-ready applications. When we create an app that follows the "Application Factory" pattern, our app should look like this:

/app
├── /application
│   ├── /static
│   └── /templates
│   ├── __init__.py
│   ├── auth.py
│   ├── forms.py
│   ├── models.py
│   └── routes.py
├── config.py
└── wsgi.py

Notice there's no app.py, main.py, or anything of the sort in our base directory. Instead, the entirety of our app lives in the /application folder, with the creation of our app happening in __init__.py. The init file is where we actually create what's called the Application Factory.

If you're wondering how we deploy an app where the main entry point isn't in the root directory, I'm very proud of you. Yes, our app is being created in application/__init__.py, so a file called wsgi.py simply imports this file to serve as our app gateway. More on that another time.

Initiating Flask in __init__.py

Let's dig into it! We will create an example Flask application that utilizes some common patterns, such as connecting to a database utilizing a Redis store. This is simply for demonstration purposes to show how all globally accessible Flask plugins are initialized in a standard Flask app.

A properly configured Application Factory should accomplish the following:

• Create a Flask app object, which derives configuration values (either from a Python class, a config file, or environment variables).
• Initialize plugins accessible to any part of our app, such as a database (via flask_sqlalchemy), Redis (via flask_redis) or user authentication (via Flask-Login).
• Import the logic which makes up our app (such as routes).
• Register Blueprints.

The below example does all of those things:

from flask import Flask
from flask_sqlalchemy import SQLAlchemy
from flask_redis import FlaskRedis


# Globally accessible libraries
db = SQLAlchemy()
r = FlaskRedis()


def init_app():
    """Initialize the core application."""
    app = Flask(__name__, instance_relative_config=False)
    app.config.from_object('config.Config')
    
    # Initialize Plugins
    db.init_app(app)
    r.init_app(app)

    with app.app_context():
        # Include our Routes
        from . import routes
        
        # Register Blueprints
        app.register_blueprint(auth.auth_bp)
        app.register_blueprint(admin.admin_bp)

        return app

The order of operations here is critical. Let's break it down.

Step 1: Creating Instances of Plugin Objects

The vast majority of Flask applications initialize via a function such as the one above, which I tend to name init_app(). Before we even reach this part, there's work to be done if you plan to utilize any of Flask's vast plugin libraries.

Before init_app() is defined in __init__.py, we create global instances of flask_sqlalchemy and flask_redis. Despite declaring these variables, nothing notable has been defined until we "initialize" these plugins inside the init_app() function - after the Flask app object is created.

from flask import Flask
from flask_sqlalchemy import SQLAlchemy
from flask_redis import FlaskRedis


# Globally accessible libraries
db = SQLAlchemy()
r = FlaskRedis()

...

Step 2: App Creation

The first two lines of init_app() should be no surprise: we're creating our Flask app object and stating that it should be configured using a class called Config in a file named config.py:

...

# Globally accessible libraries
db = SQLAlchemy()
r = FlaskRedis()


def init_app():
    """Initialize the core application."""
    app = Flask(__name__, instance_relative_config=False)
    app.config.from_object('config.Config')

Step 3: Plugin Initialization

After the app object is created, the plugins we defined outside of the init_app() scope can be "initialized." Initializing a plugin makes it visible to our Flask app, presumably via dark magic. Even though plugins are defined as "global variables" outside of init_app(), makes them globally accessible to other parts of our application, we can't use them until after they're initialized:

...

# Globally accessible libraries
db = SQLAlchemy()
r = FlaskRedis()


def init_app():
    """Initialize the core application."""
    app = Flask(__name__, instance_relative_config=False)
    app.config.from_object('config.Config')
    
    # Initialize Plugins
    db.init_app(app)
    r.init_app(app)

Step 4: The Application Context

Now comes the moment of truth: creating the app context. What happens in the app context, stays in the app context... but seriously. Any part of our app that is not imported, initialized, or registered within the with app.app_context(): block effectively does not exist. This block is the lifeblood of our Flask app: it essentially declares "here are all the pieces of my program."

The first thing we do inside the context is import the base parts of our app (any Python files or logic that aren't Blueprints). I've imported routes.py via from . import routes. This file contains the route for my app's home page, so now visiting the app will actually resolve something.

Next, we register Blueprints. Blueprints are "registered" by calling register_blueprint() on our app object and passing the Blueprint module's name, followed by the name of our Blueprint. For example, in app.register_blueprint(auth.auth_bp), I have a file called auth.py which contains a Blueprint named auth_bp.

We finally wrap things up with return app.

...

def init_app():
    ...

    with app.app_context():
        # Include our Routes
        from . import routes
        
        # Register Blueprints
        app.register_blueprint(auth.auth_bp)
        app.register_blueprint(admin.admin_bp)

        return app

Our App's Entry Point

So our function returns app, but what are we returning to, exactly? That's where the mysterious wsgi.py file from earlier comes in. Almost every wsgi.py file looks like this:

from application import init_app


app = init_app()

if __name__ == "__main__":
    app.run(host='0.0.0.0')

Ah ha! Now we have a file in our app's root directory that can serve as our entry point. When setting up a production web server to point to your app, you will almost always configure it to point to wsgi.py, which in turn imports and starts our entire app.