Ссылка на экземпляр модели

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

classmethod Model.from_db(db, field_names, values) [source]

Метод 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, **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)

Приведенный выше пример демонстрирует полную реализацию 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 используют объект Python datetime для хранения данных. Базы данных не хранят объекты datetime, поэтому значение поля должно быть преобразовано в строку даты в формате ISO для вставки в базу данных.

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

Как Django определяет UPDATE или INSERT

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

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

Процесс можно сделать более надёжным, избегая гонки, а также немного быстрее, выразив обновление относительно исходного значения поля, а не как явное присваивание нового значения. 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 expressions и их использование в запросах обновления.

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

Если 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__() [source]

Метод __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__() [source]

Метод равенства определён таким образом, что экземпляры с одинаковым значением первичного ключа и одинаковым конкретным классом считаются равными, за исключением экземпляров с значением первичного ключа 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__() [source]

Метод __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(), — это приложение администрирования. Если объект определяет этот метод, страница редактирования объекта будет содержать ссылку «Просмотреть на сайте», которая переведёт вас напрямую к публичной просмотровой странице объекта, как задано 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, установленные на псевдоним связанной базы данных.

_is_pk_set()

Model._is_pk_set() [source]

Метод _is_pk_set() возвращает, установлен ли pk экземпляра модели. Он абстрагирует определение первичного ключа модели, обеспечивая согласованное поведение независимо от конкретной конфигурации pk.