模型实例引用

本文档描述了Model API的细节。 它建立在modeldatabase query指南中的内容上,所以在阅读这些指南之前,您可能需要阅读和理解这些文档。

在整个这个参考文献中,我们将使用database query guide中介绍的example Weblog models

创建对象

要创建一个模型的新实例,只需要像其他任何Python类一样实例化它:

Model(**kwargs)[source]

关键字参数只是您在模型中定义的字段的名称。 请注意,实例化模型不会触及数据库;为此,您需要save()

注意

您可能会试图通过覆盖__init__方法来定制模型。 但是,如果这样做,请注意不要更改调用签名,因为任何更改都可能会阻止保存模型实例。 尝试使用以下方法之一,而不是重写__init__

  1. 在模型类上添加一个classmethod:

    from django.db import models
    
    class Book(models.Model):
        title = models.CharField(max_length=100)
    
        @classmethod
        def create(cls, title):
            book = cls(title=title)
            # do something with the book
            return book
    
    book = Book.create("Pride and Prejudice")
    
  2. 在自定义管理器中添加一个方法(通常是首选):

    class BookManager(models.Manager):
        def create_book(self, title):
            book = self.create(title=title)
            # do something with the book
            return book
    
    class Book(models.Model):
        title = models.CharField(max_length=100)
    
        objects = BookManager()
    
    book = Book.objects.create_book("Pride and Prejudice")
    

自定义模型加载

类方法 模型。from_dbdbfield_namesvalues[source] T6>

从数据库加载时,可以使用from_db()方法自定义模型实例创建。

db参数包含模型加载数据库的数据库别名,field_names包含所有加载字段的名称,values包含为field_names中的每个字段加载值。 field_names的顺序与values的顺序相同。 如果所有模型的字段都存在,那么values保证按照__init__()的顺序期望它们。 也就是说,实例可以由cls(*values)创建。 如果任何字段被延迟,它们将不会出现在field_names中。 在这种情况下,为每个缺少的字段分配一个django.db.models.DEFERRED值。

In addition to creating the new model, the from_db() method must set the adding and db flags in the new instance’s _state attribute.

以下是显示如何记录从数据库加载的字段的初始值的示例:

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, values))
    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()实现来阐明如何完成。 在这种情况下,当然可以在from_db()方法中使用super()调用。

从数据库刷新对象

如果从模型实例中删除一个字段,则再次访问它将重新加载数据库中的值:

>>> obj = MyModel.objects.first()
>>> del obj.field
>>> obj.field  # Loads the field from the database
模型。refresh_from_dbusing = Nonefields = None[source]

如果您需要从数据库重新加载模型的值,可以使用refresh_from_db()方法。 当这个方法被调用没有参数时,完成以下操作:

  1. 模型中的所有未延期字段都会更新为数据库中当前存在的值。
  2. 先前加载的关系值不再有效的相关实例将从重新加载的实例中删除。 For example, if you have a foreign key from the reloaded instance to another model with name Author, then if obj.author_id != obj.author.id, obj.author will be thrown away, and when next accessed it will be reloaded with the value of obj.author_id.

只有模型的字段从数据库重新加载。 其他与数据库相关的值(如注释)不会重新加载。 任何@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)

请注意,当访问延迟字段时,通过此方法加载延迟字段的值。 因此可以定制延迟加载的方式。 下面的例子展示了当重载一个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)
模型。get_deferred_fields()[source]

返回一个包含当前为此模型推迟的所有字段的属性名称的集合的帮助程序方法。

验证对象

验证模型涉及三个步骤:

  1. 验证模型字段 - Model.clean_fields()
  2. 验证整个模型 - Model.clean()
  3. 验证字段唯一性 - Model.validate_unique()

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

当您使用ModelForm时,对is_valid()的调用将对窗体上包含的所有字段执行这些验证步骤。 有关更多信息,请参阅ModelForm documentation 如果您打算自己处理验证错误,或者已经排除ModelForm中需要验证的字段,则只需要调用模型的full_clean()方法。

模型。full_cleanexclude = Nonevalidate_unique = True[source]

This method calls Model.clean_fields(), Model.clean(), and Model.validate_unique() (if validate_unique is True), in that order and raises a ValidationError that has a message_dict attribute containing errors from all three stages.

