The Django Book

What Happens When You Save?

当您�存的时候�生了什么?

When you save an object, Django performs the following steps:

当您�存一个对象的时候, Django执行下�的步骤:

Emit a pre_save signal. This provides a notification that an object is about to be saved. You can register a listener that will be invoked whenever this signal is emitted. These signals are still in development and werent documented when this book went to press; check the online documentation for the latest information.

�出一个预存信�。 它�出一个将�存储一个对象的通知。你�以注册一个监�程�，在信��出的时候就会被调用。到本书出版时，这些信��在开�中并且没有文档化，请查看在线文档�获得最新的消�。

Preprocess the data. Each field on the object is asked to perform any automated data modification that the field may need to perform.

预处�数�. 对于对象的�个字段，将根�需�进行自动的数�修改。

Most fields do no preprocessing the field data is kept as is. Preprocessing is only used on fields that have special behavior, like file fields.

大部分字段并�预处�，它们会��它们原�的样�。预处�仅仅用在那些有特殊性质的字段，比如文件字段。

Prepare the data for the database. Each field is asked to provide its current value in a data type that can be written to the database.

为数�库准备数�。 �一个字段先�把当�值转化�数�库中�以�存的数�的类型。

Most fields require no 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, DateFields use a Python datetime object to store data. Databases dont store datetime objects, so the field value must be converted into an ISO-compliant date string for insertion into the database.

大多数字段的数��需�预先准备。简�的数�类型，比如整型和字符串等python对象�以直接写进数�库。然而，更��的数�类型需��一些修改。比如， DateFields 使用python的 datetime 对象�存储数�。数�库并�能存储 datetime 对象，所以该字段�存入数�库先�把值转化为符�ISO标准的日期字符串。

Insert the data into the database. The preprocessed, prepared data is then composed into an SQL statement for insertion into the database.

�数�库中�入数�。 �过预处�准备好的数�然�会组��一�SQL语���入数�库。

Emit a post_save signal. As with the pre_save signal, this is used to provide notification that an object has been successfully saved. Again, these signals are not yet documented.

�出存毕信�。 与预存信�类似，存毕信�在对象�功�存之��出。�样，这些信�也还没有文档化。

Autoincrementing Primary Keys

自增主键

For convenience, each model is given an autoincrementing primary key field named id unless you explicitly specify primary_key=True on a field (see the section titled AutoField in Appendix B).

为了方便，�个数�库模型都会添加一个自增主键字段，� id 。除�你在�个字段属性中显�的指定 primary_key=True （��附录B中题为AutoField的章节）。

If your model has an AutoField , that autoincremented value will be calculated and saved as an attribute on your object the first time you call save() :

如果你的数�库模型中包括 AutoField ，这个自增�的值将会在你第一次调用 save() 时作为对象的一个属性计算得出并�存起�。

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

>>> b2.save()
>>> b2.id     # Returns the ID of your new object.
14

Theres 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.

在调用 save() 方法之�没有办法知�ID的值，因为这个值是数�库计算出�的，�是Django。

If a model has an AutoField but you want to define a new objects ID explicitly when saving, just define it explicitly before saving, rather than relying on the autoassignment of the ID:

如果你想在一个新数�存储时，定义其 AutoField 字段值，而��赖于数�库自动分�，明确赋值��。

>>> b3 = Blog(id=3, name='Cheddar Talk', tagline='Thoughts on cheese.')
>>> b3.id
3
>>> b3.save()
>>> b3.id
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 youre changing the existing record rather than creating a new one.

如果你手动指定自增主键的值，�确�这个主键在数�库中�存在�如果你显�地指定主键�创建新对象，而这个主键在数�库中已�存在的�，Django会认为你�更改已�存在的那�记录，而�是创建一个新的。

Given the preceding 'Cheddar Talk' blog example, this example would override the previous record in the database:

以��的 'Cheddar Talk' blog为例，下�的例�会覆盖数�库中已�存在的记录：

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

Explicitly specifying auto-primary-key values is mostly useful for bulk-saving objects, when youre confident you wont have primary key collision.

如果你确信�会产生主键冲�的�，当需��存大�对象的时候，明确指定自增主键的值是�常有用的。

Chaining Filters

级�过滤器

The result of refining a QuerySet is itself a QuerySet , so its possible to chain refinements together, for example:

细化过的 QuerySet 本身就是一个 QuerySet ，所以�以进一步细化，比如：

>>> qs = Entry.objects.filter(headline__startswith='What')
>>> qs = qs..exclude(pub_date__gte=datetime.datetime.now())
>>> qs = qs.filter(pub_date__gte=datetime.datetime(2005, 1, 1))

This takes the initial QuerySet of all entries in the database, adds a filter, then an exclusion, and then another filter. The final result is a QuerySet containing all entries with a headline that starts with What that were published between January 1, 2005, and the current day.

