Создание вашей первой Django-приложения, часть 2

Этот учебник начинается там, где Учебник 1 закончился. Мы настроим базу данных, создадим вашу первую модель и получим краткое знакомство с автоматически сгенерированной администраторской панелью Django.

Настройка базы данных

Теперь откройте mysite/settings.py. Это обычный Python-модуль с переменными уровня модуля, представляющими настройки Django.

По умолчанию конфигурация использует SQLite. Если вы новичок в базах данных или просто хотите попробовать Django, это самый простой выбор. SQLite включен в Python, поэтому вам не нужно устанавливать ничего другого для поддержки вашей базы данных. Однако при запуске первого реального проекта вы можете захотеть использовать более масштабируемую базу данных, например PostgreSQL, чтобы избежать проблем со сменой баз данных в будущем.

Если вы хотите использовать другую базу данных, установите соответствующие привязки к базе данных и измените следующие ключи в элементе DATABASES 'default' для соответствия настройкам подключения к вашей базе данных:

• ENGINE – Либо 'django.db.backends.sqlite3', 'django.db.backends.postgresql', 'django.db.backends.mysql', или 'django.db.backends.oracle'. Другие бэкэнды также доступны.
• NAME – Имя вашей базы данных. Если вы используете SQLite, база данных будет файлом на вашем компьютере; в этом случае NAME должен быть полным абсолютным путем, включая имя файла этого файла. Значение по умолчанию os.path.join(BASE_DIR, 'db.sqlite3') сохранит файл в каталоге вашего проекта.

Если вы не используете SQLite в качестве базы данных, необходимо добавить дополнительные настройки, такие как USER, PASSWORD и HOST. Более подробную информацию см. в справочной документации для DATABASES.

Во время редактирования mysite/settings.py, установите TIME_ZONE на вашу часовую зону.

Обратите также внимание на настройку INSTALLED_APPS в верхней части файла. Она содержит имена всех Django-приложений, которые активированы в этом экземпляре Django. Приложения могут использоваться в нескольких проектах, и вы можете упаковать и распространить их для использования другими в своих проектах.

По умолчанию INSTALLED_APPS содержит следующие приложения, которые поставляются с Django:

• django.contrib.admin – Администраторская панель. Вы будете использовать ее вскоре.
• django.contrib.auth – Система аутентификации.
• django.contrib.contenttypes – Фреймворк для типов контента.
• django.contrib.sessions – Фреймворк для управления сеансами.
• django.contrib.messages – Фреймворк для сообщений.
• django.contrib.staticfiles – Фреймворк для управления статическими файлами.

Эти приложения включены по умолчанию для удобства в общем случае.

Некоторые из этих приложений используют по крайней мере одну таблицу базы данных, поэтому нам необходимо создать таблицы в базе данных, прежде чем мы сможем их использовать. Для этого выполните следующую команду:

$ python manage.py migrate

...\> py manage.py migrate

Команда migrate просматривает настройку INSTALLED_APPS и создает необходимые таблицы базы данных в соответствии с настройками базы данных в вашем файле mysite/settings.py и миграциями базы данных, поставляемыми с приложением (мы рассмотрим их позже). Вы увидите сообщение для каждой применяемой миграции. Если вас интересует, запустите командную строку клиента вашей базы данных и введите \dt (PostgreSQL), SHOW TABLES; (MySQL), .schema (SQLite) или SELECT TABLE_NAME FROM USER_TABLES; (Oracle), чтобы отобразить таблицы, созданные Django.

Создание моделей

Теперь мы определим ваши модели — по существу, вашу структуру базы данных с дополнительными метаданными.

В нашем простом приложении опросов мы создадим две модели: Question и Choice. Question имеет вопрос и дату публикации. Choice имеет два поля: текст выбора и количество голосов. Каждый Choice связан с Question.

Эти понятия представлены простыми Python-классами. Отредактируйте файл polls/models.py, чтобы он выглядел так:

from django.db import models


class Question(models.Model):
    question_text = models.CharField(max_length=200)
    pub_date = models.DateTimeField('date published')


class Choice(models.Model):
    question = models.ForeignKey(Question, on_delete=models.CASCADE)
    choice_text = models.CharField(max_length=200)
    votes = models.IntegerField(default=0)

Код простой. Каждая модель представлена классом, который является подклассом django.db.models.Model. Каждая модель имеет ряд переменных класса, каждая из которых представляет поле базы данных в модели.

