Django2.0手册:模型

Many-to-one relationships¶

To define a many-to-one relationship, use django.db.models.ForeignKey.
You use it just like any other Field type: by
including it as a class attribute of your model.

ForeignKey requires a positional argument: the class
to which the model is related.

For example, if a Car model has a Manufacturer — that is, a
Manufacturer makes multiple cars but each Car only has one
Manufacturer — use the following definitions:

from django.db import models

class Manufacturer(models.Model):
    # ...
    pass

class Car(models.Model):
    manufacturer = models.ForeignKey(Manufacturer, on_delete=models.CASCADE)
    # ...

You can also create recursive relationships (an
object with a many-to-one relationship to itself) and relationships to
models not yet defined; see the model field
reference for details.

It’s suggested, but not required, that the name of a
ForeignKey field (manufacturer in the example
above) be the name of the model, lowercase. You can, of course, call the field
whatever you want. For example:

class Car(models.Model):
    company_that_makes_it = models.ForeignKey(
        Manufacturer,
        on_delete=models.CASCADE,
    )
    # ...

Many-to-many relationships¶

To define a many-to-many relationship, use
ManyToManyField. You use it just like any other
Field type: by including it as a class attribute of
your model.

ManyToManyField requires a positional argument: the
class to which the model is related.

For example, if a Pizza has multiple Topping objects — that is, a
Topping can be on multiple pizzas and each Pizza has multiple toppings
— here’s how you’d represent that:

from django.db import models

class Topping(models.Model):
    # ...
    pass

class Pizza(models.Model):
    # ...
    toppings = models.ManyToManyField(Topping)

As with ForeignKey, you can also create
recursive relationships (an object with a
many-to-many relationship to itself) and relationships to models not yet
defined.

It’s suggested, but not required, that the name of a
ManyToManyField (toppings in the example above)
be a plural describing the set of related model objects.

It doesn’t matter which model has the
ManyToManyField, but you should only put it in one
of the models — not both.

Generally, ManyToManyField instances should go in
the object that’s going to be edited on a form. In the above example,
toppings is in Pizza (rather than Topping having a pizzas
ManyToManyField ) because it’s more natural to think
about a pizza having toppings than a topping being on multiple pizzas. The way
it’s set up above, the Pizza form would let users select the toppings.

ManyToManyField fields also accept a number of
extra arguments which are explained in the model field reference. These options help define how the relationship
should work; all are optional.

Extra fields on many-to-many relationships¶

When you’re only dealing with simple many-to-many relationships such as
mixing and matching pizzas and toppings, a standard
ManyToManyField is all you need. However, sometimes
you may need to associate data with the relationship between two models.

For example, consider the case of an application tracking the musical groups
which musicians belong to. There is a many-to-many relationship between a person
and the groups of which they are a member, so you could use a
ManyToManyField to represent this relationship.
However, there is a lot of detail about the membership that you might want to
collect, such as the date at which the person joined the group.

For these situations, Django allows you to specify the model that will be used
to govern the many-to-many relationship. You can then put extra fields on the
intermediate model. The intermediate model is associated with the
ManyToManyField using the
through argument to point to the model
that will act as an intermediary. For our musician example, the code would look
something like this:

from django.db import models

class Person(models.Model):
    name = models.CharField(max_length=128)

    def __str__(self):
        return self.name

class Group(models.Model):
    name = models.CharField(max_length=128)
    members = models.ManyToManyField(Person, through='Membership')

    def __str__(self):
        return self.name

class Membership(models.Model):
    person = models.ForeignKey(Person, on_delete=models.CASCADE)
    group = models.ForeignKey(Group, on_delete=models.CASCADE)
    date_joined = models.DateField()
    invite_reason = models.CharField(max_length=64)

When you set up the intermediary model, you explicitly specify foreign
keys to the models that are involved in the many-to-many relationship. This
explicit declaration defines how the two models are related.

There are a few restrictions on the intermediate model:

• Your intermediate model must contain one – and only one – foreign key
  to the source model (this would be Group in our example), or you must
  explicitly specify the foreign keys Django should use for the relationship
  using ManyToManyField.through_fields.
  If you have more than one foreign key and through_fields is not
  specified, a validation error will be raised. A similar restriction applies
  to the foreign key to the target model (this would be Person in our
  example).
