Structure Flask project with convention over configuration

When people ask me what a should beginner Python developer choose, Flask or Django, to start their new web project, all other things being equal, I always recommend Django.

Unlike Flask, Django is opinionated. In other words, every time you need to make a choice in Flask, Django has the answer for you. Among others, Django outlines the practical project structure out of the box.

With Django, you split your project into applications. The applications themselves have a well-defined structure: views.py, models.py, all those things. What maintains and enforces the design is the convention over configuration approach: you put your code to specific well-known locations, and the framework discovers them.

Flask doesn’t impose anything like that. You can start with a single file. When the application grows, it’s up to you to provide the application structure. As a result, the app can quickly turn into an unmaintainable mess.

Official Flask documentation, following the non-opinionated principle, leaves it for developers to decide. Chapters Larger Applications Modular Applications with Blueprints don’t cover the topic entirely. To close the gap, people created their own guidelines. Google “flask project structure” to find a plethora of variants and suggestions. For example, there is a chapter a better application structure in the monumental Flask Mega-tutorial.

What bugs me about any Flask solution is the lack of support for conventions. If you’re like me, you have a function app() that manually imports and configures all the things from all the packages and blueprints. Looks familiar? This is dirty.

# file: myproject/app.py

def app():
    from myproject.users.controller import blueprint as users_blueprint
    from myproject.projects.controller import blueprint as projects_blueprint
    ...
    # Initialize extensions
    db.init_app(flask_app)

    ...
    # Register blueprints
    flask_app.register_blueprint(users_blueprint)
    flask_app.register_blueprint(projects_blueprint)
    ...

For every extension, you call init_app. For every application with a well-defined structure, you make a dance, adding a couple of lines with imports and registrations.

To somehow address the issue, I created a Python package roman-discovery. The package lets you declaratively define the conventions of your application and run a discover() function to apply their rules. It's not specific to Flask, but I created it primarily with Flask in mind.

For example, assuming that you store all the blueprints in the myproject/<app>/controllers.py, that’s how you can automatically register all of them.

from flask import Blueprint
from roman_discovery import ObjectRule, discover
from roman_discovery.matchers import MatchByPattern, MatchByType

blueprint_loader = ObjectRule(
    name="Flask blueprints loader",
    module_matches=MatchByPattern(["myproject.*.controllers"]),
    object_matches=MatchByType(Blueprint),
    object_action=flask_app.register_blueprint,
)

discover(import_path="myproject", rules=[blueprint_loader])

There is a roman_discovery.flask module you can use as a source of inspiration, or, if you don’t mind applying my conventions, use it as is.

from roman_disovery.flask import discover_flask

app = Flask(__name__)
app.config.from_object("myproject.config")
discover_flask("myproject", app)

The latest line will do the following.

• Scan myproject/*/controllers.py and myproject/*/controllers/*.py to find blueprints and attach them to the Flask application.
• Import all files in myproject/*/models.py and myproject/*/models/*.py to help flask-migrate find all the SQLAlchemy models to create migrations.
• Scan all files in myproject/*/cli.py and myproject/*/cli/*.py to find flask.cli.AppGroup instances and attach them to Flask’s CLI.
• Scan top-level myproject/services.py, find all the instances that have init_app() methods, and call obj.init_app(app=app) for each of them.

It’s still new, lacks documentation, examples, and tests, but I hope it can already become helpful for you.

Follow roman-discovery on GitHub, also to know why the package has an uncommon “roman-” prefix.

imankulov / deescovery

Discover packages and classes in a python project

Deescovery

Micro-framework initialization problem

Micro-framework-based projects are clean while they're small. Every micro-framework codebase I've seen, has a mess in the project initialization. With time, create_app() becomes filled with ad-hoc settings, imports-within-functions, and plug-in initializations.

The Application Factory Pattern, proposed, for example, in the official Flask documentation, and the Flask Mega-Tutorial, legitimize this approach.

The nature of create_app() leaves no place for the open-closed principle. We update this module every time we add a new plug-in, a new blueprint, or a new package.

# myproject/__ini__.py
#
# A common Flask application. The code is based on the Flask Mega-Tutorial.
def create_app(config_class=Config):
    app = Flask(__name__)
    app.config.from_object(config_class)

    db.init_app(app)
    migrate.init_app(app, db)
    login.init_app(app)
    mail.init_app(app)
    bootstrap

…

View on GitHub

Comments

[Roman Imankulov]

Environment variables are the way to go 🚀!

Having a config.py doesn't mean that I don't use environment variables or initialize configuration from secrets. Instead, config provides an abstraction layer that hides the configuration source.

My current preferred setup consists of three files at the top of the project.

• config.py: acts mainly as a proxy to environment variables.
• services.py: a service registry that other parts of the code use heavily.
• app.py: the module with a function initializing the project.

In the app.py, I wrap initialization with a function to avoid accidental initialization on import.

Here's my boilerplate.

imankulov / flask-boilerplate

Flask project boilerplate