Модели¶

Типы полей¶

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

• Тип столбца, который сообщает базе данных, какой тип данных хранить (например, INTEGER, VARCHAR, TEXT).
• HTML-код по умолчанию widget, используемый при визуализации поля формы (например, <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

A sequence of 2-tuples to use as choices for this field. If this is given, the default form widget will be a select box instead of the standard text field and will limit choices to the choices given.

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

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

Примечание

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

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

Для данного экземпляра модели доступ к отображаемому значению поля с 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.choices, max_length=10)

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

default

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

help_text

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

primary_key

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

Если вы не укажете primary_key = True для каких-либо полей в вашей модели, Django автоматически добавит IntegerField для хранения первичного ключа, поэтому вам не нужно устанавливать 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 предлагает способы определения трех наиболее распространенных типов отношений с базой данных: многие-к-одному (many-to-one), многие-ко-многим (many-to-many) и один-к-одному (one-to-one).

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

class Person(models.Model):
    name = models.CharField(max_length=128)

    def __str__(self):
        return self.name

class Group(models.Model):
    name = models.CharField(max_length=128)
    members = models.ManyToManyField(Person, through='Membership')

    def __str__(self):
        return self.name

class Membership(models.Model):
    person = models.ForeignKey(Person, on_delete=models.CASCADE)
    group = models.ForeignKey(Group, on_delete=models.CASCADE)
    date_joined = models.DateField()
    invite_reason = models.CharField(max_length=64)

>>> ringo = Person.objects.create(name="Ringo Starr")
>>> paul = Person.objects.create(name="Paul McCartney")
>>> beatles = Group.objects.create(name="The Beatles")
>>> m1 = Membership(person=ringo, group=beatles,
...     date_joined=date(1962, 8, 16),
...     invite_reason="Needed a new drummer.")
>>> m1.save()
>>> beatles.members.all()
<QuerySet [<Person: Ringo Starr>]>
>>> ringo.group_set.all()
<QuerySet [<Group: The Beatles>]>
>>> m2 = Membership.objects.create(person=paul, group=beatles,
...     date_joined=date(1960, 8, 1),
...     invite_reason="Wanted to form a band.")
>>> beatles.members.all()
<QuerySet [<Person: Ringo Starr>, <Person: Paul McCartney>]>

>>> beatles.members.add(john, through_defaults={'date_joined': date(1960, 8, 1)})
>>> beatles.members.create(name="George Harrison", through_defaults={'date_joined': date(1960, 8, 1)})
>>> beatles.members.set([john, paul, ringo, george], through_defaults={'date_joined': date(1960, 8, 1)})

>>> Membership.objects.create(person=ringo, group=beatles,
...     date_joined=date(1968, 9, 4),
...     invite_reason="You've been gone for a month and we miss you.")
>>> beatles.members.all()
<QuerySet [<Person: Ringo Starr>, <Person: Paul McCartney>, <Person: Ringo Starr>]>
>>> # This deletes both of the intermediate model instances for Ringo Starr
>>> beatles.members.remove(ringo)
>>> beatles.members.all()
<QuerySet [<Person: Paul McCartney>]>

>>> # Beatles have broken up
>>> beatles.members.clear()
>>> # Note that this deletes the intermediate model instances
>>> Membership.objects.all()
<QuerySet []>

# Find all the groups with a member whose name starts with 'Paul'
>>> Group.objects.filter(members__name__startswith='Paul')
<QuerySet [<Group: The Beatles>]>

# Find all the members of the Beatles that joined after 1 Jan 1961
>>> Person.objects.filter(
...     group__name='The Beatles',
...     membership__date_joined__gt=date(1961,1,1))
<QuerySet [<Person: Ringo Starr]>

>>> ringos_membership = Membership.objects.get(group=beatles, person=ringo)
>>> ringos_membership.date_joined
datetime.date(1962, 8, 16)
>>> ringos_membership.invite_reason
'Needed a new drummer.'

>>> ringos_membership = ringo.membership_set.get(group=beatles)
>>> ringos_membership.date_joined
datetime.date(1962, 8, 16)
>>> ringos_membership.invite_reason
'Needed a new drummer.'

Модели в файлах¶

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

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. Имя поля не может заканчиваться подчеркиванием по тем же причинам.

Однако эти ограничения можно обойти, потому что имя вашего поля не обязательно должно совпадать с именем столбца базы данных. Смотрите параметр 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, *args, **kwargs):
        do_something()
        super().save(*args, **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, *args, **kwargs):
        if self.name == "Yoko Ono's blog":
            return # Yoko shall never have her own blog!
        else:
            super().save(*args, **kwargs)  # Call the "real" save() method.

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

Также важно, чтобы вы передавали аргументы, которые можно передать методу модели - это то, что делает часть *args, **kwargs. Django будет время от времени расширять возможности встроенных методов модели, добавляя новые аргументы. Если вы используете *args, **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, force_insert=False, force_update=False, using=None, update_fields=None
    ):
        self.slug = slugify(self.name)
        if update_fields is not None and "name" in update_fields:
            update_fields = {"slug"}.union(update_fields)
        super().save(
            force_insert=force_insert,
            force_update=force_update,
            using=using,
            update_fields=update_fields,
        )

Более подробную информацию см. в разделе Указание полей для сохранения.

Выполнение пользовательского 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, вы можете перейти от объекта Place к объекту Restaurant, используя строчную версию имени модели:

>>> 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'.

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

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

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

Прокси-модели объявлены как обычные модели. Вы сообщаете 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

Название поля «hiding» не допускается¶

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

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

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

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

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

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