Structure Flask project with convention over configuration
Tags: python, webdev, django, flask
Published: 2021-05-05 08:42:45

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](https://en.wikipedia.org/wiki/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](https://flask.palletsprojects.com/en/1.1.x/patterns/packages/) [Modular Applications with Blueprints](https://flask.palletsprojects.com/en/1.1.x/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](https://blog.miguelgrinberg.com/post/the-flask-mega-tutorial-part-xv-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.

```python
# 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](https://github.com/imankulov/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.

```python
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](https://github.com/imankulov/roman-discovery/blob/main/roman_discovery/flask.py) module you can use as a source of inspiration, or, if you don’t mind applying my conventions, use it as is.

```python
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](https://github.com/imankulov/roman-discovery/), also to know why the package has an uncommon “roman-” prefix.

{% github imankulov/roman-discovery %}