这样，我们把最�过的数�库中所有内容的一个 QuerySet �过添加一个过滤器�一个��过滤器和�外一个过滤器，得到一个最终的 QuerySet ，最终结果中包�了所有标题以“What�开头的2005年至今的出版的�目。

Its important to point out here that QuerySets are lazy the act of creating a QuerySet doesnt involve any database activity. In fact, the three preceding lines dont make any database calls; you can chain filters together all day long and Django wont actually run the query until the QuerySet is evaluated .

这里需�指出的一点是，创建一个 QuerySet 并�会牵涉到任何数�库动作。事实上，上�的三行并�会产生 任何的 数�库调用。就是说你�以连接任�多个过滤器，��你�把这个 QuerySet 用于赋值的�，Django是�会执行查询的。

You can evaluate a QuerySet in any following ways:

你�以用下�的方法�计算 QuerySet 的值：

Iterating : A QuerySet is iterable, and it executes its database query the first time you iterate over it. For example, the following QuerySet isnt evaluated until its iterated over in the for loop:

迭代 ： QuerySet 是�以迭代的，它会在迭代结�的时候执行数�库查询。例如，下�的这个 QuerySet 在for循环迭代完毕之�，是�会被赋值的：

qs = Entry.objects.filter(pub_date__year=2006)
qs = qs.filter(headline__icontains="bill")
for e in qs:
    print e.headline

This prints all headlines from 2006 that contain bill but causes only one database hit.

它会打�2006年所有包�bill的标题，但�会触�一次数�库访问。

Printing it : A QuerySet is evaluated when you call repr() on it. This is for convenience in the Python interactive interpreter, so you can immediately see your results when using the API interactively.

打� ：对 QuerySet 使用 repr() 方法时，它是会被赋值的。这是为了方便Python的交互解释器，这样在交互环境中使用API时就会立刻看到结果。

Slicing : As explained in the upcoming Limiting QuerySets section, a QuerySet can be sliced using Pythons array-slicing syntax. Usually slicing a QuerySet returns another (unevaluated)``QuerySet``, but Django will execute the database query if you use the step parameter of slice syntax.

切片 ： 在接下�的“��查询集�一节中就会解释这一点， QuerySet 是�以用Python的数组切片的语法�切片的。通常切片过的 QuerySet 会返回�外一个（尚未赋值的） QuerySet ，但是如果在切片时使用步长�数的�，Django会执行数�库查询的。

Converting to a list : You can force evaluation of a QuerySet by calling list() on it, for example:

转化�列表 ：对 QuerySet 调用 list() 方法的�，就�以对它强制赋值，比如：

>>> entry_list = list(Entry.objects.all())

Be warned, though, that this could have a large memory overhead, because Django will load each element of the list into memory. In contrast, iterating over a QuerySet will take advantage of your database to load data and instantiate objects only as you need them.

但是，需�警告的是这样�会导致很大的内存负载，因为Django会把列表的�一个元素加载到内存。相比之下，对 QuerySet 进行迭代会利用数�库�加载数�，并且在需�的时候�会把对象实例化。

Filtered QuerySets Are Unique

过滤过的查询集是独一无二的

Each time you refine a QuerySet , you get a brand-new QuerySet that is in no way bound to the previous QuerySet . Each refinement creates a separate and distinct QuerySet that can be stored, used, and reused:

你�次细化一个 QuerySet 都会得到一个崭新的 QuerySet ，��会与之�的 QuerySet 有任何的瓜葛。�次的细化都会创建一个�自的截然��的 QuerySet ，�以用�存储�使用和�用。

q1 = Entry.objects.filter(headline__startswith="What")
q2 = q1.exclude(pub_date__gte=datetime.now())
q3 = q1.filter(pub_date__gte=datetime.now())

These three QuerySets are separate. The first is a base QuerySet containing all entries that contain a headline starting with What. The second is a subset of the first, with an additional criterion that excludes records whose pub_date is greater than now. The third is a subset of the first, with an additional criterion that selects only the records whose pub_date is greater than now. The initial QuerySet (q1 ) is unaffected by the refinement process.

这三个 QuerySet 是无关的。第一个基础查询集包�了所有标题以What开始的�目。第二个查询集是第一个的�集，�是过滤掉了 pub_date 比当�时间大的记录。第三个查询集也是第一个的�集，��留 pub_date 比当�时间大的记录。�始的 QuerySet （ q1 ）是��细化过程的影�。

Limiting QuerySets

��查询集

Use Pythons array-slicing syntax to limit your QuerySet to a certain number of results. This is the equivalent of SQLs LIMIT and OFFSET clauses.

�以用Python的数�切片的语法��定 QuerySet 的结果数�，这和SQL中的 LIMIT 和 OFFSET 语�是一样的。

For example, this returns the first five entries (LIMIT 5 ):

比如，这�返回�五个�目（ LIMIT 5 ）：