可选的exclude参数可用于提供可从验证和清除中排除的字段名称列表。 ModelForm uses this argument to exclude fields that aren’t present on your form from being validated since any errors raised could not be corrected by the user.

请注意,当您调用模型的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()执行的是清理每个单独的字段。

模型。clean_fields(exclude=None)[source]

该方法将验证模型上的所有字段。 可选的exclude参数允许您提供要从验证中排除的字段名称列表。 如果任何字段未通过验证,将引发ValidationError

第二步full_clean()执行的是调用Model.clean() 应该重写这个方法来在你的模型上执行自定义验证。

模型。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()

但是,请注意,当您调用模型的save()时,不会调用模型的clean()方法中的Model.full_clean()

在上面的例子中,Model.clean()引发的ValidationError异常是用一个字符串实例化的,所以它将被存储在一个特殊的错误字典键NON_FIELD_ERRORS 这个键用于与整个模型相关的错误,而不是与特定字段相关联的错误:

from django.core.exceptions import ValidationError, NON_FIELD_ERRORS
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'),
})

Finally, full_clean() will check any unique constraints on your model.

如果这些字段没有出现在ModelForm中,如何提出特定于字段的验证错误

您不能在Model.clean()中为未出现在模型表单中的字段(表单可能使用Meta.fields限制其字段或Meta.exclude 这样做会引发一个ValueError,因为验证错误将无法与排除的字段关联。

要解决这个难题,而不是覆盖Model.clean_fields(),因为它接收到从验证中排除的字段列表。 例如:

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.'
                     ),
                })
模型。validate_unique(exclude=None)[source]

此方法与clean_fields()类似,但会验证模型上的所有唯一性约束,而不是单个字段值。 可选的exclude参数允许您提供要从验证中排除的字段名称列表。 如果任何字段未通过验证,将引发ValidationError

请注意,如果您向validate_unique()提供exclude参数,那么涉及您提供的其中一个字段的任何unique_together约束将不会被检查。

保存对象

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

模型。save(force_insert=False, force_update=False, using=DEFAULT_DB_ALIAS, update_fields=None)[source]

如果你想自定义保存行为,你可以覆盖这个save()方法。 有关更多详细信息,请参阅Overriding predefined model methods

模型保存过程也有一些微妙之处;请参阅下面的部分。

自动递增主键

If a model has an AutoField — an auto-incrementing primary key — then that auto-incremented value will be calculated and saved as an attribute on your object the first time you call save():

>>> b2 = Blog(name='Cheddar Talk', tagline='Thoughts on cheese.')
>>> b2.id     # Returns None, because b doesn't have an ID yet.
>>> b2.save()
>>> b2.id     # Returns the ID of your new object.

在调用save()之前,没有办法知道ID的值是什么,因为该值是由数据库计算的,而不是由Django计算。

为方便起见,默认情况下每个模型都有一个名为idAutoField,除非您在模型的字段中明确指定primary_key=True 有关更多详细信息,请参阅AutoField的文档。

pk属性

模型。 PK T0> ¶ T1>

无论您是自己定义主键字段,还是让Django为您提供一个主键字段,每个模型都会有一个名为pk的属性。 它在模型上表现得像一个正常的属性,但实际上是模型的主键字段的一个别名。 您可以像读取任何其他属性一样读取和设置此值,并且会更新模型中的正确字段。

显式指定自动主键值

如果一个模型有一个AutoField,但是您希望在保存时明确定义一个新对象的ID,只需在保存之前明确定义它,而不是依靠自动分配ID:

>>> b3 = Blog(id=3, name='Cheddar Talk', tagline='Thoughts on cheese.')
>>> b3.id     # Returns 3.
>>> b3.save()
>>> b3.id     # Returns 3.

如果您手动分配自动主键值,请确保不要使用已有的主键值! 如果使用数据库中已经存在的显式主键值创建一个新对象,Django会假定您正在更改现有记录,而不是创建一个新记录。

给定上面的'Cheddar Talk'博客示例,此示例将覆盖数据库中的上一条记录:

b4 = Blog(id=3, name='Not Cheddar', tagline='Anything but cheese.')
b4.save()  # Overrides the previous blog with ID=3!

有关这种情况的原因,请参阅下面的Django如何知道UPDATE与INSERT

如果您确信自己不会遇到主键冲突,那么明确指定自动主键值对于批量保存对象非常有用。

