Справочник по экземплярам моделей

Создание объектов

Чтобы создать новый экземпляр модели, создайте его так же, как экземпляр любого другого класса Python:

class Model(**kwargs) [исходный код]

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

from django.db.models import DEFERRED


@classmethod
def from_db(cls, db, field_names, values):
    # Default implementation of from_db() (subject to change and could
    # be replaced with super()).
    if len(values) != len(cls._meta.concrete_fields):
        values = list(values)
        values.reverse()
        values = [
            values.pop() if f.attname in field_names else DEFERRED
            for f in cls._meta.concrete_fields
        ]
    instance = cls(*values)
    instance._state.adding = False
    instance._state.db = db
    # customization to store the original field values on the instance
    instance._loaded_values = dict(
        zip(field_names, (value for value in values if value is not DEFERRED))
    )
    return instance


def save(self, **kwargs):
    # Check how the current values differ from ._loaded_values. For example,
    # prevent changing the creator_id of the model. (This example doesn't
    # support cases where 'creator_id' is deferred).
    if not self._state.adding and (
        self.creator_id != self._loaded_values["creator_id"]
    ):
        raise ValueError("Updating the value of creator isn't allowed")
    super().save(**kwargs)

Обновление объектов из базы данных

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

>>> obj = MyModel.objects.first()
>>> del obj.field
>>> obj.field  # Loads the field from the database

Model.refresh_from_db(using=None, fields=None, from_queryset=None) [исходный код]

Model.arefresh_from_db(using=None, fields=None, from_queryset=None)

Асинхронная версия: arefresh_from_db()

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

1. Все незадержанные поля модели обновляются значениями, которые в данный момент находятся в базе данных.
2. Все кэшированные связи удаляются из обновлённого экземпляра.

Из базы данных повторно загружаются только поля модели. Другие зависящие от базы данных значения, например аннотации, не загружаются повторно. Атрибуты @cached_property также не очищаются.

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

С помощью аргумента fields можно принудительно указать набор загружаемых полей.

Например, чтобы проверить, что вызов update() привёл к ожидаемому обновлению, можно написать тест, похожий на этот:

def test_update_result(self):
    obj = MyModel.objects.create(val=1)
    MyModel.objects.filter(pk=obj.pk).update(val=F("val") + 1)
    # At this point obj.val is still 1, but the value in the database
    # was updated to 2. The object's updated value needs to be reloaded
    # from the database.
    obj.refresh_from_db()
    self.assertEqual(obj.val, 2)

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

class ExampleModel(models.Model):
    def refresh_from_db(self, using=None, fields=None, **kwargs):
        # fields contains the name of the deferred field to be
        # loaded.
        if fields is not None:
            fields = set(fields)
            deferred_fields = self.get_deferred_fields()
            # If any deferred field is going to be loaded
            if fields.intersection(deferred_fields):
                # then load all of them
                fields = fields.union(deferred_fields)
        super().refresh_from_db(using, fields, **kwargs)

Аргумент from_queryset позволяет использовать набор запросов, отличный от созданного на основе _base_manager. Это даёт больше контроля над повторной загрузкой модели. Например, если в модели используется мягкое удаление, можно настроить refresh_from_db() с учётом этого:

obj.refresh_from_db(from_queryset=MyModel.active_objects.all())

Можно кэшировать связанные объекты, которые иначе были бы удалены из обновлённого экземпляра:

obj.refresh_from_db(from_queryset=MyModel.objects.select_related("related_field"))

Перед повторной загрузкой значений модели можно заблокировать строку до конца транзакции:

obj.refresh_from_db(from_queryset=MyModel.objects.select_for_update())

Model.get_deferred_fields() [исходный код]

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

Проверка объектов

Проверка модели состоит из четырёх этапов:

1. Проверка полей модели — Model.clean_fields()
2. Проверка модели в целом — Model.clean()
3. Проверка уникальности полей — Model.validate_unique()
4. Проверка ограничений — Model.validate_constraints()

Все четыре этапа выполняются при вызове метода full_clean() модели.

При использовании ModelForm вызов is_valid() выполнит эти этапы проверки для всех полей, включённых в форму. Дополнительную информацию см. в документации по ModelForm. Вызывать метод full_clean() модели нужно только в том случае, если вы собираетесь самостоятельно обрабатывать ошибки проверки или исключили из ModelForm поля, которые требуют проверки.

Model.full_clean(exclude=None, validate_unique=True, validate_constraints=True) [исходный код]

Этот метод вызывает по порядку Model.clean_fields(), Model.clean(), Model.validate_unique() (если validate_unique имеет значение True) и Model.validate_constraints() (если validate_constraints имеет значение True), а затем вызывает исключение ValidationError с атрибутом message_dict, содержащим ошибки всех четырёх этапов.