>>> Entry.objects.all()[:5]

This returns the sixth through tenth entries (OFFSET 5 LIMIT 5 ):

这�返回第六到第�个�目（ OFFSET 5 LIMIT 5 ）：

>>> Entry.objects.all()[5:10]

Generally, slicing a QuerySet returns a new QuerySet it doesnt evaluate the query. An exception is if you use the step parameter of Python slice syntax. For example, this would actually execute the query in order to return a list of every second object of the first ten:

一般地，对 QuerySet 进行切片会返回一个新的 QuerySet ，但并�执行查询。如果你在Python切片语法中使用步长�数的�，就会出现特例。例如，�返回��个对象中的��数对象的列表时，实际上会执行查询：

>>> Entry.objects.all()[:10:2]

To retrieve a single object rather than a list (e.g., SELECT foo FROM bar LIMIT 1 ), use a simple index instead of a slice. For example, this returns the first Entry in the database, after ordering entries alphabetically by headline:

�得到 �个 对象而�是一个列表时（例如 SELECT foo FROM bar LIMIT 1 ），�以�用切片而是使用下标。例如，这样就会返回数�库中对标题进行字�排��的第一个 Entry ：

>>> Entry.objects.order_by('headline')[0]

This is roughly equivalent to the following:

刚�这�和下�的大致相当：

>>> Entry.objects.order_by('headline')[0:1].get()

Note, however, that the first of these will raise IndexError while the second will raise DoesNotExist if no objects match the given criteria.

但是�记�，如果没有符��件的记录的�，第一�用法会导致 IndexError ，而第二�用法会导致 DoesNotExist 。

Query Methods That Return New QuerySets

返回新的 QuerySets 的 查询方法

Django provides a range of QuerySet refinement methods that modify either the types of results returned by the QuerySet or the way its SQL query is executed. These methods are described in the sections that follow. Some of the methods take field lookup arguments, which are discussed in detail a bit later on.

Django�供了一系列的 QuerySet 细化方法，既�以修改 QuerySet 返回的结果的类型，��以修改对应的SQL查询的执行方法。这就是这一节我们�讨论的内容。其中有一些细化方法会接收字段查询�数，我们��会详细讨论。

>> Entry.objects.filter(pub_date__year=2005).order_by('-pub_date', 'headline')

>>> Entry.objects.order_by('?')

# This list contains a Blog object.
>>> Blog.objects.filter(name__startswith='Beatles')
[Beatles Blog]

# This list contains a dictionary.
>>> Blog.objects.filter(name__startswith='Beatles').values()
[{'id': 1, 'name': 'Beatles Blog', 'tagline': 'All the latest Beatles news.'}]

>>> Blog.objects.values()
[{'id': 1, 'name': 'Beatles Blog', 'tagline': 'All the latest Beatles news.'}],
>>> Blog.objects.values('id', 'name')
[{'id': 1, 'name': 'Beatles Blog'}]

>>> Entry.objects.dates('pub_date', 'year')
[datetime.datetime(2005, 1, 1)]

>>> Entry.objects.dates('pub_date', 'month')
[datetime.datetime(2005, 2, 1), datetime.datetime(2005, 3, 1)]

>>> Entry.objects.dates('pub_date', 'day')
[datetime.datetime(2005, 2, 20), datetime.datetime(2005, 3, 20)]

>>> Entry.objects.dates('pub_date', 'day', order='DESC')
[datetime.datetime(2005, 3, 20), datetime.datetime(2005, 2, 20)]

>>> Entry.objects.filter(headline__contains='Lennon').dates('pub_date', 'day')
[datetime.datetime(2005, 3, 20)]

# Hits the database.
>>> e = Entry.objects.get(id=5)

# Hits the database again to get the related Blog object.
>>> b = e.blog

# Hits the database.
>>> e = Entry.objects.select_related().get(id=5)

# Doesn't hit the database, because e.blog has been prepopulated
# in the previous query.
>>> b = e.blog

class City(models.Model):
    # ...

class Person(models.Model):
    # ...
    hometown = models.ForeignKey(City)

class Book(models.Model):
    # ...
    author = models.ForeignKey(Person)

>>> b = Book.objects.select_related().get(id=4)
>>> p = b.author         # Doesn't hit the database.
>>> c = p.hometown       # Doesn't hit the database.

>>> b = Book.objects.get(id=4) # No select_related() in this example.
>>> p = b.author         # Hits the database.
>>> c = p.hometown       # Hits the database.

>>> Entry.objects.extra(select={'is_recent': "pub_date > '2006-01-01'"})

>>> subq = 'SELECT COUNT(*) FROM blog_entry WHERE blog_entry.blog_id = blog_blog.id'
>>> Blog.objects.extra(select={'entry_count': subq})

>>> Entry.objects.extra(where=['id IN (3, 4, 5, 20)'])

