Scaffolding a Django Project and App

Before diving deep into the theory behind Django paradigms and HTTP requests, we'll show you how easy it is to get a Django project up and running. After this first section and exercise, you will have created a Django project, made a request to it with your browser, and seen the response.

A Django project is a directory that contains all the data for your project: code, settings, templates, and assets. It is created and scaffolded by running the django-admin.py command on the command line with the startproject argument and providing the project name. For example, to create a Django project with the name myproject, the command that is run is this:

django-admin.py startproject myproject

This will create the myproject directory, which Django populates with the necessary files to run the project. Inside the myproject directory are two files (shown in Figure 1.1):

Figure 1.1: Project directory for myproject

manage.py is a Python script that is executed at the command line to interact with your project. We will use it to start the Django dev server, a development web server you will use to interact with your Django project on your local computer. Like django-admin.py, commands are passed in on the command line. Unlike django-admin.py, this script is not mapped in your system path, so we must execute it using Python. We will need to use the command line to do that. For example, inside the project directory, run the following command:

python3 manage.py runserver

This passes the runserver command to the manage.py script, which starts the Django dev server. We will examine more of the commands that manage.py accepts in the Django Project section. When interacting with manage.py in this way, we call these management commands. For example, we might say that we are "executing the runserver management command."

The startproject command also created a directory with the same name as the project, in this case, myproject (Figure 1.1). This is a Python package that contains settings and some other configuration files that your project needs to run. We will examine its contents in the Django Project section.

After starting the Django project, the next thing to do is to start a Django app. We should try to segregate our Django project into different apps, grouped by functionality. For example, with Bookr, we will have a reviews app. This will hold all the code, HTML, assets, and database classes specific to working with book reviews. If we decided to expand Bookr to sell books as well, we might add a store application, containing the files for the bookstore. Apps are created with the startapp management command, passing in the application name. For example:

python3 manage.py startapp myapp

This creates the app directory (myapp) inside the project directory. Django automatically populates this with files for the app that are ready to be filled in when you start developing. We'll examine these files and discuss what makes a good app in the Django Apps section.

Now that we've introduced the basic commands to scaffold a Django project and application, let's put them into practice by starting the Bookr project in the first exercise of this book.

Exercise 1.01: Creating a Project and App, and Starting the Dev Server

Throughout this book, we will be building a book review website named Bookr. It will allow you to add fields for publishers, contributors, books, and reviews. A publisher will publish one or more books, and each book will have one or more contributors (author, editor, co-author, and so on). Only admin users will be allowed to modify these fields. Once a user has signed up for an account on the site, they will be able to start adding reviews to a book.

In this exercise, you will scaffold the bookr Django project, test that Django is working by running the dev server, then create the reviews Django app.

You should already have a virtual environment set up with Django installed. To learn how to do that, you can refer to the Preface. Once you're ready, let's start by creating the Bookr project:

1. Open a Terminal and run the following command to create the bookr project directory and the default subfolders:

   django-admin startproject bookr

   This command does not generate any output but will create a folder called bookr inside the directory in which you ran the command. You can look inside this directory and see the items we described before for the myproject example: the bookr package directory and manage.py file.

2. We can now test that the project and Django are set up correctly by running the Django dev server. Starting the server is done with the manage.py script.

   In your Terminal (or Command Prompt), change into the bookr project directory (using the cd command), then run the manage.py runserver command.

   python3 manage.py runserver

   Note

   On Windows, you may need to run replace python3 (highlighted) with just python to make the command work every time you run it.

   This command starts the Django dev server. You should get output similar to the following:

   Watching for file changes with StatReloader
   Performing system checks...
   System check identified no issues (0 silenced).
   You have 17 unapplied migration(s). Your project may not work properly until you apply the migrations for app(s): admin, auth, contenttypes, sessions.
   Run 'python manage.py migrate' to apply them.
   September 14, 2019 - 09:40:45
   Django version 3.0a1, using settings 'bookr.settings'
   Starting development server at http://127.0.0.1:8000/
   Quit the server with CONTROL-C.

   You will probably have some warnings about unapplied migrations, but that's okay for now.

3. Open up a web browser and go to http://127.0.0.1:8000/, which will show you the Django welcome screen (Figure 1.2). If you see this, you know your Django project was created successfully and it all is working fine for now:
   

   Figure 1.2: Django welcome screen

4. Go back to your Terminal and stop the development server running using the Ctrl + C key combination.
5. We'll now create the reviews app for the bookr project. In your Terminal, make sure you are in the bookr project directory, then execute the following command to create the reviews app:

   python3 manage.py startapp reviews

   Note

   After creating the reviews app, the files in your bookr project directory would look like this: http://packt.live/3nZGy5D.

   There is no output if the command was successful, but a reviews app directory has been created. You can look inside this directory to see the files that were created: the migrations directory, admin.py, models.py, and so on. We'll examine these in detail in the Django Apps section.

In this exercise, we created the bookr project, tested that the project was working by starting the Django dev server, then created the reviews app for the project. Now that we've had some hands-on time with a Django project, we'll return to some of the theory behind Django's design and HTTP requests and responses.