How to structure Flask applications part 1 - Small Apps

One of the benefits of using Flask is it is straightforward to get an application up and running. When you are first starting, you can create your application with a single file. The structure of the application is left entirely up to the developer.

Starting with a single file application is excellent for new developers; it lowers the learning curve and allows for rapid prototyping of simple ideas. Here is an example from the Flask documentation of a minimal app:

from flask import Flask
app = Flask(__name__)

@app.route('/')
def hello_world():
    return 'Hello, World!'

Unless you are building a simple API, the life of a single file application is a short one. As soon as you want to use a template for HTML, you will move past this stage. It won't be long before you find yourself getting lost or searching around a thousand line file looking for the correct route. Adding a small amount of structure to your application can get you a long way.

The natural path is to separate the data layer from the view layer. Small sites can accomplish this by creating a models.py and routes.py file.

For a small production ready site the file structure might look like this:

AppName
├── config.py
├── requirements.txt
├── test/
└── app/
    └── __init__.py
    └── forms.py
    └── models.py
    └── routes.py
    └── static/
    └── templates/

• config.py - a file to hold our application configuration options for production, development, and testing environments. Common configuration options include SECRET_KEY and SQLALCHEMY_DATABASE_URI
• requirements.txt - a list of the project requirements
• test - a directory to house the tests for the application
• app - this directory holds our application code. The entry point for the application is __init__.py which initializes and configures the application. The routes.py file contains your CRUD actions for pages and will include the logic for generating HTML or JSON requested by the client. Data models and functions to handle business logic are found in models.py. The forms.py file is a collection of forms used by the application. The app folder also contains a template folder for HTML templates.

Having fewer files means there are fewer places for application logic to go. As applications grow, the length of these files can start to feel overwhelming. The routes.py and models.py are especially vulnerable to this. As your application grows further, there are going to be times that you will want to consider restructuring your application again. The addition of more pages will cause the routes file to become bloated with CRUD operations. The influx of CRUD operations then strains the data layer. The models.py file can become a monster to handle. If you start relying heavily on your IDE to understand where a file or function might be, this likely indicates that it is time to reorganize the project.

The next post will show you how to transition past the stage of a small web application. Medium-sized applications tend to have more pages or complex systems in them. Based on the structure we created here in part one, we can make a graceful transition into a larger application.