Каждое поле представлено экземпляром класса Field — например, CharField для символьных полей и DateTimeField для дат и времени. Это говорит Django, какой тип данных хранит каждое поле.

Имя каждого экземпляра Field (например, question_text или pub_date) — это имя поля в удобном для машины формате. Вы будете использовать это значение в своем коде Python, а ваша база данных будет использовать его в качестве имени столбца.

Вы можете использовать необязательный первый позиционный аргумент к Field, чтобы указать удобочитаемое имя. Оно используется в некоторых интроспективных частях Django и служит документацией. Если это поле не предоставлено, Django будет использовать имя, удобное для машины. В этом примере мы определили только удобочитаемое имя для Question.pub_date. Для всех других полей в этой модели имя поля, удобное для машины, будет достаточным в качестве удобочитаемого имени.

Некоторые Field классы имеют обязательные аргументы. Например, CharField требует указания max_length. Это используется не только в схеме базы данных, но и в валидации, как мы скоро увидим.

У Field также могут быть различные необязательные аргументы; в этом случае мы установили значение default для votes в 0.

Наконец, обратите внимание, что отношение определяется с помощью ForeignKey. Это сообщает Django, что каждый Choice связан с одним Question. Django поддерживает все распространённые отношения в базе данных: многие-к-одному, многие-ко-многим и один-к-одному.

Активация моделей

Этот небольшой фрагмент кода модели предоставляет Django много информации. С его помощью Django может:

• Создать схему базы данных (CREATE TABLE инструкции) для этого приложения.
• Создать API доступа к базе данных Python для доступа к Question и Choice объектам.

Но сначала нам нужно сообщить нашему проекту, что приложение polls установлено.

Чтобы включить приложение в наш проект, нам нужно добавить ссылку на его конфигурационный класс в настройку INSTALLED_APPS. Класс PollsConfig находится в файле polls/apps.py, поэтому его полное имя — 'polls.apps.PollsConfig'. Откройте файл mysite/settings.py и добавьте это полное имя в настройку INSTALLED_APPS. Он будет выглядеть так:

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

Теперь Django знает, как включить приложение polls. Давайте выполним ещё одну команду:

$ python manage.py makemigrations polls

...\> py manage.py makemigrations polls

Вы должны увидеть что-то подобное:

Migrations for 'polls':
  polls/migrations/0001_initial.py:
    - Create model Choice
    - Create model Question
    - Add field question to choice

Выполняя makemigrations, вы сообщаете Django, что внесли некоторые изменения в свои модели (в данном случае создали новые) и хотите, чтобы эти изменения были сохранены как миграция.

Миграции — это способ, которым Django сохраняет изменения в ваших моделях (и, следовательно, в схеме вашей базы данных) — это просто файлы на диске. Вы можете прочитать миграцию для своей новой модели, если хотите; это файл polls/migrations/0001_initial.py. Не беспокойтесь, от вас не ожидается чтение их каждый раз, когда Django создаёт миграцию, но они разработаны для редактирования человеком, если вы захотите вручную изменить то, как Django производит изменения.

Существует команда, которая выполнит миграции за вас и автоматически управляет схемой вашей базы данных — это команда migrate, и мы к ней обратимся чуть позже — но сначала давайте посмотрим, какой SQL эта миграция выполнит. Команда sqlmigrate принимает имена миграций и возвращает их SQL:

$ python manage.py sqlmigrate polls 0001

...\> py manage.py sqlmigrate polls 0001

Вы должны увидеть что-то подобное (мы переформатировали его для большей удобочитаемости):

BEGIN;
--
-- Create model Choice
--
CREATE TABLE "polls_choice" (
    "id" serial NOT NULL PRIMARY KEY,
    "choice_text" varchar(200) NOT NULL,
    "votes" integer NOT NULL
);
--
-- Create model Question
--
CREATE TABLE "polls_question" (
    "id" serial NOT NULL PRIMARY KEY,
    "question_text" varchar(200) NOT NULL,
    "pub_date" timestamp with time zone NOT NULL
);
--
-- Add field question to choice
--
ALTER TABLE "polls_choice" ADD COLUMN "question_id" integer NOT NULL;
ALTER TABLE "polls_choice" ALTER COLUMN "question_id" DROP DEFAULT;
CREATE INDEX "polls_choice_7aa0f6ee" ON "polls_choice" ("question_id");
ALTER TABLE "polls_choice"
  ADD CONSTRAINT "polls_choice_question_id_246c99a640fbbd72_fk_polls_question_id"
    FOREIGN KEY ("question_id")
    REFERENCES "polls_question" ("id")
    DEFERRABLE INITIALLY DEFERRED;