>>> Entry.objects.extra(where=['headline=%s'], params=['Lennon'])

Entry.objects.extra(where=["headline='%s'" % name])

Entry.objects.extra(where=['headline=%s'], params=[name])

QuerySet Methods That Do Not Return QuerySets

The following QuerySet methods evaluate the QuerySet and return something otherthan a QuerySet a single object, value, and so forth.

>>> Entry.objects.get(id='foo') # raises Entry.DoesNotExist

>>> from django.core.exceptions import ObjectDoesNotExist
>>> try:
...     e = Entry.objects.get(id=3)
...     b = Blog.objects.get(id=1)
... except ObjectDoesNotExist:
...     print "Either the entry or blog doesn't exist."

>>> p = Person(first_name="Bruce", last_name="Springsteen")
>>> p.save()

>>> p = Person.objects.create(first_name="Bruce", last_name="Springsteen")

try:
    obj = Person.objects.get(first_name='John', last_name='Lennon')
except Person.DoesNotExist:
    obj = Person(first_name='John', last_name='Lennon', birthday=date(1940, 10, 9))
    obj.save()

obj, created = Person.objects.get_or_create(
    first_name = 'John',
    last_name  = 'Lennon',
    defaults   = {'birthday': date(1940, 10, 9)}
)

defaults = kwargs.pop('defaults', {})
params = dict([(k, v) for k, v in kwargs.items() if '__' not in k])
params.update(defaults)
obj = self.model(**params)
obj.save()

Foo.objects.get_or_create(
    defaults__exact = 'bar',
    defaults={'defaults': 'baz'}
)

# Returns the total number of entries in the database.
>>> Entry.objects.count()
4

# Returns the number of entries whose headline contains 'Lennon'
>>> Entry.objects.filter(headline__contains='Lennon').count()
1

>>> Blog.objects.in_bulk([1])
{1: Beatles Blog}
>>> Blog.objects.in_bulk([1, 2])
{1: Beatles Blog, 2: Cheddar Talk}
>>> Blog.objects.in_bulk([])
{}

>>> Entry.objects.latest('pub_date')

exact

Performs an exact match:

>>> Entry.objects.get(headline__exact="Man bites dog")

This matches any object with the exact headline Man bites dog.

If you dont provide a lookup type that is, if your keyword argument doesnt contain a double underscore the lookup type is assumed to be exact .

For example, the following two statements are equivalent:

例如，下�两个语�是等效的：

>>> Blog.objects.get(id__exact=14) # Explicit form
>>> Blog.objects.get(id=14) # __exact is implied

This is for convenience, because exact lookups are the common case.

iexact

Performs a case-insensitive exact match:

字符串比较（大�写无关）

>>> Blog.objects.get(name__iexact='beatles blog')

This will match 'Beatles Blog' , 'beatles blog' , 'BeAtLes BLoG' , and so forth.

contains

Performs a case-sensitive containment test:

执行严格区分大�写的内容包�检测：

Entry.objects.get(headline__contains='Lennon')

This will match the headline 'Today Lennon honored' but not 'today lennon honored' .

这将会匹é…�标题为``’Today Lennon honored’`` 的，而ä¸�匹é…� ``‘today lennon honored’``。

SQLite doesnt support case-sensitive LIKE statements; when using SQLite,``contains`` acts like icontains .

SQLite�支�严格区分大�写的 LIKE 语�，所以在使用SQLite时``contains``的作用和``icontains``一样。

Escaping Percent Signs and Underscores in LIKE Statements

除了LIKE语�中的百分�和下划线

The field lookups that equate to LIKE SQL statements (iexact , contains , icontains , startswith , istartswith , endswith , and iendswith ) will automatically escape the two special characters used in LIKE statements the percent sign and the underscore. (In a LIKE statement, the percent sign signifies a multiple-character wildcard and the underscore signifies a single-character wildcard.)

使用相当于``LIKE``的SQL查找语�(iexact , contains , icontains, startswith, istartswith, endswith, 和``iendswith``)时，会自动的排除``LIKE``语�中使用的两个特殊符�：百分��下划线。（在一�``LIKE``语�中，百分�是多个字符的通�符，下划线是�个字符的通�符）

This means things should work intuitively, so the abstraction doesnt leak. For example, to retrieve all the entries that contain a percent sign, just use the percent sign as any other character:

这�味�使用的直观性，所以�会产生���的。例如，查找所有�有一个百分�的项，�需�想用其他字符一样用一个百分�：

Entry.objects.filter(headline__contains='%')

Django takes care of the quoting for you. The resulting SQL will look something like this:

Django 为你处�了这一引用。产生的SQL如下：

SELECT ... WHERE headline LIKE '%\%%';

The same goes for underscores. Both percentage signs and underscores are handled for you transparently.

icontains

Performs a case-insensitive containment test:

执行一个忽略大�写的内容包�检测：

