Модели

Типы полей

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

• Тип столбца, который сообщает базе данных, какой тип данных хранить (например, INTEGER, VARCHAR, TEXT).
• Предпочитаемый HTML виджет для отображения поля формы (например, <input type="text">, <select>).
• Минимальные требования к валидации, используемые в админ-панели Django и в автоматически сгенерированных формах.

Django поставляется с десятками встроенных типов полей; полный список можно найти в справочнике по полям модели. Вы можете легко написать свои собственные поля, если встроенные поля Django не подходят; см. Как создать пользовательские поля модели.

Параметры полей

Каждое поле принимает определенный набор параметров, специфичных для поля (документировано в справочнике по полям модели). Например, CharField (и его подклассы) требуют аргумент max_length, который определяет размер поля базы данных VARCHAR, используемого для хранения данных.

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

null

Если True, Django будет хранить пустые значения как NULL в базе данных. По умолчанию False.

blank

Если True, поле может быть пустым. По умолчанию False.

Обратите внимание, что это отличается от null. null касается только базы данных, в то время как blank касается валидации. Если поле имеет blank=True, валидация форм позволит вводить пустые значения. Если поле имеет blank=False, поле будет обязательным.

choices

Последовательность пар значений, отображаемых пользователем, отображение, тип перечисления или вызываемый объект (который не принимает аргументы и возвращает любой из предыдущих форматов), используемые в качестве вариантов для этого поля. Если это указано, виджет формы по умолчанию будет выпадающим списком вместо стандартного текстового поля и будет ограничивать выбор заданными вариантами.

Список вариантов выглядит следующим образом:

YEAR_IN_SCHOOL_CHOICES = [
    ("FR", "Freshman"),
    ("SO", "Sophomore"),
    ("JR", "Junior"),
    ("SR", "Senior"),
    ("GR", "Graduate"),
]

Примечание

Каждый раз, когда изменяется порядок choices, создается новая миграция.

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

Для получения отображаемого значения поля с choices в экземпляре модели можно использовать метод get_FOO_display(). Например:

from django.db import models


class Person(models.Model):
    SHIRT_SIZES = {
        "S": "Small",
        "M": "Medium",
        "L": "Large",
    }
    name = models.CharField(max_length=60)
    shirt_size = models.CharField(max_length=1, choices=SHIRT_SIZES)

>>> p = Person(name="Fred Flintstone", shirt_size="L")
>>> p.save()
>>> p.shirt_size
'L'
>>> p.get_shirt_size_display()
'Large'

Вы также можете использовать классы перечислений для определения choices лаконичным способом:

from django.db import models


class Runner(models.Model):
    MedalType = models.TextChoices("MedalType", "GOLD SILVER BRONZE")
    name = models.CharField(max_length=60)
    medal = models.CharField(blank=True, choices=MedalType, max_length=10)

Дополнительные примеры можно найти в справочнике по полям модели.

default

Значение по умолчанию для поля. Это может быть значение или вызываемый объект. Если вызываемый объект, он будет вызываться каждый раз при создании нового объекта.

db_default

Значение по умолчанию для поля, вычисляемое базой данных. Это может быть литеральное значение или функция базы данных.

Если и db_default, и Field.default заданы, default будет иметь приоритет при создании экземпляров в коде Python. db_default все равно будет установлено на уровне базы данных и будет использоваться при вставке строк вне ORM или при добавлении нового поля в миграцию.

help_text

Дополнительный текст «помощи», который будет отображаться вместе с виджетом формы. Это полезно для документации, даже если ваше поле не используется в форме.

primary_key

Если True, это поле является первичным ключом для модели.

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

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

from django.db import models


class Fruit(models.Model):
    name = models.CharField(max_length=100, primary_key=True)

>>> fruit = Fruit.objects.create(name="Apple")
>>> fruit.name = "Pear"
>>> fruit.save()
>>> Fruit.objects.values_list("name", flat=True)
<QuerySet ['Apple', 'Pear']>

unique

Если True, это поле должно быть уникальным в таблице.

Опять же, это лишь краткие описания наиболее распространенных параметров полей. Полные сведения можно найти в справочнике по общим параметрам полей модели.

Автоматические поля первичного ключа

По умолчанию Django предоставляет для каждой модели поле первичного ключа с автоматическим нарастанием, тип которого задается в AppConfig.default_auto_field для каждой приложения или глобально в настройке DEFAULT_AUTO_FIELD. Например:

id = models.BigAutoField(primary_key=True)

