django 1.8 官方文档翻译: 2-5-1 管理器 (初稿)

Django 文档协作翻译小组人手紧缺,有兴趣的朋友可以加入我们,完全公益性质。

交流群:467338606

网站:http://python.usyiyi.cn/django/index.html

管理器

class Manager

管理器是一个接口,数据库查询操作通过它提供给django的模型。django应用的每个模型至少拥有一个 管理器。

管理器类的工作方式在 执行查询文档中阐述,而这篇文档涉及了自定义管理器行为的模型选项。

管理器的名字

通常,django为每个模型类添加一个名为objects的管理器。然而,如果你想将objects用于字段名称,或者你想使用其它名称而不是objects访问管理器,你可以在每个模型类中重命名它。在模型中定义一个值为models.Manager()的属性,来重命名管理器。例如:

from django.db import models

class Person(models.Model):
    #...
    people = models.Manager()

使用例子中的模型, Person.objects会抛出AttributeError异常,而Person.people.all()会返回一个包含所有Person对象的列表。

自定义管理器

在一个特定的模型中,你可以通过继承管理器类来构建一个自定义的管理器,以及实例化你的自定义管理器。

你有两个原因可能会自己定义管理器:向器类中添加额外的方法,或者修改管理器最初返回的查询集。

添加额外的管理器方法

为你的模型添加表级(table-level)功能时,采用添加额外的管理器方法是更好的处理方式。如果要添加行级功能--就是说该功能只对某个模型的实例对象起作用。在这种情况下,使用 模型方法 比使用自定义的管理器方法要更好。)

自定义的管理器 方法可以返回你想要的任何数据,而不只是查询集。

例如,下面这个自定义的 管理器提供了一个 with_counts() 方法,它返回所有 OpinionPoll 对象的列表,而且列表中的每个对象都多了一个名为 num_responses的属性,这个属性保存一个聚合查询(COUNT*)的结果:

from django.db import models

class PollManager(models.Manager):
    def with_counts(self):
        from django.db import connection
        cursor = connection.cursor()
        cursor.execute("""
            SELECT p.id, p.question, p.poll_date, COUNT(*)
            FROM polls_opinionpoll p, polls_response r
            WHERE p.id = r.poll_id
            GROUP BY p.id, p.question, p.poll_date
            ORDER BY p.poll_date DESC""")
        result_list = []
        for row in cursor.fetchall():
            p = self.model(id=row[0], question=row[1], poll_date=row[2])
            p.num_responses = row[3]
            result_list.append(p)
        return result_list

class OpinionPoll(models.Model):
    question = models.CharField(max_length=200)
    poll_date = models.DateField()
    objects = PollManager()

class Response(models.Model):
    poll = models.ForeignKey(OpinionPoll)
    person_name = models.CharField(max_length=50)
    response = models.TextField()

在这个例子中,你已经可以使用 OpinionPoll.objects.with_counts() 得到所有含有 num_responses属性的 OpinionPoll对象。

这个例子要注意的一点是: 管理器方法可以访问 self.model来得到它所用到的模型类。

修改管理器初始的查询集

管理器自带的 查询集返回系统中所有的对象。例如,使用下面这个模型:

from django.db import models

class Book(models.Model):
    title = models.CharField(max_length=100)
    author = models.CharField(max_length=50)

... Book.objects.all() 语句将返回数据库中所有的 Book 对象。

你可以通过重写 Manager.get_queryset() 的方法来覆盖 管理器自带的 查询集。get_queryset() 会根据你所需要的属性返回 查询集。

例如,下面的模型有两个 管理器,一个返回所有的对象,另一个则只返回作者是 Roald Dahl 的对象:

# First, define the Manager subclass.
class DahlBookManager(models.Manager):
    def get_queryset(self):
        return super(DahlBookManager, self).get_queryset().filter(author='Roald Dahl')

# Then hook it into the Book model explicitly.
class Book(models.Model):
    title = models.CharField(max_length=100)
    author = models.CharField(max_length=50)

    objects = models.Manager() # The default manager.
    dahl_objects = DahlBookManager() # The Dahl-specific manager.

在这个简单的例子中,Book.objects.all()将返回数据库中所有的图书。而 Book.dahl_objects.all() 只返回作者是 Roald Dahl 的图书。

