Debian Codegraph @

Doc/library/abc.rst

raw
1 :mod:`!abc` --- Abstract Base Classes
2 =====================================
3
4 .. module:: abc
5 :synopsis: Abstract base classes according to :pep:`3119`.
6
7 .. moduleauthor:: Guido van Rossum
8 .. sectionauthor:: Georg Brandl
9 .. much of the content adapted from docstrings
10
11 **Source code:** :source:`Lib/abc.py`
12
13 --------------
14
15 This module provides the infrastructure for defining :term:`abstract base
16 classes <abstract base class>` (ABCs) in Python, as outlined in :pep:`3119`;
17 see the PEP for why this was added to Python. (See also :pep:`3141` and the
18 :mod:`numbers` module regarding a type hierarchy for numbers based on ABCs.)
19
20 The :mod:`collections` module has some concrete classes that derive from
21 ABCs; these can, of course, be further derived. In addition, the
22 :mod:`collections.abc` submodule has some ABCs that can be used to test whether
23 a class or instance provides a particular interface, for example, if it is
24 :term:`hashable` or if it is a :term:`mapping`.
25
26
27 This module provides the metaclass :class:`ABCMeta` for defining ABCs and
28 a helper class :class:`ABC` to alternatively define ABCs through inheritance:
29
30 .. class:: ABC
31
32 A helper class that has :class:`ABCMeta` as its metaclass. With this class,
33 an abstract base class can be created by simply deriving from :class:`!ABC`
34 avoiding sometimes confusing metaclass usage, for example::
35
36 from abc import ABC
37
38 class MyABC(ABC):
39 pass
40
41 Note that the type of :class:`!ABC` is still :class:`ABCMeta`, therefore
42 inheriting from :class:`!ABC` requires the usual precautions regarding
43 metaclass usage, as multiple inheritance may lead to metaclass conflicts.
44 One may also define an abstract base class by passing the metaclass
45 keyword and using :class:`!ABCMeta` directly, for example::
46
47 from abc import ABCMeta
48
49 class MyABC(metaclass=ABCMeta):
50 pass
51
52 .. versionadded:: 3.4
53
54
55 .. class:: ABCMeta
56
57 Metaclass for defining Abstract Base Classes (ABCs).
58
59 Use this metaclass to create an ABC. An ABC can be subclassed directly, and
60 then acts as a mix-in class. You can also register unrelated concrete
61 classes (even built-in classes) and unrelated ABCs as "virtual subclasses" --
62 these and their descendants will be considered subclasses of the registering
63 ABC by the built-in :func:`issubclass` function, but the registering ABC
64 won't show up in their MRO (Method Resolution Order) nor will method
65 implementations defined by the registering ABC be callable (not even via
66 :func:`super`). [#]_
67
68 Classes created with a metaclass of :class:`!ABCMeta` have the following method:
69
70 .. method:: register(subclass)
71
72 Register *subclass* as a "virtual subclass" of this ABC. For
73 example::
74
75 from abc import ABC
76
77 class MyABC(ABC):
78 pass
79
80 MyABC.register(tuple)
81
82 assert issubclass(tuple, MyABC)
83 assert isinstance((), MyABC)
84
85 .. versionchanged:: 3.3
86 Returns the registered subclass, to allow usage as a class decorator.
87
88 .. versionchanged:: 3.4
89 To detect calls to :meth:`!register`, you can use the
90 :func:`get_cache_token` function.
91
92 You can also override this method in an abstract base class:
93
94 .. method:: __subclasshook__(subclass)
95
96 (Must be defined as a class method.)
97
98 Check whether *subclass* is considered a subclass of this ABC. This means
99 that you can customize the behavior of :func:`issubclass` further without the
100 need to call :meth:`register` on every class you want to consider a
101 subclass of the ABC. (This class method is called from the
102 :meth:`~type.__subclasscheck__` method of the ABC.)
103
104 This method should return ``True``, ``False`` or :data:`NotImplemented`. If
105 it returns ``True``, the *subclass* is considered a subclass of this ABC.
106 If it returns ``False``, the *subclass* is not considered a subclass of
107 this ABC, even if it would normally be one. If it returns
108 :data:`!NotImplemented`, the subclass check is continued with the usual
109 mechanism.
110
111 .. XXX explain the "usual mechanism"
112
113
114 For a demonstration of these concepts, look at this example ABC definition::
115
116 class Foo:
117 def __getitem__(self, index):
118 ...
119 def __len__(self):
120 ...
121 def get_iterator(self):
122 return iter(self)
123
124 class MyIterable(ABC):
125
126 @abstractmethod
127 def __iter__(self):
128 while False:
129 yield None
130
131 def get_iterator(self):
132 return self.__iter__()
133
134 @classmethod
135 def __subclasshook__(cls, C):
136 if cls is MyIterable:
137 if any("__iter__" in B.__dict__ for B in C.__mro__):
138 return True
139 return NotImplemented
140
141 MyIterable.register(Foo)
142
143 The ABC ``MyIterable`` defines the standard iterable method,
144 :meth:`~object.__iter__`, as an abstract method. The implementation given
145 here can still be called from subclasses. The :meth:`!get_iterator` method
146 is also part of the ``MyIterable`` abstract base class, but it does not have
147 to be overridden in non-abstract derived classes.
148
149 The :meth:`__subclasshook__` class method defined here says that any class
150 that has an :meth:`~object.__iter__` method in its
151 :attr:`~object.__dict__` (or in that of one of its base classes, accessed
152 via the :attr:`~type.__mro__` list) is considered a ``MyIterable`` too.
153
154 Finally, the last line makes ``Foo`` a virtual subclass of ``MyIterable``,
155 even though it does not define an :meth:`~object.__iter__` method (it uses
156 the old-style iterable protocol, defined in terms of :meth:`~object.__len__` and
157 :meth:`~object.__getitem__`). Note that this will not make ``get_iterator``
158 available as a method of ``Foo``, so it is provided separately.
159
160
161
162
163 The :mod:`!abc` module also provides the following decorator:
164
165 .. decorator:: abstractmethod
166
167 A decorator indicating abstract methods.
168
169 Using this decorator requires that the class's metaclass is :class:`ABCMeta`
170 or is derived from it. A class that has a metaclass derived from
171 :class:`!ABCMeta` cannot be instantiated unless all of its abstract methods
172 and properties are overridden. The abstract methods can be called using any
173 of the normal 'super' call mechanisms. :func:`!abstractmethod` may be used
174 to declare abstract methods for properties and descriptors.
175
176 Dynamically adding abstract methods to a class, or attempting to modify the
177 abstraction status of a method or class once it is created, are only
178 supported using the :func:`update_abstractmethods` function. The
179 :func:`!abstractmethod` only affects subclasses derived using regular
180 inheritance; "virtual subclasses" registered with the ABC's
181 :meth:`~ABCMeta.register` method are not affected.
182
183 When :func:`!abstractmethod` is applied in combination with other method
184 descriptors, it should be applied as the innermost decorator, as shown in
185 the following usage examples::
186
187 class C(ABC):
188 @abstractmethod
189 def my_abstract_method(self, arg1):
190 ...
191 @classmethod
192 @abstractmethod
193 def my_abstract_classmethod(cls, arg2):
194 ...
195 @staticmethod
196 @abstractmethod
197 def my_abstract_staticmethod(arg3):
198 ...
199
200 @property
201 @abstractmethod
202 def my_abstract_property(self):
203 ...
204 @my_abstract_property.setter
205 @abstractmethod
206 def my_abstract_property(self, val):
207 ...
208
209 @abstractmethod
210 def _get_x(self):
211 ...
212 @abstractmethod
213 def _set_x(self, val):
214 ...
215 x = property(_get_x, _set_x)
216
217 In order to correctly interoperate with the abstract base class machinery,
218 the descriptor must identify itself as abstract using
219 :attr:`!__isabstractmethod__`. In general, this attribute should be ``True``
220 if any of the methods used to compose the descriptor are abstract. For
221 example, Python's built-in :class:`property` does the equivalent of::
222
223 class Descriptor:
224 ...
225 @property
226 def __isabstractmethod__(self):
227 return any(getattr(f, '__isabstractmethod__', False) for
228 f in (self._fget, self._fset, self._fdel))
229
230 .. note::
231
232 Unlike Java abstract methods, these abstract
233 methods may have an implementation. This implementation can be
234 called via the :func:`super` mechanism from the class that
235 overrides it. This could be useful as an end-point for a
236 super-call in a framework that uses cooperative
237 multiple-inheritance.
238
239 The :mod:`!abc` module also supports the following legacy decorators:
240
241 .. decorator:: abstractclassmethod
242
243 .. versionadded:: 3.2
244 .. deprecated:: 3.3
245 It is now possible to use :class:`classmethod` with
246 :func:`abstractmethod`, making this decorator redundant.
247
248 A subclass of the built-in :func:`classmethod`, indicating an abstract
249 classmethod. Otherwise it is similar to :func:`abstractmethod`.
250
251 This special case is deprecated, as the :func:`classmethod` decorator
252 is now correctly identified as abstract when applied to an abstract
253 method::
254
255 class C(ABC):
256 @classmethod
257 @abstractmethod
258 def my_abstract_classmethod(cls, arg):
259 ...
260
261
262 .. decorator:: abstractstaticmethod
263
264 .. versionadded:: 3.2
265 .. deprecated:: 3.3
266 It is now possible to use :class:`staticmethod` with
267 :func:`abstractmethod`, making this decorator redundant.
268
269 A subclass of the built-in :func:`staticmethod`, indicating an abstract
270 staticmethod. Otherwise it is similar to :func:`abstractmethod`.
271
272 This special case is deprecated, as the :func:`staticmethod` decorator
273 is now correctly identified as abstract when applied to an abstract
274 method::
275
276 class C(ABC):
277 @staticmethod
278 @abstractmethod
279 def my_abstract_staticmethod(arg):
280 ...
281
282
283 .. decorator:: abstractproperty
284
285 .. deprecated:: 3.3
286 It is now possible to use :class:`property`, :meth:`property.getter`,
287 :meth:`property.setter` and :meth:`property.deleter` with
288 :func:`abstractmethod`, making this decorator redundant.
289
290 A subclass of the built-in :func:`property`, indicating an abstract
291 property.
292
293 This special case is deprecated, as the :func:`property` decorator
294 is now correctly identified as abstract when applied to an abstract
295 method::
296
297 class C(ABC):
298 @property
299 @abstractmethod
300 def my_abstract_property(self):
301 ...
302
303 The above example defines a read-only property; you can also define a
304 read-write abstract property by appropriately marking one or more of the
305 underlying methods as abstract::
306
307 class C(ABC):
308 @property
309 def x(self):
310 ...
311
312 @x.setter
313 @abstractmethod
314 def x(self, val):
315 ...
316
317 If only some components are abstract, only those components need to be
318 updated to create a concrete property in a subclass::
319
320 class D(C):
321 @C.x.setter
322 def x(self, val):
323 ...
324
325
326 The :mod:`!abc` module also provides the following functions:
327
328 .. function:: get_cache_token()
329
330 Returns the current abstract base class cache token.
331
332 The token is an opaque object (that supports equality testing) identifying
333 the current version of the abstract base class cache for virtual subclasses.
334 The token changes with every call to :meth:`ABCMeta.register` on any ABC.
335
336 .. versionadded:: 3.4
337
338 .. function:: update_abstractmethods(cls)
339
340 A function to recalculate an abstract class's abstraction status. This
341 function should be called if a class's abstract methods have been
342 implemented or changed after it was created. Usually, this function should
343 be called from within a class decorator.
344
345 Returns *cls*, to allow usage as a class decorator.
346
347 If *cls* is not an instance of :class:`ABCMeta`, does nothing.
348
349 .. note::
350
351 This function assumes that *cls*'s superclasses are already updated.
352 It does not update any subclasses.
353
354 .. versionadded:: 3.10
355
356 .. rubric:: Footnotes
357
358 .. [#] C++ programmers should note that Python's virtual base class
359 concept is not the same as C++'s.