Если вы хотите указать пользовательский первичный ключ, укажите primary_key=True для одного из ваших полей. Если Django видит, что вы явно установили Field.primary_key, он не добавит автоматическое поле id.

Каждая модель требует ровно одного поля с primary_key=True (либо явно объявленного, либо автоматически добавленного).

Имена полей с добавлением описаний

Каждый тип поля, кроме ForeignKey, ManyToManyField и OneToOneField, принимает необязательный первый позиционный аргумент – имя поля с описанием. Если имя поля с описанием не указано, Django автоматически создаст его, используя имя атрибута поля, преобразуя нижние подчёркивания в пробелы.

В этом примере имя поля с описанием – "person's first name":

first_name = models.CharField("person's first name", max_length=30)

В этом примере имя поля с описанием – "first name":

first_name = models.CharField(max_length=30)

ForeignKey, ManyToManyField и OneToOneField требуют, чтобы первым аргументом была модель класса, поэтому используйте ключевой аргумент verbose_name:

poll = models.ForeignKey(
    Poll,
    on_delete=models.CASCADE,
    verbose_name="the related poll",
)
sites = models.ManyToManyField(Site, verbose_name="list of sites")
place = models.OneToOneField(
    Place,
    on_delete=models.CASCADE,
    verbose_name="related place",
)

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

Связи

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

from django.db import models


class Manufacturer(models.Model):
    # ...
    pass


class Car(models.Model):
    manufacturer = models.ForeignKey(Manufacturer, on_delete=models.CASCADE)
    # ...

class Car(models.Model):
    company_that_makes_it = models.ForeignKey(
        Manufacturer,
        on_delete=models.CASCADE,
    )
    # ...

from django.db import models


class Topping(models.Model):
    # ...
    pass


class Pizza(models.Model):
    # ...
    toppings = models.ManyToManyField(Topping)

Модели в разных файлах

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

from django.db import models
from geography.models import ZipCode


class Restaurant(models.Model):
    # ...
    zip_code = models.ForeignKey(
        ZipCode,
        on_delete=models.SET_NULL,
        blank=True,
        null=True,
    )

Ограничения имён полей

Django устанавливает некоторые ограничения на имена полей модели:

1. Имя поля не может быть зарезервированным словом Python, так как это приведёт к синтаксической ошибке Python. Например:

   class Example(models.Model):
       pass = models.IntegerField() # 'pass' is a reserved word!
   

2. Имя поля не может содержать более одного подряд идущего символа нижнего подчеркивания, из-за того, как работает синтаксис поиска запросов Django. Например:

   class Example(models.Model):
       foo__bar = models.IntegerField()  # 'foo__bar' has two underscores!
   

3. Имя поля не может заканчиваться символом нижнего подчеркивания по аналогичным причинам.
4. Имя поля не может быть check, так как это переопределит метод Model.check() фреймворка проверки.

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

SQL-зарезервированные слова, такие как join, where или select, разрешены в качестве имён полей модели, потому что Django экранирует все имена таблиц и столбцов базы данных в каждом подлежащем SQL-запросе. Он использует синтаксис цитирования, специфичный для конкретного движка базы данных.

Пользовательские типы полей

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

Переопределение предопределенных методов модели

Существует ещё один набор методов модели, которые обобщают ряд функций поведения базы данных, которые вы захотите настроить. В частности, вам часто захочется изменить способ работы save() и delete().

Вы можете свободно переопределять эти методы (и любые другие методы модели) для изменения поведения.

Классический пример переопределения встроенных методов — если вы хотите, чтобы что-то происходило каждый раз, когда вы сохраняете объект. Например (см. save() для документации параметров, которые он принимает):

from django.db import models


class Blog(models.Model):
    name = models.CharField(max_length=100)
    tagline = models.TextField()

    def save(self, **kwargs):
        do_something()
        super().save(**kwargs)  # Call the "real" save() method.
        do_something_else()

Вы также можете предотвратить сохранение:

from django.db import models


class Blog(models.Model):
    name = models.CharField(max_length=100)
    tagline = models.TextField()

    def save(self, **kwargs):
        if self.name == "Yoko Ono's blog":
            return  # Yoko shall never have her own blog!
        else:
            super().save(**kwargs)  # Call the "real" save() method.

Важно помнить о вызове метода суперкласса — это то, что super().save(**kwargs) бизнес — чтобы гарантировать, что объект всё ещё сохраняется в базе данных. Если вы забудете вызвать метод суперкласса, поведение по умолчанию не произойдёт, и база данных не будет затронута.

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

