If you have already installed Django, you can skip this section and jump directly to the Creating your first project section. Django comes as a Python package and thus can be installed in any Python environment. If you haven't installed Django yet, the following is a quick guide to install Django for local development.

Django 2.0 requires Python version 3.4 or higher. In the examples for this book, we will use Python 3.6.5. If you're using Linux or macOS X, you probably have Python installed. If you are using Windows, you can download a Python installer at https://www.python.org/downloads/windows/.

If you are not sure whether Python is installed on your computer, you can verify it by typing python in the shell. If you see something like the following, then Python is installed on your computer:

Python 3.6.5 (v3.6.5:f59c0932b4, Mar 28 2018, 03:03:55) 
[GCC 4.2.1 (Apple Inc. build 5666) (dot 3)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>>

If your installed Python version is lower than 3.4, or if Python is not installed on your computer, download Python 3.6.5 from https://www.python.org/downloads/ and install it.

Since you will use Python 3, you don't have to install a database. This Python version comes with a built-in SQLite database. SQLite is a lightweight database that you can use with Django for development. If you plan to deploy your application in a production environment, you should use an advanced database, such as PostgreSQL, MySQL, or Oracle. You can get more information about how to get your database running with Django at https://docs.djangoproject.com/en/2.0/topics/install/#database-installation.

It is recommended that you use virtualenv to create isolated Python environments, so that you can use different package versions for different projects, which is far more practical than installing Python packages system-wide. Another advantage of using virtualenv is that you won't need any administration privileges to install Python packages. Run the following command in your shell to install virtualenv:

pip install virtualenv

After you install virtualenv, create an isolated environment with the following command:

virtualenv my_env

This will create a my_env/ directory, including your Python environment. Any Python libraries you install while your virtual environment is active will go into the my_env/lib/python3.6/site-packages directory.

You can locate the path where Python 3 is installed and use it to create the virtual environment with the following commands:

zenx$ which python3
/Library/Frameworks/Python.framework/Versions/3.6/bin/python3
zenx$ virtualenv my_env -p /Library/Frameworks/Python.framework/Versions/3.6/bin/python3 

Run the following command to activate your virtual environment:

source my_env/bin/activate

The shell prompt will include the name of the active virtual environment enclosed in parentheses, as follows:

(my_env)laptop:~ zenx$

You can deactivate your environment at any time with the deactivate command.

You can find more information about virtualenv at https://virtualenv.pypa.io/en/latest/.

On top of virtualenv, you can use virtualenvwrapper. This tool provides wrappers that make it easier to create and manage your virtual environments. You can download it from https://virtualenvwrapper.readthedocs.io/en/latest/.

The pip package management system is the preferred method for installing Django. Python 3.6 comes with pip preinstalled, but you can find pip installation instructions at https://pip.pypa.io/en/stable/installing/.

Run the following command at the shell prompt to install Django with pip:

pip install Django==2.0.5

Django will be installed in the Python site-packages/ directory of your virtual environment.

Now, check whether Django has been successfully installed. Run python on a terminal, import Django, and check its version, as follows:

>>> import django
>>> django.get_version()
'2.0.5'

If you get the preceding output, Django has been successfully installed on your machine.

Our first Django project will be building a complete blog. Django provides a command that allows you to create an initial project file structure. Run the following command from your shell:

django-admin startproject mysite

This will create a Django project with the name mysite.

Let's take a look at the project structure generated:

mysite/
  manage.py
  mysite/
    __init__.py
    settings.py
    urls.py
    wsgi.py

These files are as follows:

• manage.py: This is a command-line utility used to interact with your project. It is a thin wrapper around the django-admin.py tool. You don't need to edit this file.
• mysite/: This is your project directory, which consists of the following files:
  • __init__.py: An empty file that tells Python to treat the mysite directory as a Python module.
  • settings.py: This indicates settings and configuration for your project and contains initial default settings.
  • urls.py: This is the place where your URL patterns live. Each URL defined here is mapped to a view.
  • wsgi.py: This is the configuration to run your project as a Web Server Gateway Interface (WSGI) application.

The generated settings.py file contains the project settings, including a basic configuration to use an SQLite 3 database and a list named INSTALLED_APPS, which contains common Django applications that are added to your project by default. We will go through these applications later in the Project settings section.

To complete the project setup, we will need to create the tables in the database required by the applications listed in INSTALLED_APPS. Open the shell and run the following commands:

cd mysite
python manage.py migrate

You will note an output that ends with the following lines:

Applying contenttypes.0001_initial... OK
Applying auth.0001_initial... OK
Applying admin.0001_initial... OK
Applying admin.0002_logentry_remove_auto_add... OK
Applying contenttypes.0002_remove_content_type_name... OK
Applying auth.0002_alter_permission_name_max_length... OK
Applying auth.0003_alter_user_email_max_length... OK
Applying auth.0004_alter_user_username_opts... OK
Applying auth.0005_alter_user_last_login_null... OK
Applying auth.0006_require_contenttypes_0002... OK
Applying auth.0007_alter_validators_add_error_messages... OK
Applying auth.0008_alter_user_username_max_length... OK
Applying auth.0009_alter_user_last_name_max_length... OK
Applying sessions.0001_initial... OK

The preceding lines are the database migrations that are applied by Django. By applying migrations, the tables for the initial applications are created in the database. You will learn about the migrate management command in the Creating and applying migrations section of this chapter.

Django comes with a lightweight web server to run your code quickly, without needing to spend time configuring a production server. When you run the Django development server, it keeps checking for changes in your code. It reloads automatically, freeing you from manually reloading it after code changes. However, it might not notice some actions, such as adding new files to your project, so you will have to restart the server manually in these cases.

Start the development server by typing the following command from your project's root folder:

python manage.py runserver

You should see something like this:

Performing system checks...

System check identified no issues (0 silenced).
May 06, 2018 - 17:17:31
Django version 2.0.5, using settings 'mysite.settings'
Starting development server at http://127.0.0.1:8000/
Quit the server with CONTROL-C.

Now, open http://127.0.0.1:8000/ in your browser. You should see a page stating that the project is successfully running, as shown in the following screenshot:

The preceding screenshot indicates that Django is running. If you take a look at your console, you will see the GET request performed by your browser:

[06/May/2018 17:20:30] "GET / HTTP/1.1" 200 16348

Each HTTP request is logged in the console by the development server. Any error that occurs while running the development server will also appear in the console.

You can indicate Django to run the development server on a custom host and port or tell it to run your project, loading a different settings file, as follows:

python manage.py runserver 127.0.0.1:8001 \
--settings=mysite.settings

Remember that this server is only intended for development and is not suitable for production use. In order to deploy Django in a production environment, you should run it as a WSGI application using a real web server, such as Apache, Gunicorn, or uWSGI. You can find more information on how to deploy Django with different web servers at https://docs.djangoproject.com/en/2.0/howto/deployment/wsgi/.

Chapter 13, Going Live, explains how to set up a production environment for your Django projects.

Let's open the settings.py file and take a look at the configuration of our project. There are several settings that Django includes in this file, but these are only a part of all the Django settings available. You can see all settings and their default values in https://docs.djangoproject.com/en/2.0/ref/settings/.

The following settings are worth looking at:

• DEBUG is a boolean that turns the debug mode of the project on and off. If it is set to True, Django will display detailed error pages when an uncaught exception is thrown by your application. When you move to a production environment, remember that you have to set it to False. Never deploy a site into production with DEBUG turned on because you will expose sensitive project-related data.
• ALLOWED_HOSTS is not applied while debug mode is on, or when the tests are run. Once you move your site to production and set DEBUG to False, you will have to add your domain/host to this setting in order to allow it to serve your Django site.
• INSTALLED_APPS is a setting you will have to edit for all projects. This setting tells Django which applications are active for this site. By default, Django includes the following applications:
  • django.contrib.admin: An administration site
  • django.contrib.auth: An authentication framework
  • django.contrib.contenttypes: A framework for handling content types
  • django.contrib.sessions: A session framework
  • django.contrib.messages: A messaging framework
  • django.contrib.staticfiles: A framework for managing static files
• MIDDLEWARE is a list that contains middleware to be executed.
• ROOT_URLCONF indicates the Python module where the root URL patterns of your application are defined.
• DATABASES is a dictionary that contains the settings for all the databases to be used in the project. There must always be a default database. The default configuration uses an SQLite3 database.
• LANGUAGE_CODE defines the default language code for this Django site.
• USE_TZ tells Django to activate/deactivate timezone support. Django comes with support for timezone-aware datetime. This setting is set to True when you create a new project using the startproject management command.

Don't worry if you don't understand much about what you are seeing. You will learn the different Django settings in the following chapters.

Throughout this book, you will encounter the terms project and application over and over. In Django, a project is considered a Django installation with some settings. An application is a group of models, views, templates, and URLs. Applications interact with the framework to provide some specific functionalities and may be reused in various projects. You can think of the project as your website, which contains several applications such as a blog, wiki, or forum, that can be used by other projects also.

Now, let's create our first Django application. We will create a blog application from scratch. From the project's root directory, run the following command:

python manage.py startapp blog

This will create the basic structure of the application, which looks like this:

blog/
    __init__.py
    admin.py
    apps.py
    migrations/
        __init__.py
    models.py
    tests.py
    views.py

These files are as follows:

• admin.py: This is where you register models to include them in the Django administration site—using the Django admin site is optional.
• apps.py: This includes the main configuration of the blog application.
• migrations: This directory will contain database migrations of your application. Migrations allow Django to track your model changes and synchronize the database accordingly.
• models.py: Data models of your application—all Django applications need to have a models.py file, but this file can be left empty.
• tests.py: This is where you can add tests for your application.
• views.py: The logic of your application goes here; each view receives an HTTP request, processes it, and returns a response.

We will start designing our blog data schema by defining the data models for our blog. A model is a Python class that subclasses django.db.models.Model, in which each attribute represents a database field. Django will create a table for each model defined in the models.py file. When you create a model, Django provides you with a practical API to query objects in the database easily.

First, we will define a Post model. Add the following lines to the models.py file of the blog application:

from django.db import models
from django.utils import timezone
from django.contrib.auth.models import User

class Post(models.Model):
    STATUS_CHOICES = (
        ('draft', 'Draft'),
        ('published', 'Published'),
    )
    title = models.CharField(max_length=250)
    slug = models.SlugField(max_length=250,
                            unique_for_date='publish')
    author = models.ForeignKey(User,
                               on_delete=models.CASCADE,
                               related_name='blog_posts')
    body = models.TextField()
    publish = models.DateTimeField(default=timezone.now)
    created = models.DateTimeField(auto_now_add=True)
    updated = models.DateTimeField(auto_now=True)
    status = models.CharField(max_length=10,
                              choices=STATUS_CHOICES,
                              default='draft')

    class Meta:
        ordering = ('-publish',)

    def __str__(self):
        return self.title

This is our data model for blog posts. Let's take a look at the fields we just defined for this model:

• title: This is the field for the post title. This field is CharField, which translates into a VARCHAR column in the SQL database.
• slug: This is a field intended to be used in URLs. A slug is a short label that contains only letters, numbers, underscores, or hyphens. We will use the slug field to build beautiful, SEO-friendly URLs for our blog posts. We have added the unique_for_date parameter to this field so that we can build URLs for posts using their publish date and slug. Django will prevent multiple posts from having the same slug for a given date.
• author: This field is a foreign key. It defines a many-to-one relationship. We are telling Django that each post is written by a user, and a user can write any number of posts. For this field, Django will create a foreign key in the database using the primary key of the related model. In this case, we are relying on the User model of the Django authentication system. The on_delete parameter specifies the behavior to adopt when the referenced object is deleted. This is not specific to Django; it is an SQL standard. Using CASCADE, we specify that when the referenced user is deleted, the database will also delete its related blog posts. You can take a look at all possible options at https://docs.djangoproject.com/en/2.0/ref/models/fields/#django.db.models.ForeignKey.on_delete. We specify the name of the reverse relationship, from User to Post, with the related_name attribute. This will allow us to access related objects easily. We will learn more about this later.
• body: This is the body of the post. This field is a text field, which translates into a TEXT column in the SQL database.
• publish: This datetime indicates when the post was published. We use Django's timezone now method as the default value. This returns the current datetime in a timezone-aware format. You can think of it as a timezone-aware version of the standard Python datetime.now method.
• created: This datetime indicates when the post was created. Since we are using auto_now_add here, the date will be saved automatically when creating an object.
• updated: This datetime indicates the last time the post was updated. Since we are using auto_now here, the date will be updated automatically when saving an object.
• status: This field shows the status of a post. We use a choices parameter, so the value of this field can only be set to one of the given choices.

Django comes with different types of fields that you can use to define your models. You can find all field types at https://docs.djangoproject.com/en/2.0/ref/models/fields/.

The Meta class inside the model contains metadata. We tell Django to sort results in the publish field in descending order by default when we query the database. We specify descending order using the negative prefix. By doing so, posts published recently will appear first.

The __str__() method is the default human-readable representation of the object. Django will use it in many places, such as the administration site.

In order for Django to keep track of our application and be able to create database tables for its models, we have to activate it. To do this, edit the settings.py file and add blog.apps.BlogConfig to the INSTALLED_APPS setting. It should look like this:

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'blog.apps.BlogConfig',
]

