Справочник по методам модели¶

Настройка загрузки модели¶

classmethod Model.from_db(db, field_names, values)[исходный код]¶

Метод from_db() можно использовать для настройки создания экземпляра модели при загрузке из базы данных.

Аргумент db содержит псевдоним базы данных для базы данных, из которой загружена модель, field_names содержит имена всех загруженных полей, а values содержит загруженные значения для каждого поля в field_names. field_names находятся в том же порядке, что и values. Если присутствуют все поля модели, то values гарантированно будут в том порядке, в котором их ожидает __init__(). То есть экземпляр может быть создан с помощью cls(* values). Если какие-либо поля отложены, они не появятся в field_names. В этом случае присвойте значение django.db.models.DEFERRED каждому из пропущенных полей.

Помимо создания новой модели, метод from_db() должен установить флаги adding и db в атрибуте _state нового экземпляра.

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

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, *args, **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(*args, **kwargs)

В приведенном выше примере показана полная реализация from_db(), чтобы прояснить, как это делается. В этом случае, конечно, можно было бы просто использовать вызов super() в методе from_db().

Автоинкрементные первичные ключи¶

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

Невозможно определить, какое значение идентификатора будет перед вызовом save(), потому что это значение рассчитывается вашей базой данных, а не Django.

Для удобства каждая модель имеет AutoField с именем id по умолчанию, если вы явно не укажете primary_key=True для поля в вашей модели. Смотрите документацию для AutoField для получения более подробной информации.

>>> 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!

Что происходит, когда вы сохраняете?¶

Когда вы сохраняете объект, Django выполняет следующие шаги:

1. Посылает сигнал предварительного сохранения pre-save. Передается сигнал pre_save, позволяющий функциям, прослушивающим этот сигнал, что-то делать.

2. Предварительная обработка данных. Каждый метод поля pre_save() вызывается для выполнения любой необходимой автоматической модификации данных. Например, поля даты/времени переопределяют pre_save() для реализации auto_now_add и auto_now.

3. Подготовка данных для базы данных. Метод каждого поля get_db_prep_save() должен предоставить свое текущее значение в виде данных, которые можно записать в базу данных.

   Большинство полей не требуют подготовки данных. Простые типы данных, такие как целые числа и строки, «готовы к записи» в виде объекта Python. Однако более сложные типы данных часто требуют некоторой модификации.

   Например, поля DateField используют объект datetime Python для хранения данных. Базы данных не хранят объекты datetime, поэтому значение поля должно быть преобразовано в ISO-совместимую строку даты для вставки в базу данных.

4. Вставка данных в базу данных. Предварительно обработанные, подготовленные данные составляются в оператор SQL для вставки в базу данных.

5. Посылает сигнал post-save после сохранения. Передается сигнал post_save, позволяющий любым функциям, прослушивающим этот сигнал, что-то делать.

Как Django узнает, когда использовать UPDATE или INSERT¶

Вы могли заметить, что объекты базы данных Django используют тот же метод save() для создания и изменения объектов. Django абстрагируется от необходимости использования INSERT или UPDATE SQL-операторов. В частности, когда вы вызываете save() и атрибут первичного ключа объекта не определяет default или db_default, Django следует этому алгоритму:

• Если для атрибута первичного ключа объекта установлено значение, которое оценивается как True (т.е. значение, отличное от None или пустой строки), Django выполняет UPDATE.
• Если атрибут первичного ключа объекта не установлен или если UPDATE ничего не обновил (например, если первичному ключу присвоено значение, которого нет в базе данных), Django выполняет INSERT.

Если атрибут первичного ключа объекта определяет default или db_default, то Django выполняет UPDATE, если это существующий экземпляр модели и первичный ключ установлен на значение, существующее в базе данных. В противном случае Django выполняет INSERT.

Единственное, что здесь нужно сделать, это то, что вы должны быть осторожны, чтобы не указывать значение первичного ключа явно при сохранении новых объектов, если вы не можете гарантировать, что значение первичного ключа не используется. Подробнее об этом нюансе см. В разделе «Явное указание значений авто-первичного ключа» выше и «Форсирование INSERT или UPDATE» ниже.

В Django 1.5 и более ранних версиях Django сделал SELECT, когда был установлен атрибут первичного ключа. Если SELECT нашел строку, то Django сделал UPDATE, в противном случае он сделал INSERT. Старый алгоритм приводит к еще одному запросу в случае UPDATE. В некоторых редких случаях база данных не сообщает, что строка была обновлена, даже если база данных содержит строку для значения первичного ключа объекта. Примером является триггер PostgreSQL ON UPDATE, который возвращает NULL. В таких случаях можно вернуться к старому алгоритму, установив параметр select_on_save в True.

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))

Обновление атрибутов на основе существующих полей¶

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

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

Если старое значение number_sold, полученное из базы данных, равнялось 10, то значение 11 будет записано обратно в базу данных.

Этот процесс можно сделать более надежным, avoiding a race condition, а также несколько ускорить, если выразить обновление относительно исходного значения поля, а не как явное присвоение нового значения. Для выполнения такого рода относительного обновления в Django предусмотрена функция F expressions. Используя F expressions, предыдущий пример можно выразить так:

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

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

Указание полей для сохранения¶

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

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

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

Указание update_fields приведет к обновлению.

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

__str__()¶

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

Метод __str__() вызывается всякий раз, когда вы вызываете str() для объекта. Django использует str(obj) в нескольких местах. В частности, для отображения объекта на сайте администратора Django и в качестве значения, вставляемого в шаблон при отображении объекта. Таким образом, вы всегда должны возвращать хорошее, удобочитаемое представление модели из метода __str__().

Например:

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}"

__eq__()¶

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

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

Например:

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)

__hash__()¶

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

Метод __hash__() основан на значении первичного ключа экземпляра. Это эффективно hash(obj.pk). Если у экземпляра нет значения первичного ключа, то будет вызвано TypeError (в противном случае метод __hash__() будет возвращать разные значения до и после сохранения экземпляра, но изменяя __hash__() значение экземпляра запрещено в Python.

get_absolute_url()¶

Model.get_absolute_url()¶

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

Например:

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

Хотя этот код является правильным и простым, он может быть не самым переносимым способом написания такого рода метода. Функция reverse() обычно является наилучшим подходом.

Например:

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

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

В одном месте Django использует get_absolute_url() в приложении администратора. Если объект определяет этот метод, страница редактирования объекта будет иметь ссылку «View on site», которая приведет вас непосредственно к общему представлению объекта, как указано в get_absolute_url().

Аналогично, пара других частей Django, таких как инфраструктура канала синдикации, используют get_absolute_url(), когда она определена. Если для каждого экземпляра вашей модели имеет смысл иметь уникальный URL-адрес, вы должны определить get_absolute_url().

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

Хорошей практикой является использование get_absolute_url() в шаблонах вместо жесткого кодирования URL-адресов ваших объектов. Например, этот код шаблона плох:

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

Этот шаблон кода намного лучше:

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

Логика здесь заключается в том, что если вы изменяете структуру URL-адресов ваших объектов, даже для чего-то простого, например, для исправления орфографической ошибки, вам не нужно отслеживать каждое место, где может быть создан URL-адрес. Укажите его один раз в get_absolute_url() и пусть весь ваш другой код вызывает только его.

_state¶

Model._state¶

Атрибут _state относится к объекту ModelState, который отслеживает жизненный цикл экземпляра модели.

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

У вновь созданных экземпляров есть adding=True и db=None, поскольку они еще не сохранены. Экземпляры, полученные из QuerySet, будут иметь adding=False и db в качестве псевдонима связанной базы данных.