COMMIT;

Обратите внимание на следующее:

• Точный результат будет зависеть от используемой базы данных. Приведённый выше пример сгенерирован для PostgreSQL.
• Имена таблиц автоматически генерируются путём объединения имени приложения (polls) и имени модели в нижнем регистре — question и choice. (Вы можете настроить это поведение.)
• Первичные ключи (ID) добавляются автоматически. (Вы можете настроить это тоже.)
• Согласно соглашению, Django добавляет "_id" к имени поля внешнего ключа. (Да, вы можете настроить это тоже.)
• Отношение внешнего ключа явно задаётся ограничением FOREIGN KEY. Не беспокойтесь о частях DEFERRABLE; это просто сообщает PostgreSQL о том, что ограничение внешнего ключа не будет применяться до конца транзакции.
• Это настраивается под используемую базу данных, поэтому такие специфичные для базы данных типы полей, как auto_increment (MySQL), serial (PostgreSQL) или integer primary key autoincrement (SQLite), обрабатываются автоматически. То же самое относится к цитированию имён полей — например, с использованием двойных или одинарных кавычек.
• Команда sqlmigrate фактически не выполняет миграцию в вашей базе данных — она просто выводит SQL на экран, чтобы вы могли увидеть, какой SQL Django считает необходимым. Это полезно для проверки того, что собирается сделать Django, или если у вас есть администраторы базы данных, которым требуются скрипты SQL для изменений.

Если вас интересует, вы также можете запустить команду python manage.py check; она проверяет наличие проблем в вашем проекте без создания миграций и без вмешательства в базу данных.

Теперь запустите migrate ещё раз, чтобы создать эти таблицы модели в вашей базе данных:

$ python manage.py migrate
Operations to perform:
  Apply all migrations: admin, auth, contenttypes, polls, sessions
Running migrations:
  Rendering model states... DONE
  Applying polls.0001_initial... OK

...\> py manage.py migrate
Operations to perform:
  Apply all migrations: admin, auth, contenttypes, polls, sessions
Running migrations:
  Rendering model states... DONE
  Applying polls.0001_initial... OK

Команда migrate берёт все миграции, которые ещё не были применены (Django отслеживает, какие из них применены, используя специальную таблицу в вашей базе данных под названием django_migrations) и выполняет их в вашей базе данных — по сути, синхронизирует изменения, которые вы внесли в свои модели, со схемой в базе данных.

Миграции очень мощный инструмент, позволяющий изменять модели со временем, по мере разработки проекта, без необходимости удалять базу данных или таблицы и создавать новые — он специализируется на обновлении вашей базы данных в режиме реального времени без потери данных. Мы более подробно рассмотрим их в последующих частях учебника, но пока запомните пошаговую инструкцию по внесению изменений в модель:

• Измените свои модели (в models.py).
• Запустите python manage.py makemigrations, чтобы создать миграции для этих изменений.
• Запустите python manage.py migrate, чтобы применить эти изменения к базе данных.

Причина, по которой для создания и применения миграций используются отдельные команды, заключается в том, что вы можете добавить миграции в систему контроля версий и распространять их вместе с приложением; они не только упрощают вашу разработку, но и могут использоваться другими разработчиками и в рабочей среде.

Полную информацию о том, что может делать утилита manage.py можно получить в документации django-admin.

Работа с API

Теперь давайте перейдём к интерактивной оболочке Python и немного поиграем с бесплатным API, который предоставляет Django. Чтобы запустить оболочку Python, используйте эту команду:

$ python manage.py shell

...\> py manage.py shell

Мы используем эту команду вместо простого ввода «python», потому что manage.py устанавливает переменную среды DJANGO_SETTINGS_MODULE, которая предоставляет Django путь импорта Python к вашему файлу mysite/settings.py.

Поработайте с API базы данных:

>>> from polls.models import Choice, Question  # Import the model classes we just wrote.

# No questions are in the system yet.
>>> Question.objects.all()
<QuerySet []>

# Create a new Question.
# Support for time zones is enabled in the default settings file, so
# Django expects a datetime with tzinfo for pub_date. Use timezone.now()
# instead of datetime.datetime.now() and it will do the right thing.
>>> from django.utils import timezone
>>> q = Question(question_text="What's new?", pub_date=timezone.now())

# Save the object into the database. You have to call save() explicitly.
>>> q.save()