如果您使用PostgreSQL,则与主键关联的序列可能需要更新;请参阅Manually-specifying values of auto-incrementing primary keys

当你保存时会发生什么?

保存对象时,Django执行以下步骤:

  1. 发出预存信号。 The pre_save signal is sent, allowing any functions listening for that signal to do something.

  2. 预处理数据。 调用每个字段的pre_save()方法来执行所需的任何自动数据修改。 例如,日期/时间字段覆盖pre_save()以实现auto_now_addauto_now

  3. 准备数据库的数据。 要求每个字段的get_db_prep_save()方法在可写入数据库的数据类型中提供其当前值。

    大多数字段不需要数据准备。 简单的数据类型,比如整数和字符串,作为一个Python对象“准备写入”。 但是,更复杂的数据类型通常需要进行一些修改。

    例如,DateField字段使用Python datetime对象来存储数据。 数据库不存储datetime对象,所以必须将字段值转换为符合ISO的日期字符串以便插入到数据库中。

  4. 将数据插入数据库。 预处理的准备好的数据组成一个SQL语句,用于插入到数据库中。

  5. 发出保存后信号。 发送post_save信号,允许任何监听该信号的功能执行某些操作。

Django如何知道UPDATE与INSERT

您可能已经注意到Django数据库对象使用相同的save()方法来创建和更改对象。 Django抽象使用INSERTUPDATE SQL语句的需要。 Specifically, when you call save(), Django follows this algorithm:

  • 如果对象的主键属性被设置为True(即None或空字符串以外的值),则Django执行UPDATE
  • 如果对象的主键属性是not,或者UPDATE没有更新,Django会执行INSERT

这里的一个问题是,如果不能保证主键值不被使用,那么当保存新对象时,应该小心不要明确指定主键值。 有关此细节的更多信息,请参阅下面的显式指定自动主键值强制INSERT或UPDATE

在Django 1.5和更早的版本中,当主键属性被设置时,Django做了一个SELECT 如果SELECT找到了一行,那么Django做了一个UPDATE,否则就做了一个INSERT 旧的算法在UPDATE情况下导致多一个查询。 在极少数情况下,即使数据库包含对象主键值的行,数据库也不会报告行已更新。 例如PostgreSQL ON UPDATE触发器,它返回NULL 在这种情况下,可以通过将select_on_save选项设置为True来恢复旧算法。

强制INSERT或UPDATE

在极少数情况下,必须能够强制save()方法执行SQL INSERT,而不会退回到执行UPDATE 反之亦然:如果可能,更新,但不插入新行。 在这些情况下,您可以将force_insert=Trueforce_update=True参数传递给save()方法。 显然,传递这两个参数是一个错误:你不能同时插入更新!

您将需要使用这些参数应该是非常罕见的。 Django几乎总是会做正确的事情,并且试图重写这些会导致难以追查的错误。 此功能仅供高级使用。

使用update_fields会强制更新,类似于force_update

根据现有字段更新属性

有时你需要在一个字段上执行一个简单的算术任务,例如递增或递减当前值。 实现这一目标的显而易见的方法是执行如下操作:

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

如果从数据库中检索到的旧的number_sold值是10,那么11的值将被写回数据库。

The process can be made robust, avoiding a race condition, as well as slightly faster by expressing the update relative to the original field value, rather than as an explicit assignment of a new value. 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及其在use in update queries

指定要保存的字段

如果save()在关键字参数update_fields中传递了一个字段名称列表,则只会更新该列表中指定的字段。 如果你想更新对象上的一个或几个字段,这可能是可取的。 防止所有模型字段在数据库中被更新会带来轻微的性能优势。 例如:

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

update_fields参数可以是任何包含字符串的可迭代的。 一个空的update_fields可迭代将跳过保存。 值None将在所有字段上执行更新。

指定update_fields将强制更新。

当保存通过延迟模型加载(only()defer())获取的模型时,只有从数据库加载的字段才会更新。 实际上在这种情况下有一个自动的update_fields 如果您分配或更改任何延期的字段值,该字段将被添加到更新的字段。

删除对象

模型。delete使用= DEFAULT_DB_ALIASkeep_parents = False[source]

为该对象发出一个SQL DELETE 这只会删除数据库中的对象; Python实例仍然存在,并且在其字段中仍然有数据。 这个方法返回被删除的对象的数目和每个对象类型的删除次数的字典。