Необязательный аргумент exclude позволяет передать set имён полей, которые следует исключить из проверки и очистки. ModelForm использует этот аргумент, чтобы исключить из проверки поля, отсутствующие в форме, поскольку пользователь не смог бы исправить возникшие ошибки.

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

from django.core.exceptions import ValidationError

try:
    article.full_clean()
except ValidationError as e:
    # Do something based on the errors contained in e.message_dict.
    # Display them to a user, or handle them programmatically.
    pass

На первом этапе full_clean() очищает каждое поле по отдельности.

Model.clean_fields(exclude=None) [исходный код]

Этот метод проверяет все поля модели. Необязательный аргумент exclude позволяет передать set имён полей, которые следует исключить из проверки. Если проверка каких-либо полей завершится неудачей, будет вызвано исключение ValidationError.

На втором этапе full_clean() вызывает Model.clean(). Этот метод следует переопределить, чтобы выполнять пользовательскую проверку модели.

Model.clean() [исходный код]

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

import datetime
from django.core.exceptions import ValidationError
from django.db import models
from django.utils.translation import gettext_lazy as _


class Article(models.Model):
    ...

    def clean(self):
        # Don't allow draft entries to have a pub_date.
        if self.status == "draft" and self.pub_date is not None:
            raise ValidationError(_("Draft entries may not have a publication date."))
        # Set the pub_date for published items if it hasn't been set already.
        if self.status == "published" and self.pub_date is None:
            self.pub_date = datetime.date.today()

Однако обратите внимание: как и Model.full_clean(), метод clean() модели не вызывается при вызове метода save().

В примере выше исключение ValidationError, вызванное методом Model.clean(), было создано со строкой, поэтому оно будет сохранено в специальном ключе словаря ошибок — NON_FIELD_ERRORS. Этот ключ используется для ошибок, относящихся ко всей модели, а не к конкретному полю:

from django.core.exceptions import NON_FIELD_ERRORS, ValidationError

try:
    article.full_clean()
except ValidationError as e:
    non_field_errors = e.message_dict[NON_FIELD_ERRORS]

Чтобы связать исключения с конкретным полем, создайте экземпляр ValidationError, передав словарь, ключами которого являются имена полей. Предыдущий пример можно изменить так, чтобы ошибка относилась к полю pub_date:

class Article(models.Model):
    ...

    def clean(self):
        # Don't allow draft entries to have a pub_date.
        if self.status == "draft" and self.pub_date is not None:
            raise ValidationError(
                {"pub_date": _("Draft entries may not have a publication date.")}
            )
        ...

Если во время Model.clean() обнаружены ошибки в нескольких полях, можно также передать словарь, сопоставляющий имена полей с ошибками:

raise ValidationError(
    {
        "title": ValidationError(_("Missing title."), code="required"),
        "pub_date": ValidationError(_("Invalid date."), code="invalid"),
    }
)

Затем full_clean() проверит ограничения уникальности модели.

class Article(models.Model):
    ...

    def clean_fields(self, exclude=None):
        super().clean_fields(exclude=exclude)
        if self.status == "draft" and self.pub_date is not None:
            if exclude and "status" in exclude:
                raise ValidationError(
                    _("Draft entries may not have a publication date.")
                )
            else:
                raise ValidationError(
                    {
                        "status": _(
                            "Set status to draft if there is not a publication date."
                        ),
                    }
                )

Model.validate_unique(exclude=None) [исходный код]

Этот метод похож на clean_fields(), но проверяет ограничения уникальности, заданные с помощью Field.unique, Field.unique_for_date, Field.unique_for_month, Field.unique_for_year или Meta.unique_together модели, а не значения отдельных полей. Необязательный аргумент exclude позволяет передать set имён полей, которые следует исключить из проверки. Если проверка каких-либо полей завершится неудачей, будет вызвано исключение ValidationError.

Объекты UniqueConstraint, определённые в Meta.constraints, проверяются методом Model.validate_constraints().

Обратите внимание: если передать аргумент exclude в validate_unique(), ограничение unique_together, включающее одно из указанных полей, проверяться не будет.

Наконец, full_clean() проверит все остальные ограничения модели.

Model.validate_constraints(exclude=None) [исходный код]

Этот метод проверяет все ограничения, определённые в Meta.constraints. Необязательный аргумент exclude позволяет передать set имён полей, которые следует исключить из проверки. Если проверка каких-либо ограничений завершится неудачей, будет вызвано исключение ValidationError.

Сохранение объектов

Чтобы сохранить объект обратно в базу данных, вызовите save():

Model.save(*, force_insert=False, force_update=False, using=DEFAULT_DB_ALIAS, update_fields=None) [источник]

