Модели ¶

Типы полей ¶

Каждое поле в вашей модели должно быть экземпляром 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

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

Список вариантов выглядит так:

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 добавляет в каждый шаблон следующее поле:

id = models.AutoField(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

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)

Также важно передать параметры, которые могут быть приняты методом модели, это роль . Время от времени Django расширяет возможности встроенных методов модели, добавляя новые параметры. Если вы используете определения методов в своих определениях, вы можете быть уверены, что ваш код будет автоматически обрабатывать эти параметры при их добавлении.*args, **kwargs *args, **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 для атрибута class 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 , будет использоваться только первое вхождение, а все остальные будут проигнорированы.

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

Обратите внимание, что наследование от нескольких моделей, которые имеют 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 это обычно не разрешено для полей модели. Если неабстрактный базовый класс модели имеет поле auteur , невозможно создать другое поле модели или установить именованный атрибут auteur в классах, которые наследуются от этого базового класса.

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

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

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

Django сообщает об ошибке, FieldError если вы переопределяете поле шаблона родительского класса.