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.
myproject/*/controllers/*.pyto find blueprints and attach them to the Flask application.
- Import all files in
myproject/*/models/*.pyto help flask-migrate find all the SQLAlchemy models to create migrations.
- Scan all files in
flask.cli.AppGroupinstances 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.