本文档描述了Model API的细节。 它建立在model和数据库查询指南中提供的材料上，因此您在阅读这些文档之前可能需要阅读和理解这些文档。
在整篇文档中，我们将使用数据库查询指南中介绍的示例Weblog模型。
要创建模型的新实例，只需像其他任何Python类一样实例化它：
关键字参数只是您在模型上定义的字段的名称。 请注意，实例化模型不会触及数据库；为此，您需要save()。
Note
您可能会试图通过重写__ init __方法来定制模型。 但是，如果您这样做，请注意不要更改调用签名，因为任何更改都可能会阻止保存模型实例。
不要重写__ init __，请尝试使用以下方法之一：
在模型类上添加一个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")
在自定义管理器中添加一个方法（通常是首选）：
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_db()方法来自定义模型实例创建。
db参数包含模型加载数据库的数据库别名，field_names包含所有加载字段的名称，values包含每个field_names字段中的加载值。 field_names的顺序与值的顺序相同。 If all of the model’s
fields are present, then values are guaranteed to be in the order
__init__() expects them. 也就是说，实例可以由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, 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_db()方法。 当这个方法在没有参数的情况下被调用时，会进行以下操作：
Author的模型，那么如果obj.author_id ！= obj.author.id，obj.author将被丢弃，当下次访问时，它将被重载为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)
Note that when deferred fields are accessed, the loading of the deferred field’s value happens through this method. Thus it is possible to customize the way deferred loading happens. The example below shows how one can reload all of the instance’s fields when a deferred field is reloaded:
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)
A helper method that returns a set containing the attribute names of all those fields that are currently deferred for this model.
There are three steps involved in validating a model:
Model.clean_fields()Model.clean()Model.validate_unique()All three steps are performed when you call a model’s
full_clean() method.
When you use a ModelForm, the call to
is_valid() will perform these validation steps for
all the fields that are included on the form. See the ModelForm
documentation for more information. You should only
need to call a model’s full_clean() method if you plan to handle
validation errors yourself, or if you have excluded fields from the
ModelForm that require validation.
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.
The optional exclude argument can be used to provide a list of field names
that can be excluded from validation and cleaning.
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.
Note that full_clean() will not be called automatically when you call
your model’s save() method. You’ll need to call it manually
when you want to run one-step model validation for your own manually created
models. For example:
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
The first step full_clean() performs is to clean each individual field.
This method will validate all fields on your model. The optional exclude
argument lets you provide a list of field names to exclude from validation. It
will raise a ValidationError if any fields fail
validation.
The second step full_clean() performs is to call Model.clean().
This method should be overridden to perform custom validation on your model.
This method should be used to provide custom model validation, and to modify attributes on your model if desired. For instance, you could use it to automatically provide a value for a field, or to do validation that requires access to more than a single field:
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()方法那样。
In the above example, the ValidationError
exception raised by Model.clean() was instantiated with a string, so it
will be stored in a special error dictionary key,
NON_FIELD_ERRORS. This key is used for errors
that are tied to the entire model instead of to a specific field:
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]
To assign exceptions to a specific field, instantiate the
ValidationError with a dictionary, where the
keys are the field names. We could update the previous example to assign the
error to the pub_date field:
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.')})
...
If you detect errors in multiple fields during Model.clean(), you can also
pass a dictionary mapping field names to errors:
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.
How to raise field-specific validation errors if those fields don’t appear in a ModelForm
You can’t raise validation errors in Model.clean() for fields that
don’t appear in a model form (a form may limit its fields using
Meta.fields or Meta.exclude). Doing so will raise a ValueError
because the validation error won’t be able to be associated with the
excluded field.
To work around this dilemma, instead override Model.clean_fields() as it receives the list of fields
that are excluded from validation. For example:
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.'
),
})
This method is similar to clean_fields(), but validates all
uniqueness constraints on your model instead of individual field values. The
optional exclude argument allows you to provide a list of field names to
exclude from validation. It will raise a
ValidationError if any fields fail validation.
Note that if you provide an exclude argument to validate_unique(), any
unique_together constraint involving one of
the fields you provided will not be checked.
To save an object back to the database, call save():
Model.save(force_insert=False, force_update=False, using=DEFAULT_DB_ALIAS, update_fields=None)[source]¶If you want customized saving behavior, you can override this save()
method. See Overriding predefined model methods for more details.
The model save process also has some subtleties; see the sections below.
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.
There’s no way to tell what the value of an ID will be before you call
save(), because that value is calculated by your database, not by Django.
For convenience, each model has an AutoField named
id by default unless you explicitly specify primary_key=True on a field
in your model. See the documentation for AutoField
for more details.
pk property¶Model.pk¶Regardless of whether you define a primary key field yourself, or let Django
supply one for you, each model will have a property called pk. It behaves
like a normal attribute on the model, but is actually an alias for whichever
attribute is the primary key field for the model. You can read and set this
value, just as you would for any other attribute, and it will update the
correct field in the model.
If a model has an AutoField but you want to define a
new object’s ID explicitly when saving, just define it explicitly before
saving, rather than relying on the auto-assignment of the ID:
>>> b3 = Blog(id=3, name='Cheddar Talk', tagline='Thoughts on cheese.')
>>> b3.id # Returns 3.
>>> b3.save()
>>> b3.id # Returns 3.
If you assign auto-primary-key values manually, make sure not to use an already-existing primary-key value! If you create a new object with an explicit primary-key value that already exists in the database, Django will assume you’re changing the existing record rather than creating a new one.
Given the above 'Cheddar Talk' blog example, this example would override the
previous record in the database:
b4 = Blog(id=3, name='Not Cheddar', tagline='Anything but cheese.')
b4.save() # Overrides the previous blog with ID=3!
See How Django knows to UPDATE vs. INSERT, below, for the reason this happens.
Explicitly specifying auto-primary-key values is mostly useful for bulk-saving objects, when you’re confident you won’t have primary-key collision.
If you’re using PostgreSQL, the sequence associated with the primary key might need to be updated; see Manually-specifying values of auto-incrementing primary keys.
When you save an object, Django performs the following steps:
Emit a pre-save signal. The pre_save
signal is sent, allowing any functions listening for that signal to do
something.
Preprocess the data. Each field’s
pre_save() method is called to perform any
automated data modification that’s needed. For example, the date/time fields
override pre_save() to implement
auto_now_add and
auto_now.
Prepare the data for the database. Each field’s
get_db_prep_save() method is asked to provide
its current value in a data type that can be written to the database.
Most fields don’t require data preparation. Simple data types, such as integers and strings, are ‘ready to write’ as a Python object. However, more complex data types often require some modification.
For example, DateField fields use a Python
datetime object to store data. Databases don’t store datetime
objects, so the field value must be converted into an ISO-compliant date
string for insertion into the database.
Insert the data into the database. The preprocessed, prepared data is composed into an SQL statement for insertion into the database.
Emit a post-save signal. The post_save
signal is sent, allowing any functions listening for that signal to do
something.
You may have noticed Django database objects use the same save() method
for creating and changing objects. Django abstracts the need to use INSERT
or UPDATE SQL statements. Specifically, when you call save(), Django
follows this algorithm:
True (i.e., a value other than None or the empty string), Django
executes an UPDATE.UPDATE
didn’t update anything, Django executes an INSERT.The one gotcha here is that you should be careful not to specify a primary-key value explicitly when saving new objects, if you cannot guarantee the primary-key value is unused. For more on this nuance, see Explicitly specifying auto-primary-key values above and Forcing an INSERT or UPDATE below.
In Django 1.5 and earlier, Django did a SELECT when the primary key
attribute was set. If the SELECT found a row, then Django did an UPDATE,
otherwise it did an INSERT. The old algorithm results in one more query in
the UPDATE case. There are some rare cases where the database doesn’t
report that a row was updated even if the database contains a row for the
object’s primary key value. An example is the PostgreSQL ON UPDATE trigger
which returns NULL. In such cases it is possible to revert to the old
algorithm by setting the select_on_save
option to True.
In some rare circumstances, it’s necessary to be able to force the
save() method to perform an SQL INSERT and not fall back to
doing an UPDATE. Or vice-versa: update, if possible, but not insert a new
row. In these cases you can pass the force_insert=True or
force_update=True parameters to the save() method.
Obviously, passing both parameters is an error: you cannot both insert and
update at the same time!
It should be very rare that you’ll need to use these parameters. Django will almost always do the right thing and trying to override that will lead to errors that are difficult to track down. This feature is for advanced use only.
Using update_fields will force an update similarly to force_update.
Sometimes you’ll need to perform a simple arithmetic task on a field, such as incrementing or decrementing the current value. The obvious way to achieve this is to do something like:
>>> product = Product.objects.get(name='Venezuelan Beaver Cheese')
>>> product.number_sold += 1
>>> product.save()
If the old number_sold value retrieved from the database was 10, then
the value of 11 will be written back to the database.
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 provides F expressions for performing this kind of relative update. Using
F expressions, the previous example is expressed
as:
>>> from django.db.models import F
>>> product = Product.objects.get(name='Venezuelan Beaver Cheese')
>>> product.number_sold = F('number_sold') + 1
>>> product.save()
For more details, see the documentation on F expressions and their use in update queries.
If save() is passed a list of field names in keyword argument
update_fields, only the fields named in that list will be updated.
This may be desirable if you want to update just one or a few fields on
an object. There will be a slight performance benefit from preventing
all of the model fields from being updated in the database. For example:
product.name = 'Name changed again'
product.save(update_fields=['name'])
The update_fields argument can be any iterable containing strings. An
empty update_fields iterable will skip the save. A value of None will
perform an update on all fields.
Specifying update_fields will force an update.
When saving a model fetched through deferred model loading
(only() or
defer()) only the fields loaded
from the DB will get updated. In effect there is an automatic
update_fields in this case. If you assign or change any deferred field
value, the field will be added to the updated fields.
Issues an SQL DELETE for the object. This only deletes the object in the
database; the Python instance will still exist and will still have data in
its fields. This method returns the number of objects deleted and a dictionary
with the number of deletions per object type.
For more details, including how to delete objects in bulk, see Deleting objects.
If you want customized deletion behavior, you can override the delete()
method. See Overriding predefined model methods for more details.
Sometimes with multi-table inheritance you may
want to delete only a child model’s data. Specifying keep_parents=True will
keep the parent model’s data.
When you pickle a model, its current state is pickled. When you unpickle
it, it’ll contain the model instance at the moment it was pickled, rather than
the data that’s currently in the database.
A few object methods have special purposes.
__str__()¶无论何时调用对象上的str()，都会调用__str__()方法。
Django在很多地方使用str（obj）。 最值得注意的是，在Django管理站点中显示对象，并在显示对象时将其作为插入到模板中的值。 因此，您应该始终从__str__()方法返回一个漂亮的，人类可读的模型表示。
For example:
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__()¶The equality method is defined such that instances with the same primary
key value and the same concrete class are considered equal, except that
instances with a primary key value of None aren’t equal to anything except
themselves. For proxy models, concrete class is defined as the model’s first
non-proxy parent; for all other models it’s simply the model’s class.
For example:
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__()方法基于实例的主键值。 它实际上是hash(obj.pk)。 如果实例没有主键值，那么将引发一个TypeError（否则__hash__()方法将在实例保存之前和之后返回不同的值，但在Python中禁止更改实例的__hash__()值。
get_absolute_url()¶Model.get_absolute_url()¶定义一个get_absolute_url()方法来告诉Django如何计算一个对象的规范URL。 对于调用者来说，这个方法似乎应该返回一个可以用来通过HTTP引用对象的字符串。
For example:
def get_absolute_url(self):
return "/people/%i/" % self.id
虽然这段代码是正确和简单的，但它可能不是编写这种方法的最便捷的方式。 reverse()函数通常是最好的方法。
For example:
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()。
Warning
您应该避免从未经验证的用户输入中构建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>
This template code is much better:
<a href="{{ object.get_absolute_url }}">{{ object.name }}</a>
这里的逻辑是，如果您更改对象的URL结构，即使对于简单的事情（例如更正拼写错误），也不希望跟踪每个可能创建URL的位置。 在get_absolute_url()中指定一次，所有其他代码调用这一个地方就行。
Note
您从get_absolute_url() 返回的字符串必须仅包含ASCII字符（由URI规范 RFC 2396 ），并在必要时进行网址编码。
调用get_absolute_url()的代码和模板应该能够直接使用结果，而无需进一步处理。 如果您使用的字符串包含ASCII范围以外的字符，您可能希望使用django.utils.encoding.iri_to_uri()函数来解决此问题。
除save()，delete()之外，模型对象可能具有以下某些方法：
Model.get_FOO_display()¶对于设置了choice的每个字段，对象都有一个get_FOO_display()方法，其中FOO是该字段的名称。 该方法返回该字段的“人类可读”值。
For example:
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)¶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.
Both of these methods will perform their queries using the default manager for the model. If you need to emulate filtering used by a custom manager, or want to perform one-off custom filtering, both methods also accept optional keyword arguments, which should be in the format described in Field lookups.
Note that in the case of identical date values, these methods will use the primary key as a tie-breaker. This guarantees that no records are skipped or duplicated. That also means you cannot use those methods on unsaved objects.
DoesNotExist¶Model.DoesNotExist¶This exception is raised by the ORM in a couple places, for example by
QuerySet.get() when an object
is not found for the given query parameters.
Django provides a DoesNotExist exception as an attribute of each model
class to identify the class of object that could not be found and to allow
you to catch a particular model class with try/except. The exception is
a subclass of django.core.exceptions.ObjectDoesNotExist.
Jan 17, 2018