模型实例参考¶

自定义模型加载¶

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() 方法还必须在新实例的 _state 属性中设置 adding 和 db 标志。

下面是一个展示如何记录从数据库加载的字段初始值的示例

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() 实现，以阐明其做法。在这种情况下，可以在 from_db() 方法中使用 super() 调用。

自动递增主键¶

如果模型具有 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() 之前，无法知道 ID 的值是多少，因为该值是由您的数据库计算的，而不是由 Django 计算的。

为方便起见，每个模型默认都有一个名为 id 的 AutoField，除非您在模型中的字段上显式指定了 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 抽象了使用 INSERT 或 UPDATE SQL 语句的需求。具体来说，当您调用 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 表达式 来执行这种相对更新。使用 F 表达式，前面的示例表示为

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

有关更多详细信息，请参阅关于 F 表达式 及其 在更新查询中使用 的文档。

指定要保存的字段¶

如果将字段名称列表传递给关键字参数 update_fields，则 save() 将仅更新该列表中命名的字段。如果您只想更新对象上的一个或几个字段，这可能是可取的。防止更新数据库中的所有模型字段将带来轻微的性能提升。例如

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__() 方法在实例保存前后会返回不同的值，但 Python 禁止更改实例的 __hash__() 值）。

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 的其他一些部分，如 联合供稿框架 (syndication feed framework)，在定义时也会使用 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 配置如何，行为都是一致的。