The BlogConfig class is your application configuration. Now Django knows that our application is active for this project and will be able to load its models.

Now that we have a data model for our blog posts, we will need a database table for it. Django comes with a migration system that tracks the changes done to models and allows to propagate them into the database. The migrate command applies migrations for all applications listed in INSTALLED_APPS; it synchronizes the database with the current models and existing migrations.

First, you will need to create an initial migration for our Post model. In the root directory of your project, run the following command:

python manage.py makemigrations blog

You should get the following output:

Migrations for 'blog':
  blog/migrations/0001_initial.py
    - Create model Post

Django just created the 0001_initial.py file inside the migrations directory of the blog application. You can open that file to see how a migration appears. A migration specifies dependencies on other migrations and operations to perform in the database to synchronize it with model changes.

Let's take a look at the SQL code that Django will execute in the database to create the table for our model. The sqlmigrate command takes migration names and returns their SQL without executing it. Run the following command to inspect the SQL output of our first migration:

python manage.py sqlmigrate blog 0001

The output should look as follows:

BEGIN;
--
-- Create model Post
--
CREATE TABLE "blog_post" ("id" integer NOT NULL PRIMARY KEY AUTOINCREMENT, "title" varchar(250) NOT NULL, "slug" varchar(250) NOT NULL, "body" text NOT NULL, "publish" datetime NOT NULL, "created" datetime NOT NULL, "updated" datetime NOT NULL, "status" varchar(10) NOT NULL, "author_id" integer NOT NULL REFERENCES "auth_user" ("id"));
CREATE INDEX "blog_post_slug_b95473f2" ON "blog_post" ("slug");
CREATE INDEX "blog_post_author_id_dd7a8485" ON "blog_post" ("author_id");
COMMIT;

