| 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. |