创建对象¶

要创建模型的新实例，请像任何其他 Python 类一样实例化它

class Model(**kwargs)[source]¶

关键字参数是您在模型中定义的字段的名称。请注意，实例化模型不会以任何方式触及您的数据库；为此，您需要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)[source]¶

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创建的queryset不同的queryset。它可以让您更好地控制模型的重新加载方式。例如，当您的模型使用软删除时，您可以使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()[source]¶

一个辅助方法，返回一个集合，该集合包含当前为此模型延迟的所有字段的属性名称。

验证对象¶

验证模型涉及四个步骤

1. 验证模型字段 - Model.clean_fields()

2. 整体验证模型 - Model.clean()

3. 验证字段唯一性 - Model.validate_unique()

4. 验证约束 - Model.validate_constraints()

当您调用模型的full_clean()方法时，将执行所有四个步骤。

当您使用ModelForm时，对is_valid()的调用将对表单中包含的所有字段执行这些验证步骤。有关更多信息，请参阅ModelForm 文档。只有在您计划自己处理验证错误，或者您已从ModelForm中排除了需要验证的字段时，才需要调用模型的full_clean()方法。

Model.full_clean(exclude=None, validate_unique=True, validate_constraints=True)[source]¶

此方法按顺序调用Model.clean_fields()、Model.clean()、Model.validate_unique()（如果validate_unique为True）和Model.validate_constraints()（如果validate_constraints为True），并引发一个ValidationError，该错误具有message_dict属性，其中包含所有四个阶段的错误。

可选的exclude参数可用于提供一个set，其中包含可以从验证和清理中排除的字段名称。ModelForm使用此参数来排除表单中不存在的字段，因为任何引发的错误都无法由用户纠正。

请注意，当您调用模型的save()方法时，不会自动调用full_clean()。当您希望为自己的手动创建的模型运行一步模型验证时，需要手动调用它。例如

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)[source]¶

此方法将验证模型上的所有字段。可选的exclude参数允许您提供一个set，其中包含要从验证中排除的字段名称。如果任何字段验证失败，它将引发ValidationError。

full_clean()执行的第二步是调用Model.clean()。此方法应被重写以对您的模型执行自定义验证。

Model.clean()[source]¶

此方法应用于提供自定义模型验证，并根据需要修改模型上的属性。例如，您可以使用它来自动为字段提供值，或执行需要访问多个字段的验证。

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()一样，当您调用模型的save()方法时，不会调用模型的clean()方法。

在上面的示例中，ValidationError异常是用字符串实例化的，因此它将存储在一个特殊的错误字典键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)[source]¶

此方法类似于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()验证。

请注意，如果您向validate_unique()提供exclude参数，则将不会检查涉及您提供的字段之一的任何unique_together约束。

最后，full_clean()将检查模型上的任何其他约束。

Model.validate_constraints(exclude=None)[source]¶

此方法验证在 Meta.constraints 中定义的所有约束。可选的 exclude 参数允许您提供一个 set，其中包含要从验证中排除的字段名称。如果任何约束验证失败，它将引发 ValidationError。

保存对象¶

要将对象保存回数据库，请调用 save()

Model.save(*, force_insert=False, force_update=False, using=DEFAULT_DB_ALIAS, update_fields=None)[source]¶

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)[source]¶

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

异步版本：adelete()

为对象发出 SQL DELETE命令。这只会删除数据库中的对象；Python 实例仍然存在，其字段中仍然包含数据，但主键将设置为None。此方法返回已删除的对象数量以及包含每个对象类型删除数量的字典。

有关更多详细信息（包括如何批量删除对象），请参见删除对象。

如果需要自定义删除行为，可以覆盖delete()方法。有关更多详细信息，请参见覆盖预定义模型方法。

使用多表继承时，有时可能只想删除子模型的数据。指定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)¶

对于每个未设置null=True的DateField和DateTimeField，对象将具有get_next_by_FOO()和get_previous_by_FOO()方法，其中FOO是字段的名称。这将返回关于日期字段的下一个和上一个对象，并在适当的时候引发DoesNotExist异常。

这两种方法都将使用模型的默认管理器执行其查询。如果您需要模拟自定义管理器使用的筛选，或者想要执行一次性自定义筛选，这两种方法也接受可选的关键字参数，这些参数的格式应如Field lookups中所述。

请注意，在日期值相同的情况下，这些方法将使用主键作为决胜符。这保证不会跳过或重复任何记录。这也意味着您不能在未保存的对象上使用这些方法。

其他属性¶