有关更多详细信息(包括如何批量删除对象),请参阅Deleting objects

如果您想要自定义删除行为,则可以覆盖delete()方法。 有关更多详细信息,请参阅Overriding predefined model methods

有时用multi-table inheritance你可能只想删除一个子模型的数据。 指定keep_parents=True将保留父模型的数据。

酸洗对象

When you pickle a model, its current state is pickled. 当你取消它的时候,它会在被腌制的时候包含模型实例,而不是当前在数据库中的数据。

版本之间不能共享泡菜

模型的腌菜只对用于生成它们的Django版本有效。 如果使用Django版本N生成一个pickle,则不能保证pickle在Django版本N + 1中是可读的。 不应将腌菜作为长期档案战略的一部分。

由于泡菜兼容性错误可能难以诊断,如默默地损坏的对象,当试图在一个Django版本比在它被酸洗的一个不同于unpickle模型的RuntimeWarning

其他模型实例方法

一些对象方法有特殊的用途。

__str__()

模型。__str__()[source]

The __str__() method is called whenever you call str() on an object. 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 '%s %s' % (self.first_name, self.last_name)

__eq__()

模型。__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)
# Primay 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__()

模型。__hash__()[source]

__hash__()方法基于实例的主键值。 It is effectively hash(obj.pk). 如果实例没有主键值,那么会引发一个TypeError(否则在保存实例之前和之后,__hash__()方法将返回不同的值,但在Python中禁止更改实例的__hash__()值。

get_absolute_url()

模型。 get_absolute_url T0>()¶ T1>

定义一个get_absolute_url()方法来告诉Django如何计算一个对象的规范URL。 对于调用者来说,这个方法似乎应该返回一个可以用来通过HTTP引用对象的字符串。

例如:

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

虽然这个代码是正确和简单的,但它可能不是写这种方法的最便携的方式。 The reverse() function is usually the best approach.

例如:

def get_absolute_url(self):
    from django.urls import reverse
    return reverse('people.views.details', args=[str(self.id)])

Django使用的一个地方是get_absolute_url()在管理应用程序中。 如果一个对象定义了这个方法,那么对象编辑页面将会有一个“View on site”链接,它会直接跳转到对象的公共视图,如get_absolute_url()所示。

同样,Django的一些其他位(如syndication feed framework)在定义时使用get_absolute_url() 如果模型的实例每个都有一个唯一的URL,那么应该定义get_absolute_url()

警告

您应该避免从未经验证的用户输入构建URL,以减少链接或重定向中毒的可能性:

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

如果self.name'/example.com',则返回'//example.com/',这反过来是有效的模式相对URL,但不是预期的'/%2Fexample.com/'

在模板中使用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()中指定一次,让所有其他代码调用一个地方。

注意

您从get_absolute_url() 返回的字符串必须只包含ASCII字符(由URI规范 RFC 2396 ),并根据需要进行网址编码。

调用get_absolute_url()的代码和模板应该能够直接使用结果,而无需进一步处理。 如果您使用的字符串包含ASCII范围以外的字符,您可能希望使用django.utils.encoding.iri_to_uri()函数来解决此问题。

额外的实例方法

save()delete()之外,模型对象可能具有以下某些方法:

模型。 get_FOO_display T0>()¶ T1>

对于设置了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'
模型。 get_next_by_FOO T0>( ** kwargs T1>)¶ T2>
模型。 get_previous_by_FOO T0>( ** kwargs T1>)¶ T2>

For every DateField and DateTimeField that does not have null=True, the object will have get_next_by_FOO() and get_previous_by_FOO() methods, where FOO is the name of the field. This returns the next and previous object with respect to the date field, raising a DoesNotExist exception when appropriate.

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

请注意,在相同的日期值的情况下,这些方法将使用主键作为决胜者。 这保证没有记录被跳过或重复。 这也意味着你不能在未保存的对象上使用这些方法。

其他属性

DoesNotExist

例外 模型。 DoesNotExist T0> ¶ T1>

ORM在几个地方引发了这个异常,例如,当给定查询参数找不到对象时,通过QuerySet.get()

Django提供了一个DoesNotExist异常作为每个模型类的一个属性来标识无法找到的对象的类,并允许你用try/except 例外是django.core.exceptions.ObjectDoesNotExist的子类。