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.

# 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