• For a model which has a many-to-many relationship to itself through an
  intermediary model, two foreign keys to the same model are permitted, but
  they will be treated as the two (different) sides of the many-to-many
  relationship. If there are more than two foreign keys though, you
  must also specify through_fields as above, or a validation error
  will be raised.
• When defining a many-to-many relationship from a model to
  itself, using an intermediary model, you must use
  symmetrical=False (see
  the model field reference).

Now that you have set up your ManyToManyField to use
your intermediary model (Membership, in this case), you’re ready to start
creating some many-to-many relationships. You do this by creating instances of
the intermediate model:

>>> ringo = Person.objects.create(name="Ringo Starr")
>>> paul = Person.objects.create(name="Paul McCartney")
>>> beatles = Group.objects.create(name="The Beatles")
>>> m1 = Membership(person=ringo, group=beatles,
...     date_joined=date(1962, 8, 16),
...     invite_reason="Needed a new drummer.")
>>> m1.save()
>>> beatles.members.all()
<QuerySet [<Person: Ringo Starr>]>
>>> ringo.group_set.all()
<QuerySet [<Group: The Beatles>]>
>>> m2 = Membership.objects.create(person=paul, group=beatles,
...     date_joined=date(1960, 8, 1),
...     invite_reason="Wanted to form a band.")
>>> beatles.members.all()
<QuerySet [<Person: Ringo Starr>, <Person: Paul McCartney>]>

Unlike normal many-to-many fields, you can’t use add(), create(),
or set() to create relationships:

>>> # The following statements will not work
>>> beatles.members.add(john)
>>> beatles.members.create(name="George Harrison")
>>> beatles.members.set([john, paul, ringo, george])

Why? You can’t just create a relationship between a Person and a Group
– you need to specify all the detail for the relationship required by the
Membership model. The simple add, create and assignment calls
don’t provide a way to specify this extra detail. As a result, they are
disabled for many-to-many relationships that use an intermediate model.
The only way to create this type of relationship is to create instances of the
intermediate model.

The remove() method is
disabled for similar reasons. For example, if the custom through table defined
by the intermediate model does not enforce uniqueness on the
(model1, model2) pair, a remove() call would not provide enough
information as to which intermediate model instance should be deleted:

>>> Membership.objects.create(person=ringo, group=beatles,
...     date_joined=date(1968, 9, 4),
...     invite_reason="You've been gone for a month and we miss you.")
>>> beatles.members.all()
<QuerySet [<Person: Ringo Starr>, <Person: Paul McCartney>, <Person: Ringo Starr>]>
>>> # This will not work because it cannot tell which membership to remove
>>> beatles.members.remove(ringo)

However, the clear()
method can be used to remove all many-to-many relationships for an instance:

>>> # Beatles have broken up
>>> beatles.members.clear()
>>> # Note that this deletes the intermediate model instances
>>> Membership.objects.all()
<QuerySet []>

Once you have established the many-to-many relationships by creating instances
of your intermediate model, you can issue queries. Just as with normal
many-to-many relationships, you can query using the attributes of the
many-to-many-related model:

# Find all the groups with a member whose name starts with 'Paul'
>>> Group.objects.filter(members__name__startswith='Paul')
<QuerySet [<Group: The Beatles>]>

As you are using an intermediate model, you can also query on its attributes:

# Find all the members of the Beatles that joined after 1 Jan 1961
>>> Person.objects.filter(
...     group__name='The Beatles',
...     membership__date_joined__gt=date(1961,1,1))
<QuerySet [<Person: Ringo Starr]>

If you need to access a membership’s information you may do so by directly
querying the Membership model:

>>> ringos_membership = Membership.objects.get(group=beatles, person=ringo)
>>> ringos_membership.date_joined
datetime.date(1962, 8, 16)
>>> ringos_membership.invite_reason
'Needed a new drummer.'

Another way to access the same information is by querying the
many-to-many reverse relationship from a
Person object:

>>> ringos_membership = ringo.membership_set.get(group=beatles)
>>> ringos_membership.date_joined
datetime.date(1962, 8, 16)
>>> ringos_membership.invite_reason
'Needed a new drummer.'

One-to-one relationships¶

To define a one-to-one relationship, use
OneToOneField. You use it just like any other
Field type: by including it as a class attribute of your model.