>>> Entry.objects.get(headline__icontains='Lennon')

Unlike contains , icontains will match 'today lennon honored' .

与``contains``��, icontains 会 匹� 'today lennon honored' 。

gt, gte, lt, and lte

These represent greater than, greater than or equal to, less than, and less than or equal to:

这些�大于，大于或等于，�于，�于或等于:

>>> Entry.objects.filter(id__gt=4)
>>> Entry.objects.filter(id__lt=15)
>>> Entry.objects.filter(id__gte=0)

These queries return any object with an ID greater than 4, an ID less than 15, and an ID greater than or equal to 1, respectively.

这些查询分别返回 ID 大于 4，ID �于 15，以� ID 大于等于 0 的对象。

Youll usually use these on numeric fields. Be careful with character fields since character order isnt always what youd expect (i.e., the string 4 sorts after the string 10).

in

Filters where a value is on a given list:

筛选出包�在给定列表中的数�：

Entry.objects.filter(id__in=[1, 3, 4])

This returns all objects with the ID 1, 3, or 4.

这会返回所有ID为1，3，或4的�目。

startswith

Performs a case-sensitive starts-with:

区分大�写的开头匹�：

>>> Entry.objects.filter(headline__startswith='Will')

This will return the headlines Will he run? and Willbur named judge, but not Who is Will? or will found in crypt.

这将返回标题Will he run?和Willbur named judge，但是�会返回Who is Will? 和will found in crypt.

istartswith

Performs a case-insensitive starts-with:

>>> Entry.objects.filter(headline__istartswith='will')

This will return the headlines Will he run?, Willbur named judge, and will found in crypt, but not Who is Will?

endswith and iendswith

Perform case-sensitive and case-insensitive ends-with:

区分大�写和忽略大�写的末尾匹�。

>>> Entry.objects.filter(headline__endswith='cats')
>>> Entry.objects.filter(headline__iendswith='cats')

range

Performs an inclusive range check:

>>> start_date = datetime.date(2005, 1, 1)
>>> end_date = datetime.date(2005, 3, 31)
>>> Entry.objects.filter(pub_date__range=(start_date, end_date))

You can use range anywhere you can use BETWEEN in SQL for dates, numbers, and even characters.

year, month, and day

For date/datetime fields, perform exact year, month, or day matches:

对date/datetime类型严格匹�年�月或日：

# Year lookup
>>>Entry.objects.filter(pub_date__year=2005)

# Month lookup -- takes integers
>>> Entry.objects.filter(pub_date__month=12)

# Day lookup
>>> Entry.objects.filter(pub_date__day=3)

# Combination: return all entries on Christmas of any year
>>> Entry.objects.filter(pub_date__month=12, pub_date_day=25)

isnull

Takes either True or False , which correspond to SQL queries of IS NULL and IS NOT NULL , respectively:

使用``True``或``False``，则分别相当于SQL语�中的``IS NULL``和``IS NOT NULL``:

>>> Entry.objects.filter(pub_date__isnull=True)

__isnull=True vs. __exact=None

There is an important difference between __isnull=True and __exact=None . __exact=None will always return an empty result set, because SQL requires that no value is equal to NULL . __isnull determines if the field is currently holding the value of NULL without performing a comparison.

__isnull=True``和``__exact=None``有一个很主�的区别。因为SQL规定无值就等于``NULL ，所以``__exact=None``会 总是 返回一个空的结果。``__isnull``则�决于该阈是�当�有值 ``NULL``而�进行比较。

search

A Boolean full-text search that takes advantage of full-text indexing. This is like contains but is significantly faster due to full-text indexing.

Note this is available only in MySQL and requires direct manipulation of the database to add the full-text index.

The pk Lookup Shortcut

For convenience, Django provides a pk lookup type, which stands for primary_key.

In the example Blog model, the primary key is the id field, so these three statements are equivalent:

>>> Blog.objects.get(id__exact=14) # Explicit form
>>> Blog.objects.get(id=14) # __exact is implied
>>> Blog.objects.get(pk=14) # pk implies id__exact

The use of pk isnt limited to __exact queries any query term can be combined with pk to perform a query on the primary key of a model:

# Get blogs entries  with id 1, 4, and 7
>>> Blog.objects.filter(pk__in=[1,4,7])

# Get all blog entries with id > 14
>>> Blog.objects.filter(pk__gt=14)

pk lookups also work across joins. For example, these three statements are equivalent:

>>> Entry.objects.filter(blog__id__exact=3) # Explicit form
>>> Entry.objects.filter(blog__id=3) # __exact is implied
>>> Entry.objects.filter(blog__pk=3) # __pk implies __id__exact

Lookups That Span Relationships

跨越关系查找

Django offers a powerful and intuitive way to follow relationships in lookups, taking care of the SQL JOIN s for you automatically behind the scenes. To span a relationship, just use the field name of related fields across models, separated by double underscores, until you get to the field you want.

