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

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

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

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

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

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

UniqueConstraints, определенные в Meta.constraints, проверяются Model.validate_constraints().

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

Наконец, full_clean() проверит любые другие ограничения вашей модели.

Model.validate_constraints(exclude=None)¶

Этот метод проверяет все ограничения, определенные в Meta.constraints. Необязательный аргумент exclude позволяет вам предоставить набор имен полей для исключения из проверки. Он вызовет 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 по-прежнему будет существовать, и в его полях будут по-прежнему данные, за исключением первичного ключа, установленного на «Нет». Этот метод возвращает количество удаленных объектов и словарь с количеством удалений для каждого типа объекта.

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

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

В некоторых случаях при multi-table наследовании вам может понадобиться удалить только данные дочерней модели. Передав аргумент keep_parents=True, вы сохраните данные родительской модели.

Сериализация объектов¶

При упаковке объекта модели с помощью 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, если объект не существует.

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

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

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