Model.asave(*, force_insert=False, force_update=False, using=DEFAULT_DB_ALIAS, update_fields=None)

Асинхронная версия: asave()

Подробные сведения об использовании аргументов force_insert и force_update см. в разделе Принудительное выполнение INSERT или UPDATE. Сведения об аргументе update_fields приведены в разделе Указание полей для сохранения.

Если вы хотите изменить поведение сохранения, переопределите этот метод save(). Подробнее см. в разделе Переопределение предопределённых методов модели.

У процесса сохранения модели есть и другие особенности; см. разделы ниже.

>>> b2 = Blog(name="Cheddar Talk", tagline="Thoughts on cheese.")
>>> b2.id  # Returns None, because b2 doesn't have an ID yet.
>>> b2.save()
>>> b2.id  # Returns the ID of your new object.

>>> b3 = Blog(id=3, name="Cheddar Talk", tagline="Thoughts on cheese.")
>>> b3.id  # Returns 3.
>>> b3.save()
>>> b3.id  # Returns 3.

b4 = Blog(id=3, name="Not Cheddar", tagline="Anything but cheese.")
b4.save()  # Overrides the previous blog with ID=3!

Restaurant(pk=1, name="Bob's Cafe").save(force_insert=(Place,))

Restaurant(pk=1, name="Bob's Cafe", rating=4).save(force_insert=(Place, Rating))

>>> product = Product.objects.get(name="Venezuelan Beaver Cheese")
>>> product.number_sold += 1
>>> product.save()

>>> from django.db.models import F
>>> product = Product.objects.get(name="Venezuelan Beaver Cheese")
>>> product.number_sold = F("number_sold") + 1
>>> product.save()

product.name = "Name changed again"
product.save(update_fields=["name"])

Удаление объектов

Model.delete(using=DEFAULT_DB_ALIAS, keep_parents=False) [источник]

Model.adelete(using=DEFAULT_DB_ALIAS, keep_parents=False)

Асинхронная версия: adelete()

Выполняет SQL-оператор DELETE для объекта. Удаляется только объект в базе данных; экземпляр Python продолжает существовать, и его поля по-прежнему содержат данные, кроме первичного ключа, которому присваивается None. Метод возвращает количество удалённых объектов и словарь с количеством удалений для каждого типа объектов.

Подробнее, в том числе об удалении объектов массово, см. в разделе Удаление объектов.

Если вы хотите изменить поведение удаления, переопределите метод delete(). Подробнее см. в разделе Переопределение предопределённых методов модели.

Иногда при использовании многотабличного наследования может потребоваться удалить только данные дочерней модели. Указание keep_parents=True сохранит данные родительской модели.

Сериализация объектов с помощью pickle

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

Другие методы экземпляров модели

Некоторые методы объектов имеют особое назначение.

from django.db import models


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

    def __str__(self):
        return f"{self.first_name} {self.last_name}"

from django.db import models


class MyModel(models.Model):
    id = models.AutoField(primary_key=True)


class MyProxyModel(MyModel):
    class Meta:
        proxy = True


class MultitableInherited(MyModel):
    pass


# Primary keys compared
MyModel(id=1) == MyModel(id=1)
MyModel(id=1) != MyModel(id=2)
# Primary keys are None
MyModel(id=None) != MyModel(id=None)
# Same instance
instance = MyModel(id=None)
instance == instance
# Proxy model
MyModel(id=1) == MyProxyModel(id=1)
# Multi-table inheritance
MyModel(id=1) != MultitableInherited(id=1)

def get_absolute_url(self):
    return "/people/%i/" % self.id

def get_absolute_url(self):
    from django.urls import reverse

    return reverse("people-detail", kwargs={"pk": self.pk})

def get_absolute_url(self):
    return "/%s/" % self.name

<!-- BAD template code. Avoid! -->
<a href="/people/{{ object.id }}/">{{ object.name }}</a>

<a href="{{ object.get_absolute_url }}">{{ object.name }}</a>

Дополнительные методы экземпляров

Помимо save() и delete(), объект модели может иметь некоторые из следующих методов:

Model.get_FOO_display()

Для каждого поля, у которого задан параметр choices, объект будет иметь метод get_FOO_display(), где FOO — имя поля. Этот метод возвращает «понятное для человека» значение поля.

Например:

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=2, choices=SHIRT_SIZES)

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

Model.get_next_by_FOO(**kwargs)

Model.get_previous_by_FOO(**kwargs)

Для каждого поля DateField и DateTimeField, у которого не задан параметр null=True, объект будет иметь методы get_next_by_FOO() и get_previous_by_FOO(), где FOO — имя поля. Эти методы возвращают следующий и предыдущий объект относительно значения поля даты и при необходимости возбуждают исключение DoesNotExist.

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

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

Другие атрибуты