The exact output depends on the database you are using. The preceding output is generated for SQLite. As you can see in the preceding output, Django generates the table names by combining the app name and the lowercase name of the model (blog_post), but you can also specify a custom database name for your model in the Meta class of the model using the db_table attribute. Django creates a primary key automatically for each model, but you can also override this by specifying primary_key=True in one of your model fields. The default primary key is an id column, which consists of an integer that is incremented automatically. This column corresponds to the id field that is automatically added to your models.

Let's sync our database with the new model. Run the following command to apply existing migrations:

python manage.py migrate

You will get an output that ends with the following line:

Applying blog.0001_initial... OK

We just applied migrations for the applications listed in INSTALLED_APPS, including our blog application. After applying migrations, the database reflects the current status of our models.

If you edit your models.py file in order to add, remove, or change fields of existing models, or if you add new models, you will have to create a new migration using the makemigrations command. The migration will allow Django to keep track of model changes. Then, you will have to apply it with the migrate command to keep the database in sync with your models.

Now that we have defined the Post model, we will create a simple administration site to manage your blog posts. Django comes with a built-in administration interface that is very useful for editing content. The Django admin site is built dynamically by reading your model metadata and providing a production-ready interface for editing content. You can use it out of the box, configuring how you want your models to be displayed in it.