Если вы хотите обновить значение поля в методе save(), вы также можете добавить это поле в update_fields ключевой аргумент. Это гарантирует, что поле будет сохранено, когда update_fields указано. Например:

from django.db import models
from django.utils.text import slugify


class Blog(models.Model):
    name = models.CharField(max_length=100)
    slug = models.TextField()

    def save(self, **kwargs):
        self.slug = slugify(self.name)
        if (
            update_fields := kwargs.get("update_fields")
        ) is not None and "name" in update_fields:
            kwargs["update_fields"] = {"slug"}.union(update_fields)
        super().save(**kwargs)

См. Указание полей для сохранения для получения дополнительной информации.

Выполнение пользовательского SQL

Ещё один распространённый шаблон — написание пользовательских SQL-заявлений в методах модели и методах уровня модуля. Дополнительные сведения о работе с SQL см. в документации по использованию необработанного SQL.

Абстрактные базовые классы

Абстрактные базовые классы полезны, когда вы хотите поместить общую информацию в несколько других моделей. Вы пишете базовый класс и помещаете abstract=True в класс Meta. Эта модель не будет использоваться для создания таблицы базы данных. Вместо этого, при использовании в качестве базового класса для других моделей, её поля будут добавлены к полям дочернего класса.

Пример:

from django.db import models


class CommonInfo(models.Model):
    name = models.CharField(max_length=100)
    age = models.PositiveIntegerField()

    class Meta:
        abstract = True


class Student(CommonInfo):
    home_group = models.CharField(max_length=5)

Модель Student будет иметь три поля: name, age и home_group. Модель CommonInfo не может использоваться как обычная модель Django, так как это абстрактный базовый класс. Она не генерирует таблицу базы данных, не имеет менеджера и не может быть создана или сохранена напрямую.

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

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

from django.db import models


class CommonInfo(models.Model):
    # ...
    class Meta:
        abstract = True
        ordering = ["name"]


class Student(CommonInfo):
    # ...
    class Meta(CommonInfo.Meta):
        db_table = "student_info"

from django.db import models


class CommonInfo(models.Model):
    name = models.CharField(max_length=100)
    age = models.PositiveIntegerField()

    class Meta:
        abstract = True
        ordering = ["name"]


class Unmanaged(models.Model):
    class Meta:
        abstract = True
        managed = False


class Student(CommonInfo, Unmanaged):
    home_group = models.CharField(max_length=5)

    class Meta(CommonInfo.Meta, Unmanaged.Meta):
        pass

from django.db import models


class Base(models.Model):
    m2m = models.ManyToManyField(
        OtherModel,
        related_name="%(app_label)s_%(class)s_related",
        related_query_name="%(app_label)s_%(class)ss",
    )

    class Meta:
        abstract = True


class ChildA(Base):
    pass


class ChildB(Base):
    pass

from common.models import Base


class ChildB(Base):
    pass

Наследование с отдельными таблицами

Второй тип наследования моделей, поддерживаемый Django, — это когда каждая модель в иерархии является моделью сама по себе. Каждая модель соответствует собственной таблице базы данных и может быть запрошена и создана индивидуально. Отношение наследования вводит связи между дочерней моделью и каждой из родительских моделей (через автоматически созданное OneToOneField). Например:

from django.db import models


class Place(models.Model):
    name = models.CharField(max_length=50)
    address = models.CharField(max_length=80)


class Restaurant(Place):
    serves_hot_dogs = models.BooleanField(default=False)
    serves_pizza = models.BooleanField(default=False)

Все поля модели Place также будут доступны в модели Restaurant, хотя данные будут храниться в другой таблице базы данных. Поэтому оба варианта допустимы:

>>> Place.objects.filter(name="Bob's Cafe")
>>> Restaurant.objects.filter(name="Bob's Cafe")

Если у вас есть объект типа Place, который также является объектом типа Restaurant, вы можете получить доступ к объекту типа Restaurant из объекта типа Place, используя нижний регистр имени модели:

>>> p = Place.objects.get(id=12)
# If p is a Restaurant object, this will give the child class:
>>> p.restaurant
<Restaurant: ...>

Однако, если p в приведённом примере не является Restaurant (он был создан напрямую как объект Place или является родителем какого-либо другого класса), обращение к p.restaurant вызовет исключение Restaurant.DoesNotExist.

Автоматически созданное OneToOneField в модели Restaurant, которое связывает её с моделью Place, выглядит так:

place_ptr = models.OneToOneField(
    Place,
    on_delete=models.CASCADE,
    parent_link=True,
    primary_key=True,
)

