Apps are folders within a Django codebase and are used to organise your projects. In this post we’ll run through how you can structure your Django projects using apps, and how they can make your life easier.
What is an app?
It’s just a folder.
You can create an app by running the following line in the terminal:
python manage.py startapp <my-app-name>
Django will create a folder with the following files:
__init__.pymodels.pyadmin.pyapps.pytests.pyviews.py
You can remove any files don’t need and add files that Django didn’t create automatically (e.g. urls.py )
And that’s it. If you were to create a folder and create those files yourself, it would function exactly the same as if it been created by Django.
python manage.py startapp myappname is just a shortcut.
The difference between a web-application and a Django app
The terminology of apps can be confusing as many developers will use the word “app” to refer to the project as a whole.
In Django, an app refers to a folder of a project, which usually reflects one of the domains of a project.
Do I have to use apps?
No.
Your project will contain one app by default (the folder that contains settings.py but there is nothing stopping you from putting all of your code into that same folder.
Apps are there to make your life easier by organising your code into domains.
What are the rules for naming Django apps?
Apps are folders and folders inside Python projects are modules. Therefore, we must refer to PEP-8’s rules on naming modules for guidance on what to call our apps.
The gist is:
- All lower case
- No hyphens or underscores
- Keep it short
I’m yet to find any guidance about whether single or plural names are preferred, so for now I’ll assume that either goes.
How to Choose your App Structure
Example: a movie theatre
You have been asked to build a web-application for an independent cinema. It should allow customers to browse movies and buy tickets. It must allow also the theatre manager to schedule movies across multiple screens and allow customers to choose their seats when booking.
This is how you might split your codebase into apps:
App 1: Movies
Contains the logic that will allow the user to browse movies and view information about it: genre, director, cast and synopsis.
Possible models:
- Movie
- Actor
- Genre
- Director
- Review
App 2: Scheduling
An app for the cinema manager to schedule movies. It will contain the logic to make sure the manager doesn’t schedule two movies for the same screen at the same time.
Possible models:
- Screen
- Showtime
App 3: Ticketing
An app that will provide the logic for users to purchase tickets. It will receive the available showtimes for each movie from the scheduling app and allow users to select their seats. It will be responsible for ensuring the cinema doesn’t sell more tickets than seats.
Possible models:
- Ticket
- TicketType
- Seat
- Order
App 4: Customers
An app to manage user data.
Possible models:
- Customer
- Profile
- Basket
There are no hard and fast rules about how to divide your codebase into apps.
If you asked a group of developers about how to choose apps for the movie theatre example above, it’s unlikely they will all agree. Some developers may opt for more granularity by using more apps. They may want separate apps for seat allocation or payment processing.
Don’t feel that you need to create lots of apps for the sake of it. If your project is small, you may find you don’t need many apps at all. For example, a blog project may only need one additional app called “blog”. It’s ok for apps to contain lots of URLs, models and views as long as they are all grouped around the same domain.
For example, a blog app may contain models for posts, likes and comments. They should all live in same app as likes and comments are closely linked to posts.
Benefits of using apps
Organised Code
Apps provide an intuitive way to navigate large projects.
A neat way to run tests
The standard command to run tests is python manage.py test.
You might be working on a large project where running every test takes several minutes.
If you’re only interested in a particular subset of tests, you can run them on a per-app basis.
python manage.py movies
This will only run tests for the movies app.
A neat way to run migrations
Similar to tests, you might only want to make or run migrations on one app at a time. Perhaps there’s an app where there are known issues and you don’t want these to get in the way.
The standard command to make migrations is python manage.py makemigrations and python manage.py migrate to run them.
If you’re only interested in the movies app, you can run python manage.py makemigrations movies and python manage.py movies respectively.
Prefix your URLs
With Django, you can add prefixes to all URLs belonging to a given app.
Say every page in the movies app will have /movies/ in the URL.
You could specify this in every single URL in movies.urls
path('movies/all', ...)
path('movies/add', ...)
path('movies/coming-soon', ...)
Or…
You can specify in your root urls that every URL imported from the movies app is to be prefixed with movies, meaning movies.urls will look more like this:
path('all', ...)
path('add', ...)
path('coming-soon', ...)
An organised admin panel
When you use apps to structure your project, Django will automatically organise your apps under headings- one for each app.
The image below shows what admin could look like for our movie theatre example. Which one would you rather work with?
Troubleshooting
The most common cause of app-specific errors is forgetting to register the app.
You might get an error along the lines of No installed app with label '<app-name>'
To fix this, go into settings.py and add your app name to the INSTALLED_APPS list.
Conclusion
Django apps refer to folders of a larger project. They are just folders, nothing more.
Django encourages them to help your organise your projects and group your code by domain.
They can be created using python manage.py startapp <app-name> which is a shortcut to create a folder with some placeholder files like models.py and views.py.
While structuring projects using apps is not mandatory, they provide a clear and intuitive way to structure your project.
Each app should group code belonging to a domain of the project. In a large project like our movie theatre example, you could create apps for movies, scheduling, ticketing and users. For a small blog project, there may just be one app for blog, which is perfectly valid.
Many Django commands can be easily be applied to one app. Running tests and migrations are examples of this.