diff options
| -rw-r--r-- | Doc/library/abc.rst | 142 | ||||
| -rw-r--r-- | Doc/library/python.rst | 1 |
2 files changed, 143 insertions, 0 deletions
diff --git a/Doc/library/abc.rst b/Doc/library/abc.rst new file mode 100644 index 0000000..6870603 --- /dev/null +++ b/Doc/library/abc.rst @@ -0,0 +1,142 @@ + +:mod:`abc` --- Abstract Base Classes +==================================== + +.. module:: abc + :synopsis: Abstract base classes according to PEP 3119. +.. moduleauthor:: Guido van Rossum +.. sectionauthor:: Georg Brandl +.. much of the content adapted from docstrings + +This module provides the infrastructure for defining abstract base classes +(ABCs) in Python, as outlined in :pep:`3119`. + +Concrete base ABCs to derive from can be found in the :mod:`collections` module. + + +The module provides the following class: + +.. class:: ABCMeta + + Metaclass for defining Abstract Base Classes (ABCs). + + Use this metaclass to create an ABC. An ABC can be subclassed directly, and + then acts as a mix-in class. You can also register unrelated concrete + classes (even built-in classes) and unrelated ABCs as "virtual subclasses" -- + these and their descendants will be considered subclasses of the registering + ABC by the built-in :func:`issubclass` function, but the registering ABC + won't show up in their MRO (Method Resolution Order) nor will method + implementations defined by the registering ABC be callable (not even via + :func:`super`). + + Classes created with a metaclass of :class:`ABCMeta` have the following method: + + .. method:: register(subclass) + + Register *subclass* as a "virtual subclass" of this ABC. From now on, + ``issubclass(subclass, ABC)`` is true. + + + You can also override this method in an abstract base class: + + .. method:: __subclasshook__(subclass) + + (Must be defined as a class method.) + + Check whether *subclass* is considered a subclass of this ABC. This means + that you can customize the behavior of ``issubclass`` further without the + need to call :meth:`register` on every class you want to consider a + subclass of the ABC. + + This method should return ``True``, ``False`` or ``NotImplemented``. If + it returns ``True``, the *subclass* is considered a subclass of this ABC. + If it returns ``False``, the *subclass* is not considered a subclass of + this ABC, even if it would normally be one. If it returns + ``NotImplemented``, the subclass check is continued with the usual + mechanism. + + + To demonstrate these concepts, look at this example ABC definition:: + + class MyIterator: + pass + + class Iterator(metaclass=ABCMeta): + + @abstractmethod + def __next__(self): + raise StopIteration + + def __iter__(self): + return self + + @classmethod + def __subclasshook__(cls, C): + if cls is Iterator: + if any("__next__" in B.__dict__ for B in C.__mro__): + return True + return NotImplemented + + Iterator.register(MyIterator) + + The ABC ``Iterator`` defines the two standard iterator methods: + :meth:`__iter__` and :meth:`__next__`. The :meth:`__iter__` method is given + a default implementation, while the :meth:`__next__` method is abstract. + + .. XXX why is an implementation given then? + + The :meth:`__subclasshook__` class method defined here says that any class + that has a :meth:`__next__` method in its :attr:`__dict__` (or in that of one + of its subclasses, accessed via the :attr:`__mro__`) is considered an + ``Iterator`` too. + + Finally, the last line makes ``MyIterator`` a virtual subclass of + ``Iterator``, even though it does not define a :meth:`__next__` method. + (Of course, this doesn't make much sense in this context.) + + .. XXX perhaps find better example + + +It also provides the following decorators: + +.. function:: abstractmethod(function) + + A decorator indicating abstract methods. + + Requires that the metaclass is :class:`ABCMeta` or derived from it. A class + that has a metaclass derived from :class:`ABCMeta` cannot be instantiated + unless all of its abstract methods are overridden. The abstract methods can + be called using any of the the normal 'super' call mechanisms. + + Usage:: + + class C(metaclass=ABCMeta): + @abstractmethod + def my_abstract_method(self, ...): + ... + + +.. function:: abstractproperty(property) + + A decorator indicating abstract properties. + + Requires that the metaclass is :class:`ABCMeta` or derived from it. A class + that has a metaclass derived from :class:`ABCMeta` cannot be instantiated + unless all of its abstract properties are overridden. The abstract + properties can be called using any of the the normal 'super' call mechanisms. + + Usage:: + + class C(metaclass=ABCMeta): + @abstractproperty + def my_abstract_property(self): + ... + + This defines a read-only property; you can also define a read-write abstract + property using the 'long' form of property declaration:: + + class C(metaclass=ABCMeta): + def getx(self): ... + def setx(self, value): ... + x = abstractproperty(getx, setx) + diff --git a/Doc/library/python.rst b/Doc/library/python.rst index 3b58eee..3384322 100644 --- a/Doc/library/python.rst +++ b/Doc/library/python.rst @@ -17,6 +17,7 @@ overview: __main__.rst warnings.rst contextlib.rst + abc.rst atexit.rst traceback.rst __future__.rst |