The django.contrib.admin application is already included in the INSTALLED_APPS setting, so we don't need to add it.

First, we will need to create a user to manage the administration site. Run the following command:

python manage.py createsuperuser

You will see the following output; enter your desired username, email, and password, as follows:

Username (leave blank to use 'admin'): admin
Email address: admin@admin.com
Password: ********
Password (again): ********
Superuser created successfully.

Now, start the development server with the python manage.py runserver command and open http://127.0.0.1:8000/admin/ in your browser. You should see the administration login page, as shown in the following screenshot:

Log in using the credentials of the user you created in the preceding step. You will see the admin site index page, as shown in the following screenshot:

The Group and User models you see in the preceding screenshot are part of the Django authentication framework located in django.contrib.auth. If you click on Users, you will see the user you created previously. The Post model of your blog application has a relationship with this User model. Remember that it is a relationship defined by the author field.

Let's add your blog models to the administration site. Edit the admin.py file of your blog application and make it look like this:

from django.contrib import admin
from .models import Post

admin.site.register(Post)

Now, reload the admin site in your browser. You should see your Post model on the admin site, as follows:

That was easy, right? When you register a model in the Django admin site, you get a user-friendly interface generated by introspecting your models that allows you to list, edit, create, and delete objects in a simple way.

Click on the Add link beside Posts to add a new post. You will note the create form that Django has generated dynamically for your model, as shown in the following screenshot:

