Georg Brandl | aeaa546 | 2007-09-04 08:11:03 +0000 | [diff] [blame] | 1 | |
| 2 | :mod:`abc` --- Abstract Base Classes |
| 3 | ==================================== |
| 4 | |
| 5 | .. module:: abc |
| 6 | :synopsis: Abstract base classes according to PEP 3119. |
| 7 | .. moduleauthor:: Guido van Rossum |
| 8 | .. sectionauthor:: Georg Brandl |
| 9 | .. much of the content adapted from docstrings |
| 10 | |
| 11 | This module provides the infrastructure for defining abstract base classes |
Georg Brandl | 2d14098 | 2007-09-04 15:45:25 +0000 | [diff] [blame^] | 12 | (ABCs) in Python, as outlined in :pep:`3119`; see there for a rationale why this |
| 13 | was added to Python. |
Georg Brandl | aeaa546 | 2007-09-04 08:11:03 +0000 | [diff] [blame] | 14 | |
| 15 | Concrete base ABCs to derive from can be found in the :mod:`collections` module. |
| 16 | |
| 17 | |
| 18 | The module provides the following class: |
| 19 | |
| 20 | .. class:: ABCMeta |
| 21 | |
| 22 | Metaclass for defining Abstract Base Classes (ABCs). |
| 23 | |
| 24 | Use this metaclass to create an ABC. An ABC can be subclassed directly, and |
| 25 | then acts as a mix-in class. You can also register unrelated concrete |
| 26 | classes (even built-in classes) and unrelated ABCs as "virtual subclasses" -- |
| 27 | these and their descendants will be considered subclasses of the registering |
| 28 | ABC by the built-in :func:`issubclass` function, but the registering ABC |
| 29 | won't show up in their MRO (Method Resolution Order) nor will method |
| 30 | implementations defined by the registering ABC be callable (not even via |
| 31 | :func:`super`). |
| 32 | |
| 33 | Classes created with a metaclass of :class:`ABCMeta` have the following method: |
| 34 | |
| 35 | .. method:: register(subclass) |
| 36 | |
| 37 | Register *subclass* as a "virtual subclass" of this ABC. From now on, |
| 38 | ``issubclass(subclass, ABC)`` is true. |
| 39 | |
| 40 | |
| 41 | You can also override this method in an abstract base class: |
| 42 | |
| 43 | .. method:: __subclasshook__(subclass) |
| 44 | |
| 45 | (Must be defined as a class method.) |
| 46 | |
| 47 | Check whether *subclass* is considered a subclass of this ABC. This means |
| 48 | that you can customize the behavior of ``issubclass`` further without the |
| 49 | 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^] | 50 | subclass of the ABC. (This class method is called from the |
| 51 | :meth:`__subclasscheck__` method of the ABC.) |
Georg Brandl | aeaa546 | 2007-09-04 08:11:03 +0000 | [diff] [blame] | 52 | |
| 53 | This method should return ``True``, ``False`` or ``NotImplemented``. If |
| 54 | it returns ``True``, the *subclass* is considered a subclass of this ABC. |
| 55 | If it returns ``False``, the *subclass* is not considered a subclass of |
| 56 | this ABC, even if it would normally be one. If it returns |
| 57 | ``NotImplemented``, the subclass check is continued with the usual |
| 58 | mechanism. |
| 59 | |
Georg Brandl | 2d14098 | 2007-09-04 15:45:25 +0000 | [diff] [blame^] | 60 | .. XXX explain the "usual mechanism" |
Georg Brandl | aeaa546 | 2007-09-04 08:11:03 +0000 | [diff] [blame] | 61 | |
Georg Brandl | aeaa546 | 2007-09-04 08:11:03 +0000 | [diff] [blame] | 62 | |
Georg Brandl | 2d14098 | 2007-09-04 15:45:25 +0000 | [diff] [blame^] | 63 | For a demonstration of these concepts, look at this example ABC definition:: |
Georg Brandl | aeaa546 | 2007-09-04 08:11:03 +0000 | [diff] [blame] | 64 | |
Georg Brandl | 2d14098 | 2007-09-04 15:45:25 +0000 | [diff] [blame^] | 65 | class Foo: |
| 66 | def __getitem__(self, index): |
| 67 | ... |
| 68 | def __len__(self): |
| 69 | ... |
| 70 | def get_iterator(self): |
| 71 | return iter(self) |
| 72 | |
| 73 | class MyIterable(metaclass=ABCMeta): |
Georg Brandl | aeaa546 | 2007-09-04 08:11:03 +0000 | [diff] [blame] | 74 | |
| 75 | @abstractmethod |
Georg Brandl | aeaa546 | 2007-09-04 08:11:03 +0000 | [diff] [blame] | 76 | def __iter__(self): |
Georg Brandl | 2d14098 | 2007-09-04 15:45:25 +0000 | [diff] [blame^] | 77 | while False: |
| 78 | yield None |
| 79 | |
| 80 | def get_iterator(self): |
| 81 | return self.__iter__() |
Georg Brandl | aeaa546 | 2007-09-04 08:11:03 +0000 | [diff] [blame] | 82 | |
| 83 | @classmethod |
| 84 | def __subclasshook__(cls, C): |
Georg Brandl | 2d14098 | 2007-09-04 15:45:25 +0000 | [diff] [blame^] | 85 | if cls is MyIterable: |
| 86 | if any("__iter__" in B.__dict__ for B in C.__mro__): |
Georg Brandl | aeaa546 | 2007-09-04 08:11:03 +0000 | [diff] [blame] | 87 | return True |
| 88 | return NotImplemented |
| 89 | |
Georg Brandl | 2d14098 | 2007-09-04 15:45:25 +0000 | [diff] [blame^] | 90 | MyIterable.register(Foo) |
Georg Brandl | aeaa546 | 2007-09-04 08:11:03 +0000 | [diff] [blame] | 91 | |
Georg Brandl | 2d14098 | 2007-09-04 15:45:25 +0000 | [diff] [blame^] | 92 | The ABC ``MyIterable`` defines the standard iterable method, |
| 93 | :meth:`__iter__`, as an abstract method. The implementation given here can |
| 94 | still be called from subclasses. The :meth:`get_iterator` method is also |
| 95 | part of the ``MyIterable`` abstract base class, but it does not have to be |
| 96 | overridden in a non-abstract child. |
Georg Brandl | aeaa546 | 2007-09-04 08:11:03 +0000 | [diff] [blame] | 97 | |
| 98 | The :meth:`__subclasshook__` class method defined here says that any class |
Georg Brandl | 2d14098 | 2007-09-04 15:45:25 +0000 | [diff] [blame^] | 99 | that has an :meth:`__iter__` method in its :attr:`__dict__` (or in that of |
| 100 | one of its subclasses, accessed via the :attr:`__mro__`) is considered a |
| 101 | ``MyIterable`` too. |
Georg Brandl | aeaa546 | 2007-09-04 08:11:03 +0000 | [diff] [blame] | 102 | |
Georg Brandl | 2d14098 | 2007-09-04 15:45:25 +0000 | [diff] [blame^] | 103 | Finally, the last line makes ``Foo`` a virtual subclass of ``MyIterable``, |
| 104 | even though it does not define a :meth:`__iter__` method (it uses the |
| 105 | old-style iterable protocol, defined in terms of :meth:`__len__` and |
| 106 | :meth:`__getitem__`). Note that this will not make ``get_iterator`` |
| 107 | available as a method of ``Foo``, so it is provided separately. |
Georg Brandl | aeaa546 | 2007-09-04 08:11:03 +0000 | [diff] [blame] | 108 | |
| 109 | |
| 110 | It also provides the following decorators: |
| 111 | |
| 112 | .. function:: abstractmethod(function) |
| 113 | |
| 114 | A decorator indicating abstract methods. |
| 115 | |
Georg Brandl | 2d14098 | 2007-09-04 15:45:25 +0000 | [diff] [blame^] | 116 | Using this decorator requires that the metaclass is :class:`ABCMeta` or |
| 117 | derived from it. A class that has a metaclass derived from :class:`ABCMeta` |
| 118 | cannot be instantiated unless all of its abstract methods are overridden. |
| 119 | The abstract methods can be called using any of the the normal 'super' call |
| 120 | mechanisms. |
| 121 | |
| 122 | Dynamically adding abstract methods to a class, or attempting to modify the |
| 123 | abstraction status of a method or class once it is created, are not |
| 124 | supported. The :func:`abstractmethod` only affects subclasses derived using |
| 125 | regular inheritance; "virtual subclasses" registered with the ABC's |
| 126 | :meth:`register` method are not affected. |
Georg Brandl | aeaa546 | 2007-09-04 08:11:03 +0000 | [diff] [blame] | 127 | |
| 128 | Usage:: |
| 129 | |
| 130 | class C(metaclass=ABCMeta): |
| 131 | @abstractmethod |
| 132 | def my_abstract_method(self, ...): |
| 133 | ... |
| 134 | |
Georg Brandl | 2d14098 | 2007-09-04 15:45:25 +0000 | [diff] [blame^] | 135 | .. note:: |
Georg Brandl | aeaa546 | 2007-09-04 08:11:03 +0000 | [diff] [blame] | 136 | |
Georg Brandl | 2d14098 | 2007-09-04 15:45:25 +0000 | [diff] [blame^] | 137 | Unlike C++ or Java, these abstract methods may have an implementation. |
| 138 | This implementation can be called via the :func:`super` mechanism from the |
| 139 | class that overrides it. This could be useful as an end-point for a |
| 140 | super-call in framework using a cooperative multiple-inheritance |
Georg Brandl | aeaa546 | 2007-09-04 08:11:03 +0000 | [diff] [blame] | 141 | |
Georg Brandl | 2d14098 | 2007-09-04 15:45:25 +0000 | [diff] [blame^] | 142 | |
| 143 | .. function:: abstractproperty(fget[, fset[, fdel[, doc]]]) |
| 144 | |
| 145 | A subclass of the built-in :func:`property`, indicating an abstract property. |
Georg Brandl | aeaa546 | 2007-09-04 08:11:03 +0000 | [diff] [blame] | 146 | |
| 147 | Requires that the metaclass is :class:`ABCMeta` or derived from it. A class |
| 148 | that has a metaclass derived from :class:`ABCMeta` cannot be instantiated |
| 149 | unless all of its abstract properties are overridden. The abstract |
| 150 | properties can be called using any of the the normal 'super' call mechanisms. |
| 151 | |
| 152 | Usage:: |
| 153 | |
| 154 | class C(metaclass=ABCMeta): |
| 155 | @abstractproperty |
| 156 | def my_abstract_property(self): |
| 157 | ... |
| 158 | |
| 159 | This defines a read-only property; you can also define a read-write abstract |
| 160 | property using the 'long' form of property declaration:: |
| 161 | |
| 162 | class C(metaclass=ABCMeta): |
| 163 | def getx(self): ... |
| 164 | def setx(self, value): ... |
| 165 | x = abstractproperty(getx, setx) |
| 166 | |