Flask itself is very flexible. It has no certain pattern for a project folder structure, which is very good for experienced developers to organize things in their own favors. However, people new to Flask will get confused, they need some guide on it, and usually they are going to find something works but not good (or even bad).
I didn't know such a problem until someone reported an issue
to Authlib. And I can't understand the problem either. Then another
person explained it to me with a project structure, I finally got it. I was terrified that lots
of posts, guide, boilerplates are backward importing modules from project root
# project/__init__.pyfrom flask import Flaskfrom flask_sqlalchemy import SQLAlchemydb = SQLAlchemy()def create_app():app = Flask(__name__)db.init_app(app)# project/auth/models.pyfrom .. import dbclass User(db.Model):# define columns
The code itself will work, but when your projects grow, sooner or later you will face a
cyclic dependencies problem. For instance, another extension requires to init with the
# project/__init__.pyfrom flask_sqlalchemy import SQLAlchemyfrom another_extension import AnotherExtensionfrom project.auth.models import Userdb = SQLAlchemy()ext = AnotherExtension(User)
Oops, a cyclic dependency occurs. Because
auth.models is importing
db from the root,
root can not import
User module. This is a common cyclic problem, not limited to Flask.
It is easy to fix, but junior developers may find it very hard. So why not avoid such
thing from the very begining? Actually, if you have read the official documentation,
in application factories
you can find this piece of code:
def create_app(config_filename):app = Flask(__name__)app.config.from_pyfile(config_filename)from yourapplication.model import dbdb.init_app(app)from yourapplication.views.admin import adminfrom yourapplication.views.frontend import frontendapp.register_blueprint(admin)app.register_blueprint(frontend)return app
See, we put
I always keep this one certain rule when writing modules and packages:
Don't backward import from root
That's why I submitted a ticket to Flask as soon as I found this problem. People need a guide on folder structure. And here I'm going to share my suggestions. But think it yourself, don't treat mine as a golden rule.
Functional Based Structure
There are many ways to setup your project folder structure. One is by its function. For instance:
project/ __init__.py models/ __init__.py base.py users.py posts.py ... routes/ __init__.py home.py account.py dashboard.py ... templates/ base.html post.html ... services/ __init__.py google.py mail.py ...
All things are grouped by its function. If it hehaves as a model, put it in models
folder; if it behaves as a route, put it in routes folder. Build a
project/__init__.py, and init_app of everything:
# project/__init__.pyfrom flask import Flaskdef create_app()from . import models, routes, servicesapp = Flask(__name__)models.init_app(app)routes.init_app(app)services.init_app(app)return app
Here is a trick by me. In official documentation,
db of Flask-SQLAlchemy is registered
in this way:
from project.models import dbdb.init_app(app)
So my trick is define a
init_app in every folder's
__init__.py, and unify the init
progress as one:
# project/models/__init__.pyfrom .base import dbdef init_app(app):db.init_app(app)# project/routes/__init__.pyfrom .users import user_bpfrom .posts import posts_bp# ...def init_app(app):app.register_blueprint(user_bp)app.register_blueprint(posts_bp)# ...
App Based Structure
Another famous folder structure is app based structure, which means things are grouped bp application. For instance:
project/ __init__.py db.py auth/ __init__.py route.py models.py templates/ blog/ __init__.py route.py models.py templates/ ...
Each folder is an application. This pattern is used by default in Django. It doesn't mean this pattern is better, you need to choose a folder structure depending on your project. And sometime, you will have to use a mixed pattern.
It is the same as above, we can
# project/__init__.pyfrom flask import Flaskdef create_app()from . import db, auth, blogapp = Flask(__name__)db.init_app(app)auth.init_app(app)blog.init_app(app)return app
Loading configuration would be another issue that many people find difficult, it is also a folder structure problem. I don't know how other people are doing, I'm just sharing my solution.
- Put a
settings.pyin project folder, treat it as static configuration.
- Load configration from environment variable.
- Update configration within
Here is a basic folder structure for configration:
conf/ dev_config.py test_config.py project/ __init__.py settings.py app.py
create_app to load settings and environment variable:
# project/__init__.pyimport osfrom flask import Flaskdef create_app(config=None)app = Flask(__name__)# load default configurationapp.config.from_object('project.settings')# load environment configurationif 'FLASK_CONF' in os.environ:app.config.from_envvar('FLASK_CONF')# load app sepcified configurationif config is not None:if isinstance(config, dict):app.config.update(config)elif config.endswith('.py'):app.config.from_pyfile(config)return app
FLASK_CONF is a python file path which contains configrations. It can
be any name you want, e.g. your project is called Expanse, you can name it as
I use this
FLASK_CONF to load production configurations.
Again, Flask is very flexible, there is no certain patterns. You can always find your favors. These are just my suggestions, do not blind by anyone.
I don't like to write posts like this. But there are so many wrong guide, I hope this post can get a better SEO, so that bad posts don't mislead people.