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