This is most useful on the primary key of an object when that object “extends”
another object in some way.

OneToOneField requires a positional argument: the
class to which the model is related.

For example, if you were building a database of “places”, you would
build pretty standard stuff such as address, phone number, etc. in the
database. Then, if you wanted to build a database of restaurants on
top of the places, instead of repeating yourself and replicating those
fields in the Restaurant model, you could make Restaurant have
a OneToOneField to Place (because a
restaurant “is a” place; in fact, to handle this you’d typically use
inheritance, which involves an implicit
one-to-one relation).

As with ForeignKey, a recursive relationship can be defined and references to as-yet
undefined models can be made.

OneToOneField fields also accept an optional
parent_link argument.

OneToOneField classes used to automatically become
the primary key on a model. This is no longer true (although you can manually
pass in the primary_key argument if you like).
Thus, it’s now possible to have multiple fields of type
OneToOneField on a single model.

Meta inheritance¶

When an abstract base class is created, Django makes any Meta
inner class you declared in the base class available as an
attribute. If a child class does not declare its own Meta
class, it will inherit the parent’s Meta. If the child wants to
extend the parent’s Meta class, it can subclass it. For example:

from django.db import models

class CommonInfo(models.Model):
    # ...
    class Meta:
        abstract = True
        ordering = ['name']

class Student(CommonInfo):
    # ...
    class Meta(CommonInfo.Meta):
        db_table = 'student_info'

Django does make one adjustment to the Meta class of an abstract base
class: before installing the Meta attribute, it sets abstract=False.
This means that children of abstract base classes don’t automatically become
abstract classes themselves. Of course, you can make an abstract base class
that inherits from another abstract base class. You just need to remember to
explicitly set abstract=True each time.

Some attributes won’t make sense to include in the Meta class of an
abstract base class. For example, including db_table would mean that all
the child classes (the ones that don’t specify their own Meta) would use
the same database table, which is almost certainly not what you want.

Be careful with related_name and related_query_name¶

If you are using related_name or
related_query_name on a ForeignKey or
ManyToManyField, you must always specify a unique reverse name and query
name for the field. This would normally cause a problem in abstract base
classes, since the fields on this class are included into each of the child
classes, with exactly the same values for the attributes (including
related_name and
related_query_name) each time.

To work around this problem, when you are using
related_name or
related_query_name in an abstract base
class (only), part of the value should contain '%(app_label)s' and
'%(class)s'.

• '%(class)s' is replaced by the lower-cased name of the child class
  that the field is used in.
• '%(app_label)s' is replaced by the lower-cased name of the app the child
  class is contained within. Each installed application name must be unique
  and the model class names within each app must also be unique, therefore the
  resulting name will end up being different.

For example, given an app common/models.py:

from django.db import models

class Base(models.Model):
    m2m = models.ManyToManyField(
        OtherModel,
        related_name="%(app_label)s_%(class)s_related",
        related_query_name="%(app_label)s_%(class)ss",
    )

    class Meta:
        abstract = True

class ChildA(Base):
    pass

class ChildB(Base):
    pass

Along with another app rare/models.py:

from common.models import Base

class ChildB(Base):
    pass

The reverse name of the common.ChildA.m2m field will be
common_childa_related and the reverse query name will be common_childas.
The reverse name of the common.ChildB.m2m field will be
common_childb_related and the reverse query name will be
common_childbs. Finally, the reverse name of the rare.ChildB.m2m field
will be rare_childb_related and the reverse query name will be
rare_childbs. It’s up to you how you use the '%(class)s' and
'%(app_label)s' portion to construct your related name or related query name
but if you forget to use it, Django will raise errors when you perform system
checks (or run migrate).

If you don’t specify a related_name
attribute for a field in an abstract base class, the default reverse name will
be the name of the child class followed by '_set', just as it normally
would be if you’d declared the field directly on the child class. For example,
in the above code, if the related_name
attribute was omitted, the reverse name for the m2m field would be
childa_set in the ChildA case and childb_set for the ChildB
field.

Meta and multi-table inheritance¶

In the multi-table inheritance situation, it doesn’t make sense for a child
class to inherit from its parent’s Meta class. All the Meta options
have already been applied to the parent class and applying them again would
normally only lead to contradictory behavior (this is in contrast with the
abstract base class case, where the base class doesn’t exist in its own
right).

