1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
|
:mod:`abc` --- Abstract Base Classes
====================================
.. module:: abc
:synopsis: Abstract base classes according to PEP 3119.
.. moduleauthor:: Guido van Rossum
.. sectionauthor:: Georg Brandl
.. much of the content adapted from docstrings
This module provides the infrastructure for defining abstract base classes
(ABCs) in Python, as outlined in :pep:`3119`.
Concrete base ABCs to derive from can be found in the :mod:`collections` module.
The module provides the following class:
.. class:: ABCMeta
Metaclass for defining Abstract Base Classes (ABCs).
Use this metaclass to create an ABC. An ABC can be subclassed directly, and
then acts as a mix-in class. You can also register unrelated concrete
classes (even built-in classes) and unrelated ABCs as "virtual subclasses" --
these and their descendants will be considered subclasses of the registering
ABC by the built-in :func:`issubclass` function, but the registering ABC
won't show up in their MRO (Method Resolution Order) nor will method
implementations defined by the registering ABC be callable (not even via
:func:`super`).
Classes created with a metaclass of :class:`ABCMeta` have the following method:
.. method:: register(subclass)
Register *subclass* as a "virtual subclass" of this ABC. From now on,
``issubclass(subclass, ABC)`` is true.
You can also override this method in an abstract base class:
.. method:: __subclasshook__(subclass)
(Must be defined as a class method.)
Check whether *subclass* is considered a subclass of this ABC. This means
that you can customize the behavior of ``issubclass`` further without the
need to call :meth:`register` on every class you want to consider a
subclass of the ABC.
This method should return ``True``, ``False`` or ``NotImplemented``. If
it returns ``True``, the *subclass* is considered a subclass of this ABC.
If it returns ``False``, the *subclass* is not considered a subclass of
this ABC, even if it would normally be one. If it returns
``NotImplemented``, the subclass check is continued with the usual
mechanism.
To demonstrate these concepts, look at this example ABC definition::
class MyIterator:
pass
class Iterator(metaclass=ABCMeta):
@abstractmethod
def __next__(self):
raise StopIteration
def __iter__(self):
return self
@classmethod
def __subclasshook__(cls, C):
if cls is Iterator:
if any("__next__" in B.__dict__ for B in C.__mro__):
return True
return NotImplemented
Iterator.register(MyIterator)
The ABC ``Iterator`` defines the two standard iterator methods:
:meth:`__iter__` and :meth:`__next__`. The :meth:`__iter__` method is given
a default implementation, while the :meth:`__next__` method is abstract.
.. XXX why is an implementation given then?
The :meth:`__subclasshook__` class method defined here says that any class
that has a :meth:`__next__` method in its :attr:`__dict__` (or in that of one
of its subclasses, accessed via the :attr:`__mro__`) is considered an
``Iterator`` too.
Finally, the last line makes ``MyIterator`` a virtual subclass of
``Iterator``, even though it does not define a :meth:`__next__` method.
(Of course, this doesn't make much sense in this context.)
.. XXX perhaps find better example
It also provides the following decorators:
.. function:: abstractmethod(function)
A decorator indicating abstract methods.
Requires that the metaclass is :class:`ABCMeta` or derived from it. A class
that has a metaclass derived from :class:`ABCMeta` cannot be instantiated
unless all of its abstract methods are overridden. The abstract methods can
be called using any of the the normal 'super' call mechanisms.
Usage::
class C(metaclass=ABCMeta):
@abstractmethod
def my_abstract_method(self, ...):
...
.. function:: abstractproperty(property)
A decorator indicating abstract properties.
Requires that the metaclass is :class:`ABCMeta` or derived from it. A class
that has a metaclass derived from :class:`ABCMeta` cannot be instantiated
unless all of its abstract properties are overridden. The abstract
properties can be called using any of the the normal 'super' call mechanisms.
Usage::
class C(metaclass=ABCMeta):
@abstractproperty
def my_abstract_property(self):
...
This defines a read-only property; you can also define a read-write abstract
property using the 'long' form of property declaration::
class C(metaclass=ABCMeta):
def getx(self): ...
def setx(self, value): ...
x = abstractproperty(getx, setx)
|