由于 get_queryset() 返回的是一个 查询集 对象,所以你仍可以对它使用 filter(), exclude()和其他 查询集的方法。所以下面这些例子都是可用的:

Book.dahl_objects.all()
Book.dahl_objects.filter(title='Matilda')
Book.dahl_objects.count()

这个例子还展示了另外一个很有意思的技巧:在同一个模型中使用多个管理器。你可以随你所意在一个模型里面添加多个 Manager() 实例。下面就用很简单的方法,给模型添加通用过滤器:

例如:

class AuthorManager(models.Manager):
    def get_queryset(self):
        return super(AuthorManager, self).get_queryset().filter(role='A')

class EditorManager(models.Manager):
    def get_queryset(self):
        return super(EditorManager, self).get_queryset().filter(role='E')

class Person(models.Model):
    first_name = models.CharField(max_length=50)
    last_name = models.CharField(max_length=50)
    role = models.CharField(max_length=1, choices=(('A', _('Author')), ('E', _('Editor'))))
    people = models.Manager()
    authors = AuthorManager()
    editors = EditorManager()

在这个例子中,你使用 Person.authors.all(), Person.editors.all(),以及 Person.people.all(), 都会得到和名称相符的结果。

默认管理器

如果你使用了自定义 管理器对象,要注意 Django 中的第一个 管理器 (按照模型中出现的顺序而定) 拥有特殊的地位。Django 会将模型中定义的管理器解释为默认的 管理器,并且 Django 中的一部分应用(包括数据备份)会使用默认的管理器,除了前面那个模型。因此,要决定默认的管理器时,要小心谨慎,仔细考量,这样才能避免重写 get_queryset() 导致无法正确地获得数据。

使用管理器访问关联对象

默认情况下,在访问相关对象时(例如choice.poll),Django 并不使用相关对象的默认管理器,而是使用一个"朴素"管理器类的实例来访问。这是因为 Django 要能从关联对象中获得数据,但这些数据有可能被默认管理器过滤掉,或是无法进行访问。

如果普通的朴素管理器类(django.db.models.Manager)并不适用于你的应用,那么你可以通过在管理器类中设置 use_for_related_fields ,强制 Django 在你的模型中使用默认的管理器。这部分内容在 下面有 详细介绍。

调用自定义的查询集

虽然大多数标准查询集的方法可以从管理器中直接访问到,但是这是一个例子,访问了定义在自定义 查询集上的额外方法,如果你也在管理器上面实现了它们:

class PersonQuerySet(models.QuerySet):
    def authors(self):
        return self.filter(role='A')

    def editors(self):
        return self.filter(role='E')

class PersonManager(models.Manager):
    def get_queryset(self):
        return PersonQuerySet(self.model, using=self._db)

    def authors(self):
        return self.get_queryset().authors()

    def editors(self):
        return self.get_queryset().editors()

class Person(models.Model):
    first_name = models.CharField(max_length=50)
    last_name = models.CharField(max_length=50)
    role = models.CharField(max_length=1, choices=(('A', _('Author')), ('E', _('Editor'))))
    people = PersonManager()

这个例子展示了如何直接从管理器 Person.people调用authors() 和 editors()。

创建管理器

** django 1.7 中新增 **

对于上面的例子,同一个方法需要在查询集 和 管理器上创建两份副本,作为替代,QuerySet.as_manager()可以创建一个管理器的实例,它拥有自定义查询集的方法:

class Person(models.Model):
    ...
    people = PersonQuerySet.as_manager()

通过QuerySet.as_manager()创建的管理器 实例,实际上等价于上面例子中的PersonManager。

并不是每个查询集的方法都在管理器层面上有意义。比如 QuerySet.delete(),我们有意防止它复制到管理器 中。

方法按照以下规则进行复制:

  • 公共方法默认被复制。
  • 私有方法(前面带一个下划线)默认不被复制。
  • 带queryset_only 属性,并且值为False的方法总是被复制。
  • 带 queryset_only 属性,并且值为True 的方法不会被复制。

例如:

