Flask project structure, the right choice to start.

The first and most important decision that you will ever make for your project is how you can organize it.

Also, this is the decision that will lead you to have more or fewer problems in the future, so making it right now will avoid problems for yourself later.

What is the best Flask project structure?

This is a question that you should ask yourself from the beginning, but the problem with this is, what will your project need, is it different from other projects you’ve done already? How can I have one single project structure that will make sure my project will not have a problem, while at the same time will also allow me to improve and keep growing?

The answer is that you don’t have this kind of structure, but, you have one pattern for your structure that will allow you to keep growing and not block and create more problems.

The baseline for any Flask project structure.

1 — Single module structure.

There are 2 basic formats that you can start your project, one is using a Single Module format.

my_project/
    app.py
    config.py
    requirements.txt
    static/
    templates/
    views/

You create one folder, and inside this folder, you create the baseline for your structure.

The entry point will be your “app.py” file, the configuration can be either in your “config.py” file or environment variables. Also, you will have the “requirements.txt” that will have all the dependencies for you to run your project.

At this point, you have all the files that you need to build your project. After you will have the organization level using folders with all the “accessories” files that will allow you to create a specific view and use unique templates which can load any static file that you want to provide.

At this moment you have a full Flask project created and organized, but it’s not scalable if you really intend to grow.

Imagine that you will have 30 or more views, you can imagine that just this would be for example 30 files like this:

views/
    home.py
    about.py
    contact.py
    ....

It’s ok, not that difficult, but, imagine that for each one you will need to create other files inside templates, also, you will need to provide specific static files and images for example.

I guess you can see the problem, just this “single folder structure” will not help you separate and organize it. That’s why for this we have another format, the most used format, and the one you should start with, Package Structure.

2 — Package structure, the baseline.

This is almost the same as the last one, but now with the necessary improvements to allow you to grow or scale.

requirements.txt
setup.py
instance/
    config.py
yourapp/
    __init__.py
    views.py
    models.py
    forms.py
    static/
    templates/

The most important thing for you to notice here is the separation from having an “app.py” as the start point, with all files together, and grouping it in a folder that will transform your files into a package named “yourapp”.

When we move from “app.py” to “folder” we are saying that we are not module anymore but become a package.

Also, you don’t need to have only one package you can have as many as you want.

Flask is smart enough to know when your project is using the “app.py” file and will try to start your project. However, when you move away from it and create your package you will need to tell it how to start using the new package. For this, you use the ‘’setup.py’’

That being said, you still need the information from “app.py”, when you create a package, the “__init__.py” file is the start point now, anything that is necessary for that package to build you will add into the “__init__.py” file.

This already gives us a lot more to grow, but still can be improved and you will see next how big projects are usually organized.

3 — Package structure, the baseline for any big project.

We will start the same as before, but with a big advantage that will allow you to really increase and maintain your project, that is add the Blueprints.

If you don’t know much about it, you can read and learn all about it on this post that I teach all that you need to learn about Blueprints. Link: https://itnext.io/flask-blueprints-complete-tutorial-to-fully-understand-how-to-use-it-767f7433a02e

This is the improved version:

config.py
requirements.txt
run.py
instance/
    config.py
yourapp/
    __init__.py
    views.py
    models.py
    forms.py
    models/
    static/
    templates/
    blueprints/
        home/
           templates/
            __init__.py
            home.py
        user/
            model/
            templates/
            __init__.py
            user.py

The 2 changes that we have here are, first the “models” folder, this is important as you will have models that can be used by the entire project, and should be there.

Second, and most important is the addition of the “blueprints” folder, from now on is how we will organize our project views.

Visually you can see that we split and organize our project by “screens” or “flows”, so for each new “flow” you create one blueprint.

This way we can separate responsibilities, like, having a specific template folder for that flow, model, and anything that is related only to that particular scenario.

Important guidelines to follow.

You can see that we have grown, and each architecture adds something to the next one, but, as the baseline, these are the base requirements for you to start and be able to grow without pain or create a problem for your project.

1 — Always prefer to use packages besides modules, the reason for this is to make it easier to handle paths for your project, it’s easier to decouple.

2 — Use blueprints, this will allow you to grow as much you want make changes all the time and keep your routes running.

3 — Have a proper configuration file, you will need this, to have some server secrets, configurations, and more, for the development environment, use the “.env” pattern, it’s embedded in the Flask framework if you want o know more you can learn how to do it here: https://itnext.io/start-using-env-for-your-flask-project-and-stop-using-environment-variables-for-development-247dc12468be

Conclusion

I hope you enjoyed reading this. If you’d like to support me as a writer, consider signing up to become a Medium member. It’s just $5 a month and you get unlimited access to Medium also if you liked, consider sharing with others that also want to learn more about this.

Also, I started a new channel on YouTube, I want to teach in videos what I write about, so please, subscribe if you liked this tutorial.

Youtube channel:

Linkedin:

Instagram: @thedevproject