Éric Araujo | f90112e | 2011-06-03 19:18:41 +0200 | [diff] [blame] | 1 | .. _abstract-base-classes: |
| 2 | |
Georg Brandl | aeaa546 | 2007-09-04 08:11:03 +0000 | [diff] [blame] | 3 | :mod:`abc` --- Abstract Base Classes |
| 4 | ==================================== |
| 5 | |
| 6 | .. module:: abc |
| 7 | :synopsis: Abstract base classes according to PEP 3119. |
| 8 | .. moduleauthor:: Guido van Rossum |
| 9 | .. sectionauthor:: Georg Brandl |
| 10 | .. much of the content adapted from docstrings |
| 11 | |
Raymond Hettinger | ead4975 | 2011-01-24 16:28:06 +0000 | [diff] [blame] | 12 | **Source code:** :source:`Lib/abc.py` |
| 13 | |
| 14 | -------------- |
| 15 | |
Georg Brandl | 86b2fb9 | 2008-07-16 03:43:04 +0000 | [diff] [blame] | 16 | This module provides the infrastructure for defining an :term:`abstract base |
Éric Araujo | f90112e | 2011-06-03 19:18:41 +0200 | [diff] [blame] | 17 | class` (ABC) in Python, as outlined in :pep:`3119`; see the PEP for why this |
Benjamin Peterson | 4118174 | 2008-07-02 20:22:54 +0000 | [diff] [blame] | 18 | was added to Python. (See also :pep:`3141` and the :mod:`numbers` module |
| 19 | regarding a type hierarchy for numbers based on ABCs.) |
Georg Brandl | aeaa546 | 2007-09-04 08:11:03 +0000 | [diff] [blame] | 20 | |
Mark Summerfield | 08898b4 | 2007-09-05 08:43:04 +0000 | [diff] [blame] | 21 | The :mod:`collections` module has some concrete classes that derive from |
| 22 | ABCs; these can, of course, be further derived. In addition the |
Éric Araujo | 3622680 | 2011-06-03 20:49:39 +0200 | [diff] [blame^] | 23 | :mod:`collections.abc` submodule has some ABCs that can be used to test whether |
Mark Summerfield | 08898b4 | 2007-09-05 08:43:04 +0000 | [diff] [blame] | 24 | a class or instance provides a particular interface, for example, is it |
| 25 | hashable or a mapping. |
Georg Brandl | aeaa546 | 2007-09-04 08:11:03 +0000 | [diff] [blame] | 26 | |
| 27 | |
Mark Summerfield | 08898b4 | 2007-09-05 08:43:04 +0000 | [diff] [blame] | 28 | This module provides the following class: |
Georg Brandl | aeaa546 | 2007-09-04 08:11:03 +0000 | [diff] [blame] | 29 | |
| 30 | .. class:: ABCMeta |
| 31 | |
| 32 | Metaclass for defining Abstract Base Classes (ABCs). |
| 33 | |
| 34 | Use this metaclass to create an ABC. An ABC can be subclassed directly, and |
| 35 | then acts as a mix-in class. You can also register unrelated concrete |
| 36 | classes (even built-in classes) and unrelated ABCs as "virtual subclasses" -- |
| 37 | these and their descendants will be considered subclasses of the registering |
| 38 | ABC by the built-in :func:`issubclass` function, but the registering ABC |
| 39 | won't show up in their MRO (Method Resolution Order) nor will method |
| 40 | implementations defined by the registering ABC be callable (not even via |
Mark Summerfield | 08898b4 | 2007-09-05 08:43:04 +0000 | [diff] [blame] | 41 | :func:`super`). [#]_ |
Georg Brandl | aeaa546 | 2007-09-04 08:11:03 +0000 | [diff] [blame] | 42 | |
| 43 | Classes created with a metaclass of :class:`ABCMeta` have the following method: |
| 44 | |
| 45 | .. method:: register(subclass) |
| 46 | |
Mark Summerfield | 08898b4 | 2007-09-05 08:43:04 +0000 | [diff] [blame] | 47 | Register *subclass* as a "virtual subclass" of this ABC. For |
| 48 | example:: |
Georg Brandl | aeaa546 | 2007-09-04 08:11:03 +0000 | [diff] [blame] | 49 | |
Georg Brandl | a1c6a1c | 2009-01-03 21:26:05 +0000 | [diff] [blame] | 50 | from abc import ABCMeta |
Mark Summerfield | 08898b4 | 2007-09-05 08:43:04 +0000 | [diff] [blame] | 51 | |
Georg Brandl | a1c6a1c | 2009-01-03 21:26:05 +0000 | [diff] [blame] | 52 | class MyABC(metaclass=ABCMeta): |
| 53 | pass |
Mark Summerfield | 08898b4 | 2007-09-05 08:43:04 +0000 | [diff] [blame] | 54 | |
Georg Brandl | a1c6a1c | 2009-01-03 21:26:05 +0000 | [diff] [blame] | 55 | MyABC.register(tuple) |
Mark Summerfield | 08898b4 | 2007-09-05 08:43:04 +0000 | [diff] [blame] | 56 | |
Georg Brandl | a1c6a1c | 2009-01-03 21:26:05 +0000 | [diff] [blame] | 57 | assert issubclass(tuple, MyABC) |
| 58 | assert isinstance((), MyABC) |
Georg Brandl | aeaa546 | 2007-09-04 08:11:03 +0000 | [diff] [blame] | 59 | |
Éric Araujo | 6c3787c | 2011-02-24 18:03:10 +0000 | [diff] [blame] | 60 | .. versionchanged:: 3.3 |
| 61 | Returns the registered subclass, to allow usage as a class decorator. |
| 62 | |
Georg Brandl | aeaa546 | 2007-09-04 08:11:03 +0000 | [diff] [blame] | 63 | You can also override this method in an abstract base class: |
| 64 | |
| 65 | .. method:: __subclasshook__(subclass) |
| 66 | |
| 67 | (Must be defined as a class method.) |
| 68 | |
| 69 | Check whether *subclass* is considered a subclass of this ABC. This means |
| 70 | that you can customize the behavior of ``issubclass`` further without the |
| 71 | need to call :meth:`register` on every class you want to consider a |
Georg Brandl | 2d14098 | 2007-09-04 15:45:25 +0000 | [diff] [blame] | 72 | subclass of the ABC. (This class method is called from the |
| 73 | :meth:`__subclasscheck__` method of the ABC.) |
Georg Brandl | aeaa546 | 2007-09-04 08:11:03 +0000 | [diff] [blame] | 74 | |
| 75 | This method should return ``True``, ``False`` or ``NotImplemented``. If |
| 76 | it returns ``True``, the *subclass* is considered a subclass of this ABC. |
| 77 | If it returns ``False``, the *subclass* is not considered a subclass of |
| 78 | this ABC, even if it would normally be one. If it returns |
| 79 | ``NotImplemented``, the subclass check is continued with the usual |
| 80 | mechanism. |
| 81 | |
Georg Brandl | 2d14098 | 2007-09-04 15:45:25 +0000 | [diff] [blame] | 82 | .. XXX explain the "usual mechanism" |
Georg Brandl | aeaa546 | 2007-09-04 08:11:03 +0000 | [diff] [blame] | 83 | |
Georg Brandl | aeaa546 | 2007-09-04 08:11:03 +0000 | [diff] [blame] | 84 | |
Georg Brandl | 2d14098 | 2007-09-04 15:45:25 +0000 | [diff] [blame] | 85 | For a demonstration of these concepts, look at this example ABC definition:: |
Georg Brandl | aeaa546 | 2007-09-04 08:11:03 +0000 | [diff] [blame] | 86 | |
Georg Brandl | 2d14098 | 2007-09-04 15:45:25 +0000 | [diff] [blame] | 87 | class Foo: |
| 88 | def __getitem__(self, index): |
| 89 | ... |
| 90 | def __len__(self): |
| 91 | ... |
| 92 | def get_iterator(self): |
| 93 | return iter(self) |
| 94 | |
| 95 | class MyIterable(metaclass=ABCMeta): |
Georg Brandl | aeaa546 | 2007-09-04 08:11:03 +0000 | [diff] [blame] | 96 | |
| 97 | @abstractmethod |
Georg Brandl | aeaa546 | 2007-09-04 08:11:03 +0000 | [diff] [blame] | 98 | def __iter__(self): |
Georg Brandl | 2d14098 | 2007-09-04 15:45:25 +0000 | [diff] [blame] | 99 | while False: |
| 100 | yield None |
| 101 | |
| 102 | def get_iterator(self): |
| 103 | return self.__iter__() |
Georg Brandl | aeaa546 | 2007-09-04 08:11:03 +0000 | [diff] [blame] | 104 | |
| 105 | @classmethod |
| 106 | def __subclasshook__(cls, C): |
Georg Brandl | 2d14098 | 2007-09-04 15:45:25 +0000 | [diff] [blame] | 107 | if cls is MyIterable: |
| 108 | if any("__iter__" in B.__dict__ for B in C.__mro__): |
Georg Brandl | aeaa546 | 2007-09-04 08:11:03 +0000 | [diff] [blame] | 109 | return True |
| 110 | return NotImplemented |
| 111 | |
Georg Brandl | 2d14098 | 2007-09-04 15:45:25 +0000 | [diff] [blame] | 112 | MyIterable.register(Foo) |
Georg Brandl | aeaa546 | 2007-09-04 08:11:03 +0000 | [diff] [blame] | 113 | |
Georg Brandl | 2d14098 | 2007-09-04 15:45:25 +0000 | [diff] [blame] | 114 | The ABC ``MyIterable`` defines the standard iterable method, |
| 115 | :meth:`__iter__`, as an abstract method. The implementation given here can |
| 116 | still be called from subclasses. The :meth:`get_iterator` method is also |
| 117 | part of the ``MyIterable`` abstract base class, but it does not have to be |
Mark Summerfield | 08898b4 | 2007-09-05 08:43:04 +0000 | [diff] [blame] | 118 | overridden in non-abstract derived classes. |
Georg Brandl | aeaa546 | 2007-09-04 08:11:03 +0000 | [diff] [blame] | 119 | |
| 120 | The :meth:`__subclasshook__` class method defined here says that any class |
Georg Brandl | 2d14098 | 2007-09-04 15:45:25 +0000 | [diff] [blame] | 121 | that has an :meth:`__iter__` method in its :attr:`__dict__` (or in that of |
Mark Summerfield | 08898b4 | 2007-09-05 08:43:04 +0000 | [diff] [blame] | 122 | one of its base classes, accessed via the :attr:`__mro__` list) is |
| 123 | considered a ``MyIterable`` too. |
Georg Brandl | aeaa546 | 2007-09-04 08:11:03 +0000 | [diff] [blame] | 124 | |
Georg Brandl | 2d14098 | 2007-09-04 15:45:25 +0000 | [diff] [blame] | 125 | Finally, the last line makes ``Foo`` a virtual subclass of ``MyIterable``, |
Mark Summerfield | 08898b4 | 2007-09-05 08:43:04 +0000 | [diff] [blame] | 126 | even though it does not define an :meth:`__iter__` method (it uses the |
Georg Brandl | 2d14098 | 2007-09-04 15:45:25 +0000 | [diff] [blame] | 127 | old-style iterable protocol, defined in terms of :meth:`__len__` and |
| 128 | :meth:`__getitem__`). Note that this will not make ``get_iterator`` |
| 129 | available as a method of ``Foo``, so it is provided separately. |
Georg Brandl | aeaa546 | 2007-09-04 08:11:03 +0000 | [diff] [blame] | 130 | |
| 131 | |
| 132 | It also provides the following decorators: |
| 133 | |
Georg Brandl | 8a1caa2 | 2010-07-29 16:01:11 +0000 | [diff] [blame] | 134 | .. decorator:: abstractmethod(function) |
Georg Brandl | aeaa546 | 2007-09-04 08:11:03 +0000 | [diff] [blame] | 135 | |
| 136 | A decorator indicating abstract methods. |
| 137 | |
Mark Summerfield | 08898b4 | 2007-09-05 08:43:04 +0000 | [diff] [blame] | 138 | Using this decorator requires that the class's metaclass is :class:`ABCMeta` or |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 139 | is derived from it. |
Mark Summerfield | 08898b4 | 2007-09-05 08:43:04 +0000 | [diff] [blame] | 140 | A class that has a metaclass derived from :class:`ABCMeta` |
| 141 | cannot be instantiated unless all of its abstract methods and |
| 142 | properties are overridden. |
Benjamin Peterson | d23f822 | 2009-04-05 19:13:16 +0000 | [diff] [blame] | 143 | The abstract methods can be called using any of the normal 'super' call |
Georg Brandl | 2d14098 | 2007-09-04 15:45:25 +0000 | [diff] [blame] | 144 | mechanisms. |
| 145 | |
| 146 | Dynamically adding abstract methods to a class, or attempting to modify the |
| 147 | abstraction status of a method or class once it is created, are not |
| 148 | supported. The :func:`abstractmethod` only affects subclasses derived using |
| 149 | regular inheritance; "virtual subclasses" registered with the ABC's |
| 150 | :meth:`register` method are not affected. |
Georg Brandl | aeaa546 | 2007-09-04 08:11:03 +0000 | [diff] [blame] | 151 | |
| 152 | Usage:: |
| 153 | |
| 154 | class C(metaclass=ABCMeta): |
| 155 | @abstractmethod |
| 156 | def my_abstract_method(self, ...): |
| 157 | ... |
| 158 | |
Georg Brandl | 2d14098 | 2007-09-04 15:45:25 +0000 | [diff] [blame] | 159 | .. note:: |
Georg Brandl | aeaa546 | 2007-09-04 08:11:03 +0000 | [diff] [blame] | 160 | |
Benjamin Peterson | ad3d5c2 | 2009-02-26 03:38:59 +0000 | [diff] [blame] | 161 | Unlike Java abstract methods, these abstract |
Mark Summerfield | 08898b4 | 2007-09-05 08:43:04 +0000 | [diff] [blame] | 162 | methods may have an implementation. This implementation can be |
| 163 | called via the :func:`super` mechanism from the class that |
| 164 | overrides it. This could be useful as an end-point for a |
| 165 | super-call in a framework that uses cooperative |
| 166 | multiple-inheritance. |
Georg Brandl | aeaa546 | 2007-09-04 08:11:03 +0000 | [diff] [blame] | 167 | |
Georg Brandl | 2d14098 | 2007-09-04 15:45:25 +0000 | [diff] [blame] | 168 | |
Benjamin Peterson | 45c257f | 2010-08-17 00:52:52 +0000 | [diff] [blame] | 169 | .. decorator:: abstractclassmethod(function) |
| 170 | |
| 171 | A subclass of the built-in :func:`classmethod`, indicating an abstract |
| 172 | classmethod. Otherwise it is similar to :func:`abstractmethod`. |
| 173 | |
| 174 | Usage:: |
| 175 | |
| 176 | class C(metaclass=ABCMeta): |
| 177 | @abstractclassmethod |
| 178 | def my_abstract_classmethod(cls, ...): |
| 179 | ... |
| 180 | |
Benjamin Peterson | ad1e0c5 | 2010-08-17 03:37:20 +0000 | [diff] [blame] | 181 | .. versionadded:: 3.2 |
| 182 | |
Benjamin Peterson | 45c257f | 2010-08-17 00:52:52 +0000 | [diff] [blame] | 183 | |
| 184 | .. decorator:: abstractstaticmethod(function) |
| 185 | |
| 186 | A subclass of the built-in :func:`staticmethod`, indicating an abstract |
| 187 | staticmethod. Otherwise it is similar to :func:`abstractmethod`. |
| 188 | |
| 189 | Usage:: |
| 190 | |
| 191 | class C(metaclass=ABCMeta): |
| 192 | @abstractstaticmethod |
| 193 | def my_abstract_staticmethod(...): |
| 194 | ... |
| 195 | |
Benjamin Peterson | ad1e0c5 | 2010-08-17 03:37:20 +0000 | [diff] [blame] | 196 | .. versionadded:: 3.2 |
| 197 | |
Benjamin Peterson | 45c257f | 2010-08-17 00:52:52 +0000 | [diff] [blame] | 198 | |
Georg Brandl | b868a66 | 2009-04-02 02:56:10 +0000 | [diff] [blame] | 199 | .. function:: abstractproperty(fget=None, fset=None, fdel=None, doc=None) |
Georg Brandl | 2d14098 | 2007-09-04 15:45:25 +0000 | [diff] [blame] | 200 | |
| 201 | A subclass of the built-in :func:`property`, indicating an abstract property. |
Georg Brandl | aeaa546 | 2007-09-04 08:11:03 +0000 | [diff] [blame] | 202 | |
Mark Summerfield | 08898b4 | 2007-09-05 08:43:04 +0000 | [diff] [blame] | 203 | Using this function requires that the class's metaclass is :class:`ABCMeta` or |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 204 | is derived from it. |
Mark Summerfield | 08898b4 | 2007-09-05 08:43:04 +0000 | [diff] [blame] | 205 | A class that has a metaclass derived from :class:`ABCMeta` cannot be |
| 206 | instantiated unless all of its abstract methods and properties are overridden. |
| 207 | The abstract properties can be called using any of the normal |
| 208 | 'super' call mechanisms. |
Georg Brandl | aeaa546 | 2007-09-04 08:11:03 +0000 | [diff] [blame] | 209 | |
| 210 | Usage:: |
| 211 | |
| 212 | class C(metaclass=ABCMeta): |
| 213 | @abstractproperty |
| 214 | def my_abstract_property(self): |
| 215 | ... |
| 216 | |
| 217 | This defines a read-only property; you can also define a read-write abstract |
| 218 | property using the 'long' form of property declaration:: |
| 219 | |
| 220 | class C(metaclass=ABCMeta): |
| 221 | def getx(self): ... |
| 222 | def setx(self, value): ... |
| 223 | x = abstractproperty(getx, setx) |
| 224 | |
Benjamin Peterson | d23f822 | 2009-04-05 19:13:16 +0000 | [diff] [blame] | 225 | |
Mark Summerfield | 08898b4 | 2007-09-05 08:43:04 +0000 | [diff] [blame] | 226 | .. rubric:: Footnotes |
| 227 | |
| 228 | .. [#] C++ programmers should note that Python's virtual base class |
| 229 | concept is not the same as C++'s. |