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 15This module provides the infrastructure for defining :term:`abstract base 16classes <abstract base class>` (ABCs) in Python, as outlined in :pep:`3119`; 17see 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 20The :mod:`collections` module has some concrete classes that derive from 21ABCs; 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 23a class or instance provides a particular interface, for example, if it is 24hashable or if it is a mapping. 25 26 27This module provides the metaclass :class:`ABCMeta` for defining ABCs and 28a 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 ``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:`__subclasscheck__` method of the ABC.) 103 104 This method should return ``True``, ``False`` or ``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 ``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:`~iterator.__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:`~iterator.__iter__` method in its 151 :attr:`~object.__dict__` (or in that of one of its base classes, accessed 152 via the :attr:`~class.__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:`~iterator.__iter__` method (it uses 156 the old-style iterable protocol, defined in terms of :meth:`__len__` and 157 :meth:`__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 163The :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 :meth:`register` 181 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, ...): 190 ... 191 @classmethod 192 @abstractmethod 193 def my_abstract_classmethod(cls, ...): 194 ... 195 @staticmethod 196 @abstractmethod 197 def my_abstract_staticmethod(...): 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 239The :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, ...): 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(...): 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 326The :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. 360