# Now it has an ID.
>>> q.id
1

# Access model field values via Python attributes.
>>> q.question_text
"What's new?"
>>> q.pub_date
datetime.datetime(2012, 2, 26, 13, 0, 0, 775217, tzinfo=<UTC>)

# Change values by changing the attributes, then calling save().
>>> q.question_text = "What's up?"
>>> q.save()

# objects.all() displays all the questions in the database.
>>> Question.objects.all()
<QuerySet [<Question: Question object (1)>]>

Подождите минутку. <Question: Question object (1)> не является полезной формой представления этого объекта. Давайте исправим это, отредактировав модель Question (в файле polls/models.py), и добавим метод __str__() для обеих моделей Question и Choice.

from django.db import models

class Question(models.Model):
    # ...
    def __str__(self):
        return self.question_text

class Choice(models.Model):
    # ...
    def __str__(self):
        return self.choice_text

Важно добавлять методы __str__() в ваши модели не только для собственного удобства при работе с интерактивным приглашением, но и потому, что представления объектов используются в автоматически сгенерированном административном интерфейсе Django.

Обратите внимание, что это обычные методы Python. Давайте добавим пользовательский метод для демонстрации:

import datetime

from django.db import models
from django.utils import timezone


class Question(models.Model):
    # ...
    def was_published_recently(self):
        return self.pub_date >= timezone.now() - datetime.timedelta(days=1)

Обратите внимание на добавление import datetime и from django.utils import timezone, для ссылки на стандартный модуль Python datetime и инструменты Django для работы со временными зонами в django.utils.timezone соответственно. Если вы не знакомы с обработкой временных зон в Python, вы можете узнать больше в документации по поддержке временных зон.

Сохраните эти изменения и запустите новую интерактивную оболочку Python, выполнив python manage.py shell ещё раз:

>>> from polls.models import Choice, Question