class CustomQuerySet(models.QuerySet):
    # Available on both Manager and QuerySet.
    def public_method(self):
        return

    # Available only on QuerySet.
    def _private_method(self):
        return

    # Available only on QuerySet.
    def opted_out_public_method(self):
        return
    opted_out_public_method.queryset_only = True

    # Available on both Manager and QuerySet.
    def _opted_in_private_method(self):
        return
    _opted_in_private_method.queryset_only = False

from_queryset

classmethod from_queryset(queryset_class)

在进一步的使用中,你可能想创建一个自定义管理器和一个自定义查询集。你可以调用Manager.from_queryset(),它会返回管理器的一个子类,带有自定义查询集所有方法的副本:

class BaseManager(models.Manager):
    def manager_only_method(self):
        return

class CustomQuerySet(models.QuerySet):
    def manager_and_queryset_method(self):
        return

class MyModel(models.Model):
    objects = BaseManager.from_queryset(CustomQueryset)()

你也可以在一个变量中储存生成的类:

CustomManager = BaseManager.from_queryset(CustomQueryset)

class MyModel(models.Model):
    objects = CustomManager()

自定义管理器和模型继承

类继承和模型管理器两者之间配合得并不是很好。 管理器一般只对其定义所在的类起作用,在子类中对其继承绝对不是一个好主意。 而且,因为第一个 管理器会被 Djange 声明为默认的管理器,所以对默认的管理器 进行控制是非常必要的。下面就是 Django 如何处理自定义管理器和模型继承(model inheritance)的:

  • 定义在非抽象基类中的管理器是 不会 被子类继承的。如果你想从一个非抽象基类中重用管理器,只能在子类中重定义管理器。 这是因为这种管理器与定义它的模型 绑定得非常紧密,所以继承它们经常会导致异常的结果(特别是默认管理器运行的时候)。 因此,它们不应继承给子类。
  • 定义在抽象基类中的管理器总是被子类继续的,是按 Python 的命名解析顺序解析的(首先是子类中的命名覆盖所有的,然后是第一个父类的,以此类推)。 抽象类用来提取子类中的公共信息和行为,定义公共管理器也是公共信息的一部分。
  • 如果类当中显示定义了默认管理器,Django 就会以此做为默认管理器;否则就会从第一个抽象基类中继承默认管理器; 如果没有显式声明默认管理器,那么 Django 就会自动添加默认管理器。

如果你想在一组模型上安装一系列自定义管理器,上面提到的这些规则就已经为你的实现提供了必要的灵活性。你可以继承一个抽象基类,但仍要自定义默认的管理器。例如,假设你的基类是这样的:

class AbstractBase(models.Model):
    # ...
    objects = CustomManager()

    class Meta:
        abstract = True

如果你在基类中没有定义管理器,直接使用上面的代码,默认管理器就是从基类中继承的 objects:

class ChildA(AbstractBase):
    # ...
    # This class has CustomManager as the default manager.
    pass

如果你想从 AbstractBase继承,却又想提供另一个默认管理器,那么你可以在子类中定义默认管理器:

class ChildB(AbstractBase):
    # ...
    # An explicit default manager.
    default_manager = OtherManager()

在这个例子中, default_manager就是默认的 管理器。从基类中继承的 objects 管理器仍是可用的。只不过它不再是默认管理器罢了。

最后再举个例子,假设你想在子类中再添加一个额外的管理器,但是很想使用从 AbstractBase继承的管理器做为默认管理器。那么,你不在直接在子类中添加新的管理器,否则就会覆盖掉默认管理器,而且你必须对派生自这个基类的所有子类都显示指定管理器。 解决办法就是在另一个基类中添加新的管理器,然后继承时将其放在默认管理器所在的基类 之后。例如:

class ExtraManager(models.Model):
    extra_manager = OtherManager()

    class Meta:
        abstract = True

class ChildC(AbstractBase, ExtraManager):
    # ...
    # Default manager is CustomManager, but OtherManager is
    # also available via the "extra_manager" attribute.
    pass

注意在抽象模型上面定义一个自定义管理器的时候,不能调用任何使用这个抽象模型的方法。就像:

ClassA.objects.do_something()

是可以的,但是:

AbstractBase.objects.do_something()

会抛出一个异常。这是因为,管理器被设计用来封装对象集合管理的逻辑。由于抽象的对象中并没有一个集合,管理它们是毫无意义的。如果你写了应用在抽象模型上的功能,你应该把功能放到抽象模型的静态方法,或者类的方法中。