Вы можете переопределить это поле, объявив своё OneToOneField с parent_link=True в модели Restaurant.

class ChildModel(ParentModel):
    # ...
    class Meta:
        # Remove parent's ordering effect
        ordering = []

class Supplier(Place):
    customers = models.ManyToManyField(Place)

Reverse query name for 'Supplier.customers' clashes with reverse query
name for 'Supplier.place_ptr'.

HINT: Add or change a related_name argument to the definition for
'Supplier.customers' or 'Supplier.place_ptr'.

Модели-прокси

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

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

Модели-прокси объявляются как обычные модели. Вы сообщаете Django, что это модель-прокси, установив атрибут proxy класса Meta в значение True.

Например, предположим, что вы хотите добавить метод к модели Person. Вы можете сделать это так:

from django.db import models


class Person(models.Model):
    first_name = models.CharField(max_length=30)
    last_name = models.CharField(max_length=30)


class MyPerson(Person):
    class Meta:
        proxy = True

    def do_something(self):
        # ...
        pass

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

>>> p = Person.objects.create(first_name="foobar")
>>> MyPerson.objects.get(first_name="foobar")
<MyPerson: foobar>

Вы также можете использовать модель-прокси для определения другого порядка по умолчанию в модели. Вам может не всегда потребоваться сортировать модель Person, но регулярно сортировать по атрибуту last_name при использовании прокси:

class OrderedPerson(Person):
    class Meta:
        ordering = ["last_name"]
        proxy = True

Теперь обычные запросы к Person будут несортированными, а запросы к OrderedPerson будут отсортированы по last_name.

Модели-прокси наследуют атрибуты Meta так же, как и обычные модели.

from django.db import models


class NewManager(models.Manager):
    # ...
    pass


class MyPerson(Person):
    objects = NewManager()

    class Meta:
        proxy = True

# Create an abstract class for the new manager.
class ExtraManagers(models.Model):
    secondary = NewManager()

    class Meta:
        abstract = True


class MyPerson(Person, ExtraManagers):
    class Meta:
        proxy = True

Наследование от нескольких классов

Как и в Python, модель Django может наследоваться от нескольких родительских моделей. Имейте в виду, что применяются обычные правила разрешения имен Python. Первый базовый класс, в котором появляется определенное имя (например, Meta), будет использоваться; например, это означает, что если несколько родителей содержат класс Meta, будет использоваться только первый, а все остальные будут проигнорированы.

В целом, вам не нужно наследовать от нескольких родителей. Основной случай использования, где это полезно, — это классы «миксины»: добавление определенного дополнительного поля или метода ко всем классам, которые наследуют миксин. Старайтесь сохранять иерархии наследования максимально простыми и понятными, чтобы вам не приходилось бороться с тем, откуда поступает та или иная информация.

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

class Article(models.Model):
    article_id = models.AutoField(primary_key=True)
    ...


class Book(models.Model):
    book_id = models.AutoField(primary_key=True)
    ...


class BookReview(Book, Article):
    pass

Или используйте общего предка для хранения поля AutoField. Это требует использования явного поля OneToOneField от каждой родительской модели до общего предка, чтобы избежать конфликта между полями, которые автоматически генерируются и наследуются дочерним классом:

class Piece(models.Model):
    pass


class Article(Piece):
    article_piece = models.OneToOneField(
        Piece, on_delete=models.CASCADE, parent_link=True
    )
    ...


class Book(Piece):
    book_piece = models.OneToOneField(Piece, on_delete=models.CASCADE, parent_link=True)
    ...


class BookReview(Book, Article):
    pass

Использование имени поля для «скрытия» запрещено

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

Это ограничение не относится к полям модели, унаследованным от абстрактной модели. Такие поля можно переопределить другим полем или значением, или удалить, установив field_name = None.

Переопределение полей в родительской модели приводит к трудностям при инициализации новых экземпляров (указании поля, которое инициализируется в Model.__init__) и сериализации. Эти функции в обычном наследовании классов Python не нужно обрабатывать таким же образом, поэтому разница между наследованием моделей Django и наследованием классов Python не произвольная.

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

Django поднимет исключение FieldError, если вы переопределите любое поле модели в любой родительской модели.

Обратите внимание, что из-за способа разрешения полей во время определения класса поля модели, унаследованные от нескольких абстрактных родительских моделей, разрешаются в строгом порядке «глубина-вперед». Это отличается от стандартного Python MRO, который разрешается в порядке «ширина-вперед» в случаях наследования в форме ромба. Эта разница влияет только на сложные иерархии моделей, которых (как сказано выше) следует избегать.