This example retrieves all Entry objects with a Blog whose name is 'Beatles Blog' :

>>> Entry.objects.filter(blog__name__exact='Beatles Blog')

This spanning can be as deep as youd like.

这跨越�之深�想而知�

It works backward, too. To refer to a reverse relationship, just use the lowercase name of the model.

This example retrieves all Blog objects that have at least one Entry whose headline contains 'Lennon' :

>>> Blog.objects.filter(entry__headline__contains='Lennon')

Foreign Key Relationships

外键关系

If a model has a ForeignKey , instances of that model will have access to the related (foreign) object via a simple attribute of the model, for example:

如果一个模型里�有一个 ForeignKey 字段，那么它的实例化对象�以很轻易的通过模型的属性�访问与其关�的关系对象，例如：

e = Entry.objects.get(id=2)
e.blog # Returns the related Blog object.

You can get and set via a foreign key attribute. As you may expect, changes to the foreign key arent saved to the database until you call save() , for example:

你�以通过外键属性�获�并设置关�的外键对象。如你所料，�纯修改外键的�作是�能马上将修改的内容�步到数�库中的，你还必须调用 save() 方法�行，例如：

e = Entry.objects.get(id=2)
e.blog = some_blog
e.save()

If a ForeignKey field has null=True set (i.e., it allows NULL values), you can assign None to it:

如果一个 ForeignKey 字段设置了 null=True 选项（�许 NULL 值）时，你�以将 None 赋给它（译注:但纯设置null=True其实还是�行的,会抛出异常的,还�须把blank=True也设了�行,�知�什么原因,我一直以�都有点怀疑这是个BUG)：

e = Entry.objects.get(id=2)
e.blog = None
e.save() # "UPDATE blog_entry SET blog_id = NULL ...;"

Forward access to one-to-many relationships is cached the first time the related object is accessed. Subsequent accesses to the foreign key on the same object instance are cached, for example:

e = Entry.objects.get(id=2)
print e.blog  # Hits the database to retrieve the associated Blog.
print e.blog  # Doesn't hit the database; uses cached version.

Note that the select_related() QuerySet method recursively prepopulates the cache of all one-to-many relationships ahead of time:

e = Entry.objects.select_related().get(id=2)
print e.blog  # Doesn't hit the database; uses cached version.
print e.blog  # Doesn't hit the database; uses cached version.

select_related() is documented in the QuerySet Methods That Return New QuerySets section.

Reverse Foreign Key Relationships

外键的�引用关系

Foreign key relationships are automatically symmetrical a reverse relationship is inferred from the presence of a ForeignKey pointing to another model.

外键关系是自动对称�引用关系的,这�由一个外键�以指��一个模型而得知.

If a model has a ForeignKey , instances of the foreign key model will have access to a Manager that returns all instances of the first model. By default, this Manager is named FOO_set , where FOO is the source model name, lowercased. This Manager returns QuerySets , which can be filtered and manipulated as described in the Retrieving Objects section.

如果一个æº�模型å�«æœ‰ä¸€ä¸ªå¤–é”®,那么它的外键模型的实例,å�¯ä»¥åˆ©ç”¨”Manager”返回这个æº�模型的所有实例.默认的这个”Manager”å�«å�š”FOO_set”,这个”FOO”是æº�模型的å��å­—,å°�写字æ¯�,这个”Manager”将返回”QuerySets”,对这个QuerySets进行过滤和æ“�作,å°±åƒ�在检索对象章节中介ç»�çš„.

Heres an example:

b = Blog.objects.get(id=1)
b.entry_set.all() # Returns all Entry objects related to Blog.

# b.entry_set is a Manager that returns QuerySets.
b.entry_set.filter(headline__contains='Lennon')
b.entry_set.count()

You can override the FOO_set name by setting the related_name parameter in the ForeignKey() definition. For example, if the Entry model was altered to blog = ForeignKey(Blog, related_name='entries') , the preceding example code would look like this:

通过在”ForeignKey()”中定义related_nameå�‚æ•°,ä½ å�¯ä»¥é‡�è½½”FOO_set”å��å­—.举例,如果把”Entry”模型修改为”blog =ForeignKey(Blog, related_name=’entries’)”,处ç�†ä¾‹å­�的代ç �如下:

b = Blog.objects.get(id=1)
b.entries.all() # Returns all Entry objects related to Blog.

# b.entries is a Manager that returns QuerySets.
b.entries.filter(headline__contains='Lennon')
b.entries.count()

You cannot access a reverse ForeignKey Manager from the class; it must be accessed from an instance:

ä½ ä¸�能直接访问这个类的reverse “ForeignKey” “Manager”;它必须通过一个实例:

Blog.entry_set # Raises AttributeError: "Manager must be accessed via instance".

In addition to the QuerySet methods defined in the Retrieving Objects section, the ForeignKey Manager has these additional methods:

add(obj1, obj2, ...) : Adds the specified model objects to the related object set, for example:

b = Blog.objects.get(id=1)
e = Entry.objects.get(id=234)
b.entry_set.add(e) # Associates Entry e with Blog b.

create(**kwargs) : Creates a new object, saves it, and puts it in the related object set. It returns the newly created object:

b = Blog.objects.get(id=1)
e = b.entry_set.create(headline='Hello', body_text='Hi', pub_date=datetime.date(2005, 1, 1))
# No need to call e.save() at this point -- it's already been saved.

This is equivalent to (but much simpler than) the following:

b = Blog.objects.get(id=1)
e = Entry(blog=b, headline='Hello', body_text='Hi', pub_date=datetime.date(2005, 1, 1))
e.save()

Note that theres no need to specify the keyword argument of the model that defines the relationship. In the preceding example, we dont pass the parameter blog to create() . Django figures out that the new Entry objects blog field should be set to b .

注æ„�到,这并没有必è¦�在定义了外键关系的模型中定义关键字å�‚æ•°.在之å‰�的例å­�中,我们没有传递”blog”å�‚æ•°ç»™”create()”.Django会解决这个新建的”Entry”对象的blog字段值设置为b.

remove(obj1, obj2, ...) : Removes the specified model objects from the related object set:

b = Blog.objects.get(id=1)
e = Entry.objects.get(id=234)
b.entry_set.remove(e) # Disassociates Entry e from Blog b.

In order to prevent database inconsistency, this method only exists on ForeignKey objects where null=True . If the related field cant be set to None (NULL ), then an object cant be removed from a relation without being added to another. In the preceding example, removing e from b.entry_set() is equivalent to doing e.blog = None , and because the blog ForeignKey doesnt have null=True , this is invalid.

为了阻止数æ�®åº“çš„ä¸�稳定,è¿™ç§�方法å�ªèƒ½å¯¹å�«æœ‰å¤–键字段并且该字段å�¯ä»¥ä¸ºnull的对象有效,如果关è�”字段ä¸�能设置为”None”(“NULL”),then an object can’t be removed from a relation without being added to another. 在之å‰�的例å­�中,从``b.entry_set()`` 中删除e,相当于”e.blog=None”,因为这个”blog”“ForeignKey”ä¸�能”nullTrue”,所以这是无效的删除.

clear() : Removes all objects from the related object set:

b = Blog.objects.get(id=1)
b.entry_set.clear()

Note this doesnt delete the related objects it just disassociates them.

注�: 这并�会删除关�的对象,仅是断开与它们的关�

Just like remove() , clear() is only available on ForeignKey``s where ``null=True .

To assign the members of a related set in one fell swoop, just assign to it from any iterable object, for example:

通过给关�集分�一个�迭代的对象�以实现一股脑的把多个对象赋给它

b = Blog.objects.get(id=1)
b.entry_set = [e1, e2]

If the clear() method is available, any pre-existing objects will be removed from the entry_set before all objects in the iterable (in this case, a list) are added to the set. If the clear() method is not available, all objects in the iterable will be added without removing any existing elements.

Each reverse operation described in this section has an immediate effect on the database. Every addition, creation, and deletion is immediately and automatically saved to the database.

Many-to-Many Relationships

多对多关系

Both ends of a many-to-many relationship get automatic API access to the other end. The API works just as a reverse one-to-many relationship (described in the previous section).

在多对多关系的两端，都�以通过相应的API�访问�外的一端。 API的工作方�跟�一节所�述的��一对多关系差�多。

The only difference is in the attribute naming: the model that defines the ManyToManyField uses the attribute name of that field itself, whereas the reverse model uses the lowercased model name of the original model, plus '_set' (just like reverse one-to-many relationships).

唯一的��在于属性的命�：定义了``ManyToManyField``的model的实例使用属性�称本身，�外一端的model的实例则使用model�称的�写加上``_set``�活得关�的对象集（就跟��一对多关系一样）

An example makes this concept easier to understand:

用例��说明一下大家会更容易�解：

e = Entry.objects.get(id=3)
e.authors.all() # Returns all Author objects for this Entry.
e.authors.count()
e.authors.filter(name__contains='John')

a = Author.objects.get(id=5)
a.entry_set.all() # Returns all Entry objects for this Author.

Like ForeignKey , ManyToManyField can specify related_name . In the preceding example, if the ManyToManyField in Entry had specified related_name='entries' , then each Author instance would have an entries attribute instead of entry_set .

How Are the Backward Relationships Possible?

Other object-relational mappers require you to define relationships on both sides. The Django developers believe this is a violation of the DRY (Dont Repeat Yourself) principle, so Django requires you to define the relationship on only one end. But how is this possible, given that a model class doesnt know which other model classes are related to it until those other model classes are loaded?