So a child model does not have access to its parent’s Meta class. However, there are a few limited cases where the child
inherits behavior from the parent: if the child does not specify an
ordering attribute or a
get_latest_by attribute, it will inherit
these from its parent.

If the parent has an ordering and you don’t want the child to have any natural
ordering, you can explicitly disable it:

class ChildModel(ParentModel):
    # ...
    class Meta:
        # Remove parent's ordering effect
        ordering = []

Inheritance and reverse relations¶

Because multi-table inheritance uses an implicit
OneToOneField to link the child and
the parent, it’s possible to move from the parent down to the child,
as in the above example. However, this uses up the name that is the
default related_name value for
ForeignKey and
ManyToManyField relations. If you
are putting those types of relations on a subclass of the parent model, you
must specify the related_name
attribute on each such field. If you forget, Django will raise a validation
error.

For example, using the above Place class again, let’s create another
subclass with a ManyToManyField:

class Supplier(Place):
    customers = models.ManyToManyField(Place)

This results in the error:

Reverse query name for 'Supplier.customers' clashes with reverse query
name for 'Supplier.place_ptr'.

HINT: Add or change a related_name argument to the definition for
'Supplier.customers' or 'Supplier.place_ptr'.

Adding related_name to the customers field as follows would resolve the
error: models.ManyToManyField(Place, related_name='provider').

Specifying the parent link field¶

As mentioned, Django will automatically create a
OneToOneField linking your child
class back to any non-abstract parent models. If you want to control the
name of the attribute linking back to the parent, you can create your
own OneToOneField and set
parent_link=True
to indicate that your field is the link back to the parent class.

QuerySets still return the model that was requested¶

There is no way to have Django return, say, a MyPerson object whenever you
query for Person objects. A queryset for Person objects will return
those types of objects. The whole point of proxy objects is that code relying
on the original Person will use those and your own code can use the
extensions you included (that no other code is relying on anyway). It is not
a way to replace the Person (or any other) model everywhere with something
of your own creation.

Base class restrictions¶

一个代理模型必须仅能继承一个非抽象模型类。你不能继承多个非抽象模型类，因为代理模型无法提供不同数据表的任何行间连接。一个代理模型可以继承任意数量的抽象模型类，假如他们*没有*定义任何的模型字段。一个代理模型也可以继承任意数量的代理模型，只需他们共享同一个非抽象父类。

代理模型管理器¶

If you don’t specify any model managers on a proxy model, it inherits the
managers from its model parents. If you define a manager on the proxy model,
it will become the default, although any managers defined on the parent
classes will still be available.

Continuing our example from above, you could change the default manager used
when you query the Person model like this:

from django.db import models

class NewManager(models.Manager):
    # ...
    pass

class MyPerson(Person):
    objects = NewManager()

    class Meta:
        proxy = True

If you wanted to add a new manager to the Proxy, without replacing the
existing default, you can use the techniques described in the custom
manager documentation: create a base class
containing the new managers and inherit that after the primary base class:

# Create an abstract class for the new manager.
class ExtraManagers(models.Model):
    secondary = NewManager()

    class Meta:
        abstract = True

class MyPerson(Person, ExtraManagers):
    class Meta:
        proxy = True

通常情况下，你可能不需要这么做。然而，你需要的时候，这也是可以的。

Differences between proxy inheritance and unmanaged models¶

Proxy model inheritance might look fairly similar to creating an unmanaged
model, using the managed attribute on a
model’s Meta class.

With careful setting of Meta.db_table you could create an unmanaged model that
shadows an existing model and adds Python methods to it. However, that would be
very repetitive and fragile as you need to keep both copies synchronized if you
make any changes.

On the other hand, proxy models are intended to behave exactly like the model
they are proxying for. They are always in sync with the parent model since they
directly inherit its fields and managers.

The general rules are:

1. If you are mirroring an existing model or database table and don’t want
   all the original database table columns, use Meta.managed=False.
   That option is normally useful for modeling database views and tables
   not under the control of Django.
2. If you are wanting to change the Python-only behavior of a model, but
   keep all the same fields as in the original, use Meta.proxy=True.
   This sets things up so that the proxy model is an exact copy of the
   storage structure of the original model when data is saved.