29.7. abc — 抽象基类

源代码: Lib/abc.py


该模块提供了在 Python 中定义 抽象基类 (ABC) 的组件,在 PEP 3119 中已有概述。查看 PEP 文档了解为什么需要在 Python 中增加这个模块。(也可查看 PEP 3141 以及 numbers 模块了解基于 ABC 的数字类型继承关系。)

The collections module has some concrete classes that derive from ABCs; these can, of course, be further derived. In addition the collections.abc submodule has some ABCs that can be used to test whether a class or instance provides a particular interface, for example, is it hashable or a mapping.

This module provides the following classes:

class abc.ABCMeta

用于定义抽象基类(ABC)的元类。

使用该元类以创建抽象基类。抽象基类可以像 mix-in 类一样直接被子类继承。你也可以将不相关的具体类(包括内建类)和抽象基类注册为“抽象子类” —— 这些类以及它们的子类会被内建函数 issubclass() 识别为对应的抽象基类的子类,但是该抽象基类不会出现在其 MRO(Method Resolution Order,方法解析顺序)中,抽象基类中实现的方法也不可调用(即使通过 super() 调用也不行)。[1]

使用 ABCMeta 作为元类创建的类含有如下方法:

register(subclass)

将“子类”注册为该抽象基类的“抽象子类”,例如:

from abc import ABCMeta

class MyABC(metaclass=ABCMeta):
    pass

MyABC.register(tuple)

assert issubclass(tuple, MyABC)
assert isinstance((), MyABC)

3.3 版更變: 返回注册的子类,使其能够作为类装饰器。

3.4 版更變: 你可以使用 get_cache_token() 函数来检测对 register() 的调用。

你也可以在虚基类中重载这个方法。

__subclasshook__(subclass)

(必须定义为类方法。)

检查 subclass 是否是该抽象基类的子类。也就是说对于那些你希望定义为该抽象基类的子类的类,你不用对每个类都调用 register() 方法了,而是可以直接自定义 issubclass 的行为。(这个类方法是在抽象基类的 __subclasscheck__() 方法中调用的。)

该方法必须返回 True, False 或是 NotImplemented。如果返回 Truesubclass 就会被认为是这个抽象基类的子类。如果返回 False,无论正常情况是否应该认为是其子类,统一视为不是。如果返回 NotImplemented,子类检查会按照正常机制继续执行。

为了对这些概念做一演示,请看以下定义 ABC 的示例:

class Foo:
    def __getitem__(self, index):
        ...
    def __len__(self):
        ...
    def get_iterator(self):
        return iter(self)

class MyIterable(metaclass=ABCMeta):

    @abstractmethod
    def __iter__(self):
        while False:
            yield None

    def get_iterator(self):
        return self.__iter__()

    @classmethod
    def __subclasshook__(cls, C):
        if cls is MyIterable:
            if any("__iter__" in B.__dict__ for B in C.__mro__):
                return True
        return NotImplemented

MyIterable.register(Foo)

ABC MyIterable 定义了标准的迭代方法 __iter__() 作为一个抽象方法。这里给出的实现仍可在子类中被调用。get_iterator() 方法也是 MyIterable 抽象基类的一部分,但它并非必须被非抽象派生类所重载。

这里定义的 __subclasshook__() 类方法指明了任何在其 __dict__ (或在其通过 __mro__ 列表访问的基类) 中具有 __iter__() 方法的类也都会被视为 MyIterable

最后,末尾行使得 Foo 成为 MyIterable 的一个虚子类,即使它没有定义 __iter__() 方法(它使用了以 __len__()__getitem__() 术语定义的旧式可迭代对象协议)。 请注意这将不会使 get_iterator 成为 Foo 的一个可用方法,它是被另外提供的。

class abc.ABC

A helper class that has ABCMeta as its metaclass. With this class, an abstract base class can be created by simply deriving from ABC, avoiding sometimes confusing metaclass usage.

Note that the type of ABC is still ABCMeta, therefore inheriting from ABC requires the usual precautions regarding metaclass usage, as multiple inheritance may lead to metaclass conflicts.

3.4 版新加入.

The abc module also provides the following decorators:

@abc.abstractmethod

用于声明抽象方法的装饰器。

使用此装饰器要求类的元类是 ABCMeta 或是从该类派生。一个具有派生自 ABCMeta 的元类的类不可以被实例化,除非它全部的抽象方法和特征属性均已被重载。抽象方法可通过任何普通的“super”调用机制来调用。 abstractmethod() 可被用于声明特性属性和描述器的抽象方法。

