Django Project Structure

Django doesn’t require you to build web applications in any particular way. In fact, billions of electrons have been sacrificed discussing the One Best Way to structure a Django project. We’re all pragmatic programmers here, so we won’t play that game.

Django does, however, have a default way of doing things, and there is a definite underlying logic to it you need to understand to become a professional Django programmer.

The fundamental unit of a Django web application is a Django project. A Django project comprises one or more Django apps (Figure 3.4)

Figure 3.4: Django’s project structure.

A Django app is a self-contained package that should only do one thing. For example, a blog, a membership app or an event calendar. Notice at the bottom of Figure 3.4, there’s an extra package called Django Apps.

This is another case where Django’s logic carries right through the framework—Django itself is a collection of apps, each designed to do one thing. With Django’s built-in apps, they’re all designed to make your life easier, which is a Good Thing.

While the built-in apps are invisible in your project tree, you can see them in your settings.py file:

# ...\myclub_project\myclub_site\myclub_site\settings.py
# partial listing
INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
]

You can see that Django has added several apps to your project automatically. There are also many other built-in Django apps you can add to the INSTALLED_APPS list. When you add your apps to a Django project, you also add a link to the app configuration class to this list.

You can see this logic in what Django has created for you so far. Open up your \myclub_project folder. The folder structure should look something like this:

# ...\my_clubproject
\env_myclub
\myclub_site        <= This is your Django project
    \myclub_site    <= This is a Django app
    db.sqlite3      <= Your project database
    manage.py       <= Django project management utility

Let’s examine these files and folders in more detail:

• The env_myclub folder is where Django stores your virtual environment files. Generally, you should leave everything inside this folder alone.
• The outer myclub_site folder is your Django project. Django created this folder and its contents when you ran the startproject command in the last chapter. Django doesn’t care about the folder name, so you can rename it to something meaningful to you.
• Inside the outer myclub_site folder are two files:
  • db.sqlite3. The database created when you ran the migrate command; and
  • manage.py. A command-line utility for executing Django commands from within your project.
• The inner myclub_site folder is your Django website application. This is the one application that Django creates automatically for you. Because Django is a web framework, it assumes you want a website app.

This should make more sense by now, but I bet there is one thing that’s still a bit confusing—the two myclub_site folders.

A very common complaint from programmers new to Django is how confusing it is to know which folder they should work in when there are two folders named the same. Django is not alone with this convention—Integrated Development Environments (IDEs) like Visual Studio create a project folder and application folder with the same name. But just because it’s common, that doesn’t mean it isn’t confusing.

As I said a moment ago, Django doesn’t care what you name this folder—so let’s commit heresy #3, breaking thirteen years of Django tutorial convention while we are at it, and rename the folder!

Here, we’re renaming it to “myclub_root”.

Once you have made the change, your folder structure should go from this:

\myclub_project
    \myclub_site
        \myclub_site

To this:

\myclub_project
    \myclub_root
        \myclub_site

Now we’ve taken care of that source of confusion, let’s have a look inside the myclub_site website app Django created for us:

# \myclub_project\myclub_root\
\myclub_site
    __init.py__
    asgi.py # Django 3 only
    settings.py
    urls.py
    wsgi.py

Looking closer at these files:

• The __init__.py file tells Python that this folder (your Django app) is a Python package.
• asgi.py enables ASGI compatible web servers to serve your project (Django 3 only).
• settings.py contains the settings for your Django project. Every Django project must have a settings file. By convention, Django puts it in your website app, but it doesn’t have to live there. There are proponents for other structures as I mentioned earlier, but here we’re using the default.
• urls.py contains project-level URL configurations. By default, this contains a single URL pattern for the admin. We will cover more on URLs later in the chapter, and in great detail in Chapter 5.
• wsgi.py enables WSGI compatible web servers to serve your project.

Now that we’ve had a good look at the basic structure of a Django project, it’s time to take the next step and add our own Django app.