# Make sure our __str__() addition worked.
>>> Question.objects.all()
<QuerySet [<Question: What's up?>]>

# Django provides a rich database lookup API that's entirely driven by
# keyword arguments.
>>> Question.objects.filter(id=1)
<QuerySet [<Question: What's up?>]>
>>> Question.objects.filter(question_text__startswith='What')
<QuerySet [<Question: What's up?>]>

# Get the question that was published this year.
>>> from django.utils import timezone
>>> current_year = timezone.now().year
>>> Question.objects.get(pub_date__year=current_year)
<Question: What's up?>

# Request an ID that doesn't exist, this will raise an exception.
>>> Question.objects.get(id=2)
Traceback (most recent call last):
    ...
DoesNotExist: Question matching query does not exist.

# Lookup by a primary key is the most common case, so Django provides a
# shortcut for primary-key exact lookups.
# The following is identical to Question.objects.get(id=1).
>>> Question.objects.get(pk=1)
<Question: What's up?>

# Make sure our custom method worked.
>>> q = Question.objects.get(pk=1)
>>> q.was_published_recently()
True

# Give the Question a couple of Choices. The create call constructs a new
# Choice object, does the INSERT statement, adds the choice to the set
# of available choices and returns the new Choice object. Django creates
# a set to hold the "other side" of a ForeignKey relation
# (e.g. a question's choice) which can be accessed via the API.
>>> q = Question.objects.get(pk=1)

# Display any choices from the related object set -- none so far.
>>> q.choice_set.all()
<QuerySet []>

# Create three choices.
>>> q.choice_set.create(choice_text='Not much', votes=0)
<Choice: Not much>
>>> q.choice_set.create(choice_text='The sky', votes=0)
<Choice: The sky>
>>> c = q.choice_set.create(choice_text='Just hacking again', votes=0)

# Choice objects have API access to their related Question objects.
>>> c.question
<Question: What's up?>

# And vice versa: Question objects get access to Choice objects.
>>> q.choice_set.all()
<QuerySet [<Choice: Not much>, <Choice: The sky>, <Choice: Just hacking again>]>
>>> q.choice_set.count()
3

# The API automatically follows relationships as far as you need.
# Use double underscores to separate relationships.
# This works as many levels deep as you want; there's no limit.
# Find all Choices for any question whose pub_date is in this year
# (reusing the 'current_year' variable we created above).
>>> Choice.objects.filter(question__pub_date__year=current_year)
<QuerySet [<Choice: Not much>, <Choice: The sky>, <Choice: Just hacking again>]>

# Let's delete one of the choices. Use delete() for that.
>>> c = q.choice_set.filter(choice_text__startswith='Just hacking')
>>> c.delete()

Дополнительную информацию об отношениях моделей см. в разделе Доступ к связанным объектам. Подробности о том, как использовать двойное подчеркивание для выполнения поиска по полям через API, см. в разделе Поиск по полям. Полную информацию об API базы данных см. в нашей Справочнике по API базы данных.

Представление Django Admin

Создание пользователя администратора

Сначала нам нужно создать пользователя, который может войти в админ-панель. Выполните следующую команду:

$ python manage.py createsuperuser

...\> py manage.py createsuperuser

Введите желаемое имя пользователя и нажмите Enter.

Username: admin

Затем вам будет предложено ввести желаемый адрес электронной почты:

Email address: admin@example.com

Последний шаг — ввести пароль. Вам будет предложено дважды ввести свой пароль, во второй раз для подтверждения первого.

Password: **********
Password (again): *********
Superuser created successfully.

Запуск сервера разработки

Админ-панель Django активирована по умолчанию. Давайте запустим сервер разработки и исследуем его.

Если сервер не запущен, запустите его следующим образом:

$ python manage.py runserver

...\> py manage.py runserver

Теперь откройте веб-браузер и перейдите по адресу «/admin/» на вашем локальном домене — например, http://127.0.0.1:8000/admin/. Вы должны увидеть экран входа в админ-панель:

Поскольку перевод включен по умолчанию, экран входа может быть отображен на вашем языке в зависимости от настроек вашего браузера и наличия перевода для этого языка в Django.

Вход в админ-панель

Теперь попробуйте войти в систему с учетной записью суперпользователя, которую вы создали на предыдущем шаге. Вы должны увидеть главную страницу админ-панели Django:

Вы должны увидеть несколько типов редактируемого контента: группы и пользователи. Они предоставляются django.contrib.auth, фреймворком аутентификации, поставляемым Django.

Сделайте приложение опросов редактируемым в админ-панели

Но где наше приложение опросов? Оно не отображается на главной странице админ-панели.

Нужно сделать только одно: сообщить админ-панели, что объекты Question имеют интерфейс администрирования. Для этого откройте файл polls/admin.py, и отредактируйте его, как показано ниже:

from django.contrib import admin

from .models import Question

admin.site.register(Question)

Изучение функциональности админ-панели

Теперь, когда мы зарегистрировали Question, Django знает, что оно должно отображаться на главной странице админ-панели:

Нажмите «Вопросы». Теперь вы на странице «список изменений» для вопросов. Эта страница отображает все вопросы в базе данных и позволяет вам выбрать один для изменения. Там есть вопрос «Что нового?» , который мы создали ранее:

Нажмите на вопрос «Что нового?» для редактирования:

Следует отметить:

• Форма автоматически генерируется из модели Question.
• Разные типы полей модели (DateTimeField, CharField) соответствуют соответствующему HTML-элементу ввода. Каждый тип поля знает, как отобразить себя в админ-панели Django.
• Каждое поле DateTimeField получает бесплатные JavaScript-сокращения. Даты получают сокращение «Сегодня» и всплывающую календарную панель, а время получает сокращение «Сейчас» и удобную всплывающую панель, которая перечисляет часто вводимое время.

В нижней части страницы у вас есть несколько вариантов:

• Сохранить — сохраняет изменения и возвращается к странице списка изменений для этого типа объекта.
• Сохранить и продолжить редактирование — сохраняет изменения и перезагружает страницу администрирования для этого объекта.
• Сохранить и добавить другой — сохраняет изменения и загружает новую пустую форму для этого типа объекта.
• Удалить — отображает страницу подтверждения удаления.

Если значение «Дата публикации» не совпадает со временем, когда вы создали вопрос в Уроке 1, это, вероятно, означает, что вы забыли установить правильное значение для параметра TIME_ZONE. Измените его, перезагрузите страницу и проверьте, что появляется правильное значение.

Измените «Дата публикации», щелкнув сокращения «Сегодня» и «Сейчас». Затем нажмите «Сохранить и продолжить редактирование». Затем нажмите «История» в правом верхнем углу. Вы увидите страницу, на которой перечислены все изменения, внесенные в этот объект через админ-панель Django, со временем и именем пользователя, который внес изменение:

Когда вы будете готовы работать с API моделей и ознакомитесь с админ-панелью, прочитайте часть 3 этого руководства, чтобы узнать, как добавить больше представлений в наше приложение опросов.