不支持动态添加抽象方法到一个类,或试图在方法或类被创建后修改其抽象状态等操作。 abstractmethod() 只会影响使用常规继承所派生的子类;通过 ABC 的 register() 方法注册的“虚子类”不会受到影响。

abstractmethod() 与其他方法描述符配合应用时,它应当被应用为最内层的装饰器,如以下用法示例所示:

class C(metaclass=ABCMeta):
    @abstractmethod
    def my_abstract_method(self, ...):
        ...
    @classmethod
    @abstractmethod
    def my_abstract_classmethod(cls, ...):
        ...
    @staticmethod
    @abstractmethod
    def my_abstract_staticmethod(...):
        ...

    @property
    @abstractmethod
    def my_abstract_property(self):
        ...
    @my_abstract_property.setter
    @abstractmethod
    def my_abstract_property(self, val):
        ...

    @abstractmethod
    def _get_x(self):
        ...
    @abstractmethod
    def _set_x(self, val):
        ...
    x = property(_get_x, _set_x)

In order to correctly interoperate with the abstract base class machinery, the descriptor must identify itself as abstract using __isabstractmethod__. In general, this attribute should be True if any of the methods used to compose the descriptor are abstract. For example, Python’s built-in property does the equivalent of:

class Descriptor:
    ...
    @property
    def __isabstractmethod__(self):
        return any(getattr(f, '__isabstractmethod__', False) for
                   f in (self._fget, self._fset, self._fdel))

備註

不同于 Java 抽象方法,这些抽象方法可能具有一个实现。 这个实现可在重载它的类上通过 super() 机制来调用。 这在使用协作多重继承的框架中可以被用作超调用的一个端点。

@abc.abstractclassmethod

内置 classmethod() 的子类,指明一个抽象类方法。 在其他情况下它都类似于 abstractmethod()

这个特殊情况已被弃用,因为现在 classmethod() 当将装饰器应用于抽象方法时它会被正确地标识为抽象的:

class C(metaclass=ABCMeta):
    @classmethod
    @abstractmethod
    def my_abstract_classmethod(cls, ...):
        ...

3.2 版新加入.

3.3 版後已棄用: 现在可以让 classmethod 配合 abstractmethod() 使用,使得此装饰器变得冗余。

@abc.abstractstaticmethod

内置 staticmethod() 的子类,指明一个抽象静态方法。 在其他方面它都类似于 abstractmethod()

这个特殊情况已被弃用,因为现在当 staticmethod() 装饰器应用于抽象方法时它会被正确地标识为抽象的:

class C(metaclass=ABCMeta):
    @staticmethod
    @abstractmethod
    def my_abstract_staticmethod(...):
        ...

3.2 版新加入.

3.3 版後已棄用: 现在可以让 staticmethod 配合 abstractmethod() 使用,使得此装饰器变得冗余。

@abc.abstractproperty(fget=None, fset=None, fdel=None, doc=None)

内置 property() 的子类,指明一个抽象特性属性。

Using this function requires that the class’s metaclass is ABCMeta or is derived from it. A class that has a metaclass derived from ABCMeta cannot be instantiated unless all of its abstract methods and properties are overridden. The abstract properties can be called using any of the normal 『super』 call mechanisms.

这个特例已被弃用,因为现在当 property() 装饰器应用于抽象方法时它会被正确地标识为抽象的:

class C(metaclass=ABCMeta):
    @property
    @abstractmethod
    def my_abstract_property(self):
        ...

上面的例子定义了一个只读特征属性;你也可以通过适当地将一个或多个下层方法标记为抽象的来定义可读写的抽象特征属性:

class C(metaclass=ABCMeta):
    @property
    def x(self):
        ...

    @x.setter
    @abstractmethod
    def x(self, val):
        ...

如果只有某些组件是抽象的,则只需更新那些组件即可在子类中创建具体的特征属性:

class D(C):
    @C.x.setter
    def x(self, val):
        ...

3.3 版後已棄用: 现在可以让 property, property.getter(), property.setter()property.deleter() 配合 abstractmethod() 使用,使得此装饰器变得冗余。

abc 模块还提供了这些函数:

abc.get_cache_token()

返回当前抽象基类的缓存令牌

此令牌是一个不透明对象(支持相等性测试),用于为虚子类标识抽象基类缓存的当前版本。 此令牌会在任何 ABC 上每次调用 ABCMeta.register() 时发生更改。

3.4 版新加入.

註解

[1]C++ 程序员需要注意:Python 中虚基类的概念和 C++ 中的并不相同。