The answer lies in the INSTALLED_APPS setting. The first time any model is loaded, Django iterates over every model in INSTALLED_APPS and creates the backward relationships in memory as needed. Essentially, one of the functions of INSTALLED_APPS is to tell Django the entire model domain.

Queries Over Related Objects

通过关�对象查询

Queries involving related objects follow the same rules as queries involving normal value fields. When specifying the value for a query to match, you may use either an object instance itself or the primary key value for the object.

包�关�对象的�索和包�普通字段的�索�循相�的规则。当指定一个值去查询时，你�以使用那个对象的一个实例，也�以使用它的主键值。

For example, if you have a Blog object b with id=5 , the following three queries would be identical:

Entry.objects.filter(blog=b) # Query using object instance
Entry.objects.filter(blog=b.id) # Query using id from instance
Entry.objects.filter(blog=5) # Query using id directly

get_FOO_display()

For every field that has choices set, the object will have a get_FOO_display() method, where FOO is the name of the field. This method returns the human-readable value of the field. For example, in the following model:

GENDER_CHOICES = (
    ('M', 'Male'),
    ('F', 'Female'),
)
class Person(models.Model):
    name = models.CharField(max_length=20)
    gender = models.CharField(max_length=1, choices=GENDER_CHOICES)

each Person instance will have a get_gender_display() method:

�一个 Person 实例都将有一个 get_gender_display() 方法：

>>> p = Person(name='John', gender='M')
>>> p.save()
>>> p.gender
'M'
>>> p.get_gender_display()
'Male'

get_next_by_FOO(**kwargs) and 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 the appropriate DoesNotExist exception when appropriate.

对于任何ä¸�å…�许空值的DateFieldå’ŒDateTimeField字段，将会有”get_next_by_FOO()”å’Œ”get_previous_by_FOO()”这两个方法。FOO表示字段å��。这两个方法将根æ�®ç»™å®šçš„日期字段返回其å‰�一个ã€�å�Žä¸€ä¸ªå¯¹è±¡ï¼Œé€‚当的时候会抛出”DoesNotExist”的异常。

Both methods accept optional keyword arguments, which should be in the format described in the Field Lookups section.

两�方法都接��选的关键��数，这些�数应该�循 “域查询�一节中的格�。

Note that in the case of identical date values, these methods will use the ID as a fallback check. This guarantees that no records are skipped or duplicated. For a full example, see the lookup API samples at http://www.djangoproject.com/documentation/0.96/models/lookup/.

get_FOO_filename()

For every FileField , the object will have a get_FOO_filename() method, where FOO is the name of the field. This returns the full filesystem path to the file, according to your MEDIA_ROOT setting.

Note that ImageField is technically a subclass of FileField , so every model with an ImageField will also get this method.

注�到 ``ImageField``从技术上是 ``FileField``的�类，所以�个有``ImageField``的模型都有这个方法。

get_FOO_url()

For every FileField , the object will have a get_FOO_url() method, where FOO is the name of the field. This returns the full URL to the file, according to your MEDIA_URL setting. If the value is blank, this method returns an empty string.

get_FOO_size()

For every FileField , the object will have a get_FOO_size() method, where FOO is the name of the field. This returns the size of the file, in bytes. (Behind the scenes, it uses os.path.getsize .)

save_FOO_file(filename, raw_contents)

For every FileField , the object will have a save_FOO_file() method, where FOO is the name of the field. This saves the given file to the filesystem, using the given file name. If a file with the given file name already exists, Django adds an underscore to the end of the file name (but before the extension) until the file name is available.

get_FOO_height() and get_FOO_width()

For every ImageField , the object will have get_FOO_height() and get_FOO_width() methods, where FOO is the name of the field. This returns the height (or width) of the image, as an integer, in pixels.

get_object_or_404()

One common idiom to use get() and raise Http404 if the object doesnt exist. This idiom is captured by get_object_or_404() . This function takes a Django model as its first argument and an arbitrary number of keyword arguments, which it passes to the default managers get() function. It raises Http404 if the object doesnt exist, for example:

# Get the Entry with a primary key of 3
e = get_object_or_404(Entry, pk=3)

When you provide a model to this shortcut function, the default manager is used to execute the underlying get() query. If you dont want to use the default manager, or if you want to search a list of related objects, you can provide get_object_or_404() with a Manager object instead:

# Get the author of blog instance e with a name of 'Fred'
a = get_object_or_404(e.authors, name='Fred')

# Use a custom manager 'recent_entries' in the search for an
# entry with a primary key of 3
e = get_object_or_404(Entry.recent_entries, pk=3)

get_list_or_404()

get_list_or_404 behaves the same way as get_object_or_404() , except that it uses filter() instead of get() . It raises Http404 if the list is empty.

get_list_or_404 行为与 get_object_or_404() 相�，但是它用 filter() �代了 get() 。如果列表为空，它将引� Http404 。