Django uses different form widgets for each type of field. Even complex fields, such as DateTimeField, are displayed with an easy interface, such as a JavaScript date picker.

Fill in the form and click on the SAVE button. You should be redirected to the post list page with a successful message and the post you just created, as shown in the following screenshot:

Now, we will take a look at how to customize the admin site. Edit the admin.py file of your blog application and change it, as follows:

from django.contrib import admin
from .models import Post

@admin.register(Post)
class PostAdmin(admin.ModelAdmin):
    list_display = ('title', 'slug', 'author', 'publish',
                    'status')

We are telling the Django admin site that our model is registered in the admin site using a custom class that inherits from ModelAdmin. In this class, we can include information about how to display the model in the admin site and how to interact with it. The list_display attribute allows you to set the fields of your model that you want to display in the admin object list page. The @admin.register() decorator performs the same function as the admin.site.register() function we have replaced, registering the ModelAdmin class that it decorates.

Let's customize the admin model with some more options, using the following code:

@admin.register(Post)
class PostAdmin(admin.ModelAdmin):
    list_display = ('title', 'slug', 'author', 'publish',
                       'status')
    list_filter = ('status', 'created', 'publish', 'author')
    search_fields = ('title', 'body')
    prepopulated_fields = {'slug': ('title',)}
    raw_id_fields = ('author',)
    date_hierarchy = 'publish'
    ordering = ('status', 'publish')

Return to your browser and reload the post list page. Now, it will look like this:

You can see that the fields displayed on the post list page are the ones you specified in the list_display attribute. The list page now includes a right sidebar that allows you to filter the results by the fields included in the list_filter attribute. A Search bar has appeared on the page. This is because we have defined a list of searchable fields using the search_fields attribute. Just below the Search bar, there are navigation links to navigate through a date hierarchy: this has been defined by the date_hierarchy attribute. You can also see that the posts are ordered by Status and Publish columns by default. We have specified the default order using the ordering attribute.

Now, click on the Add Post link. You will also note some changes here. As you type the title of a new post, the slug field is filled in automatically. We have told Django to prepopulate the slug field with the input of the title field using the prepopulated_fields attribute. Also, now, the author field is displayed with a lookup widget that can scale much better than a drop-down select input when you have thousands of users, as shown in the following screenshot:

With a few lines of code, we have customized the way our model is displayed on the admin site. There are plenty of ways to customize and extend the Django administration site. You will learn more about this later in this book.