Написание вашего первого приложения Django, часть 1

Давайте учиться на примерах.

В этом руководстве мы покажем вам создание простого приложения опросов.

Оно будет состоять из двух частей:

• Общедоступный сайт, позволяющий людям просматривать опросы и голосовать в них.
• Админ-сайт, позволяющий добавлять, изменять и удалять опросы.

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

$ python -c "import django; print(django.get_version())"

Если Django установлен, вы увидите версию вашей установки. Если нет, вы получите ошибку, сообщающую «Нет модуля django».

Это руководство написано для Django 1.8 и Python 3.2 или более поздней версии. Если версия Django не совпадает, вы можете обратиться к руководству для вашей версии Django, используя переключатель версий в правом нижнем углу этой страницы, или обновите Django до последней версии. Если вы по-прежнему используете Python 2.7, вам нужно будет немного изменить примеры кода, как описано в комментариях.

См. Как установить Django для получения советов по удалению более старых версий Django и установке более новой.

Создание проекта

Если вы впервые используете Django, вам нужно будет выполнить начальную настройку. В частности, вам нужно будет автоматически сгенерировать код, который создает проект Django проект – набор настроек для экземпляра Django, включая конфигурацию базы данных, специфичные для Django параметры и параметры, специфичные для приложения.

Из командной строки, cd в каталог, где вы хотите сохранить свой код, затем выполните следующую команду:

$ django-admin startproject mysite

Это создаст mysite каталог в вашем текущем каталоге. Если это не сработало, см. Проблемы с запуском django-admin.

Давайте посмотрим, что создал startproject:

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

Эти файлы:

• Внешний mysite/ корневой каталог просто содержит ваш проект. Его имя не имеет значения для Django; вы можете переименовать его в любое другое.
• manage.py: Утилита командной строки, которая позволяет вам взаимодействовать с этим проектом Django различными способами. Вы можете прочитать все подробности о manage.py в django-admin и manage.py.
• Внутренний mysite/ каталог — это фактический пакет Python для вашего проекта. Его имя — это имя пакета Python, которое вам нужно будет использовать для импорта чего-либо внутри него (например, mysite.urls).
• mysite/__init__.py: Пустой файл, который сообщает Python, что этот каталог следует рассматривать как пакет Python. (Прочитайте подробнее о пакетах в официальной документации Python, если вы новичок в Python.)
• mysite/settings.py: Настройки/конфигурация для этого проекта Django. Настройки Django расскажут вам обо всех настройках.
• mysite/urls.py: Объявления URL для этого проекта Django; «оглавление» вашего сайта на базе Django. Вы можете узнать больше о URL-адресах в диспетчере URL.
• mysite/wsgi.py: Точка входа для совместимых с WSGI веб-серверов для обслуживания вашего проекта. См. Как развернуть с помощью WSGI для получения более подробной информации.

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

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

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

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

• ENGINE – Либо 'django.db.backends.sqlite3', 'django.db.backends.postgresql_psycopg2', '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 – Админ-сайт. Вы будете использовать его в части 2 этого руководства.
• django.contrib.auth – Система аутентификации.
• django.contrib.contenttypes – Фреймворк для типов контента.
• django.contrib.sessions – Фреймворк для управления сессиями.
• django.contrib.messages – Фреймворк для сообщений.
• django.contrib.staticfiles – Фреймворк для управления статическими файлами.

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

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

$ python manage.py migrate

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

Сервер разработки

Давайте проверим, работает ли ваш проект Django. Перейдите в внешний каталог mysite (если вы ещё этого не сделали) и выполните следующие команды:

$ python manage.py runserver

В командной строке вы увидите следующий вывод:

Performing system checks...

0 errors found
April 04, 2017 - 15:50:53
Django version 1.8, using settings 'mysite.settings'
Starting development server at http://127.0.0.1:8000/
Quit the server with CONTROL-C.

Вы запустили сервер разработки Django, лёгкий веб-сервер, написанный чисто на Python. Мы включили его в Django, чтобы вы могли быстро разрабатывать приложения, не заботясь о настройке сервера для производства (например, Apache), пока не будете готовы к запуску в производстве.

Сейчас хорошее время отметить: не используйте этот сервер в среде, напоминающей производство. Он предназначен только для использования во время разработки. (Мы занимаемся разработкой веб-фреймворков, а не веб-серверов.)

Теперь, когда сервер запущен, откройте в своём веб-браузере http://127.0.0.1:8000/. Вы увидите страницу «Добро пожаловать в Django» приятного светло-голубого пастельного цвета. Всё работает!

$ python manage.py runserver 8080

$ python manage.py runserver 0.0.0.0:8000

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

Теперь, когда ваша среда — «проект» — настроена, вы готовы приступить к работе.

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

Ваши приложения могут находиться где угодно в вашем пути Python. В этом учебнике мы создадим наше приложение опроса рядом с вашим файлом manage.py, чтобы его можно было импортировать как самостоятельный модуль верхнего уровня, а не как подмодуль mysite.

Чтобы создать своё приложение, убедитесь, что вы находитесь в той же директории, что и manage.py, и введите эту команду:

$ python manage.py startapp polls

Это создаст директорию polls, которая организована так:

polls/
    __init__.py
    admin.py
    migrations/
        __init__.py
    models.py
    tests.py
    views.py

Эта структура каталогов будет содержать приложение опроса.

Первый шаг в написании веб-приложения базы данных в 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)
    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 установлено.

Измените файл mysite/settings.py ещё раз и измените настройку INSTALLED_APPS, включив строку 'polls'. Так это будет выглядеть:

INSTALLED_APPS = (
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'polls',
)

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

$ python manage.py makemigrations polls

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

Migrations for 'polls':
  0001_initial.py:
    - Create model Question
    - Create model Choice
    - 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

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

BEGIN;
CREATE TABLE "polls_choice" (
    "id" serial NOT NULL PRIMARY KEY,
    "choice_text" varchar(200) NOT NULL,
    "votes" integer NOT NULL
);
CREATE TABLE "polls_question" (
    "id" serial NOT NULL PRIMARY KEY,
    "question_text" varchar(200) NOT NULL,
    "pub_date" timestamp with time zone NOT NULL
);
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 Django считает необходимым. Это полезно для проверки того, что Django собирается сделать, или если у вас есть администраторы базы данных, которым требуются SQL-скрипты для изменений.

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

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

$ python manage.py migrate
Operations to perform:
  Synchronize unmigrated apps: staticfiles, messages
  Apply all migrations: admin, contenttypes, polls, auth, sessions
Synchronizing apps without migrations:
  Creating tables...
    Running deferred SQL...
  Installing custom SQL...
Running migrations:
  Rendering model states... DONE
  Applying <migration name>... OK

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

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

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

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

Для получения полной информации о том, что может делать утилита manage.py, обратитесь к документации manage.py.

Работа с API

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

$ python manage.py shell

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

>>> import django
>>> django.setup()

После того как вы окажетесь в оболочке, изучите API базы данных:

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

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

# 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. Note that this might say "1L" instead of "1", depending
# on which database you're using. That's no biggie; it just means your
# database backend prefers to return integers as Python long integer
# objects.
>>> 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()
[<Question: Question object>]

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

from django.db import models

class Question(models.Model):
    # ...
    def __str__(self):              # __unicode__ on Python 2
        return self.question_text

class Choice(models.Model):
    # ...
    def __str__(self):              # __unicode__ on Python 2
        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 Question, Choice

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

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

# 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()
[<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)
[<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 базы данных.

Когда вы освоитесь с API, прочитайте часть 2 этого учебника, чтобы настроить автоматическую административную панель Django.