实现上的注意事项

无论你向自定义管理器中添加了什么功能,都必须可以得到 管理器实例的一个浅表副本:例如,下面的代码必须正常运行:

>>> import copy
>>> manager = MyManager()
>>> my_copy = copy.copy(manager)

Django 在一些查询中会创建管理器的浅表副本;如果你的管理器不能被复制,查询就会失败。

这对于大多数自定义管理器不是什么大问题。如果你只是添加一些简单的方法到你的管理器中,不太可能会把你的管理器实例变为不可复制的。但是,如果你覆盖了__getattr__,或者其它管理器中控制对象状态的私有方法,你应该确保不会影响到管理器的复制。

控制自动管理器的类型

这篇文档已经提到了Django创建管理器类的一些位置:默认管理器和用于访问关联对象的“朴素” 管理器。在 Django 的实现中也有很多地方用到了临时的朴素管理器。 正常情况下,django.db.models.Manager 类的实例会自动创建管理器。

在整个这一节中,我们将那种由 Django 为你创建的管理器称之为 "自动管理器",既有因为没有管理器而被 Django 自动添加的默认管理器, 也包括在访问关联模型时使用的临时管理器。

有时,默认管理器也并非是自动管理器。 一个例子就是 Django 自带的django.contrib.gis 应用,所有 gis模型都必须使用一个特殊的管理器类(GeoManager),因为它们需要运行特殊的查询集(GeoQuerySet)与数据库进行交互。这表明无论自动管理器是否被创建,那些要使用特殊的管理器的模型仍要使用这个特殊的管理器类。

Django 为自定义管理器的开发者提供了一种方式:无论开发的管理器类是不是默认的管理器,它都应该可以用做自动管理器。 可以通过在管理器类中设置 use_for_related_fields 属性来做到这点:

class MyManager(models.Manager):
    use_for_related_fields = True
    # ...

如果在模型中的默认 管理器(在这些情况中仅考虑默认管理器)中设置了这个属性,那么无论它是否需要被自动创建,Django 都会自动使用它。否则 Django 就会使用 django.db.models.Manager.

历史回顾

从它使用目的来看,这个属性的名称(use_for_related_fields)好象有点古怪。原本,这个属性仅仅是用来控制访问关联字段的管理器的类型,这就是它名字的由来。 后来它的作用更加拓宽了,但是名称一直未变。 因为要保证现在的代码在 Django 以后的版本中仍可以正常工作(continue to work),这就是它名称不变的原因。

在自动管理器实例中编写正确的管理器

在上面的django.contrib.gis 已经提到了, use_for_related_fields这个特性是在需要返回一个自定义查询集子类的管理器中使用的。要在你的管理器中提供这个功能,要注意以下几点。

不要在这种类型的管理器子类中过滤掉任何结果

一个原因是自动管理器是用来访问关联模型 的对象。 在这种情况下,Django 必须要能看到相关模型的所有对象,所以才能根据关联关系得到任何数据 。

如果你重写了 get_queryset() 方法并且过滤掉了一些行数据,Django 将返回不正确的结果。不要这么做! 在 get_queryset()方法中过滤掉数据,会使得它所在的管理器不适于用做自动管理器。

设置 use_for_related_fields

use_for_related_fields属性必须在管理器类中设置,而不是在类的 实例中设置。上面已经有例子展示如何正确地设置,下面这个例子就是一个错误的示范:

# BAD: Incorrect code
class MyManager(models.Manager):
    # ...
    pass

# Sets the attribute on an instance of MyManager. Django will
# ignore this setting.
mgr = MyManager()
mgr.use_for_related_fields = True

class MyModel(models.Model):
    # ...
    objects = mgr

# End of incorrect code.

你也不应该在模型中使用这个属性之后,在类上改变它。这是因为在模型类被创建时,这个属性值马上就会被处理,而且随后不会再读取这个属性值。 这节的第一个例子就是在第一次定义的时候在管理器上设置use_for_related_fields属性,所有的代码就工作得很好。

你可能感兴趣的:(django 1.8 官方文档翻译: 2-5-1 管理器 (初稿))