diff options
Diffstat (limited to 'Doc/library/abc.rst')
| -rw-r--r-- | Doc/library/abc.rst | 135 |
1 files changed, 106 insertions, 29 deletions
diff --git a/Doc/library/abc.rst b/Doc/library/abc.rst index dcec19a..6f23596 100644 --- a/Doc/library/abc.rst +++ b/Doc/library/abc.rst @@ -18,7 +18,7 @@ regarding a type hierarchy for numbers based on ABCs.) The :mod:`collections` module has some concrete classes that derive from ABCs; these can, of course, be further derived. In addition the -:mod:`collections` module has some ABCs that can be used to test whether +:mod:`collections.abc` submodule has some ABCs that can be used to test whether a class or instance provides a particular interface, for example, is it hashable or a mapping. @@ -55,6 +55,9 @@ This module provides the following class: assert issubclass(tuple, MyABC) assert isinstance((), MyABC) + .. versionchanged:: 3.3 + Returns the registered subclass, to allow usage as a class decorator. + You can also override this method in an abstract base class: .. method:: __subclasshook__(subclass) @@ -124,19 +127,18 @@ This module provides the following class: available as a method of ``Foo``, so it is provided separately. -It also provides the following decorators: +The :mod:`abc` module also provides the following decorators: .. decorator:: abstractmethod A decorator indicating abstract methods. - Using this decorator requires that the class's metaclass is :class:`ABCMeta` or - is derived from it. - A class that has a metaclass derived from :class:`ABCMeta` - cannot be instantiated unless all of its abstract methods and - properties are overridden. - The abstract methods can be called using any of the normal 'super' call - mechanisms. + Using this decorator requires that the class's metaclass is :class:`ABCMeta` + or is derived from it. A class that has a metaclass derived from + :class:`ABCMeta` cannot be instantiated unless all of its abstract methods + and properties are overridden. The abstract methods can be called using any + of the normal 'super' call mechanisms. :func:`abstractmethod` may be used + to declare abstract methods for properties and descriptors. Dynamically adding abstract methods to a class, or attempting to modify the abstraction status of a method or class once it is created, are not @@ -144,12 +146,52 @@ It also provides the following decorators: regular inheritance; "virtual subclasses" registered with the ABC's :meth:`register` method are not affected. - Usage:: + When :func:`abstractmethod` is applied in combination with other method + descriptors, it should be applied as the innermost decorator, as shown in + the following usage examples:: class C(metaclass=ABCMeta): @abstractmethod def my_abstract_method(self, ...): ... + @classmethod + @abstractmethod + def my_abstract_classmethod(cls, ...): + ... + @staticmethod + @abstractmethod + def my_abstract_staticmethod(...): + ... + + @property + @abstractmethod + def my_abstract_property(self): + ... + @my_abstract_property.setter + @abstractmethod + def my_abstract_property(self, val): + ... + + @abstractmethod + def _get_x(self): + ... + @abstractmethod + def _set_x(self, val): + ... + x = property(_get_x, _set_x) + + In order to correctly interoperate with the abstract base class machinery, + the descriptor must identify itself as abstract using + :attr:`__isabstractmethod__`. In general, this attribute should be ``True`` + if any of the methods used to compose the descriptor are abstract. For + example, Python's built-in property does the equivalent of:: + + class Descriptor: + ... + @property + def __isabstractmethod__(self): + return any(getattr(f, '__isabstractmethod__', False) for + f in (self._fget, self._fset, self._fdel)) .. note:: @@ -166,14 +208,20 @@ It also provides the following decorators: A subclass of the built-in :func:`classmethod`, indicating an abstract classmethod. Otherwise it is similar to :func:`abstractmethod`. - Usage:: + This special case is deprecated, as the :func:`classmethod` decorator + is now correctly identified as abstract when applied to an abstract + method:: class C(metaclass=ABCMeta): - @abstractclassmethod + @classmethod + @abstractmethod def my_abstract_classmethod(cls, ...): ... .. versionadded:: 3.2 + .. deprecated:: 3.3 + It is now possible to use :class:`classmethod` with + :func:`abstractmethod`, making this decorator redundant. .. decorator:: abstractstaticmethod @@ -181,41 +229,70 @@ It also provides the following decorators: A subclass of the built-in :func:`staticmethod`, indicating an abstract staticmethod. Otherwise it is similar to :func:`abstractmethod`. - Usage:: + This special case is deprecated, as the :func:`staticmethod` decorator + is now correctly identified as abstract when applied to an abstract + method:: class C(metaclass=ABCMeta): - @abstractstaticmethod + @staticmethod + @abstractmethod def my_abstract_staticmethod(...): ... .. versionadded:: 3.2 + .. deprecated:: 3.3 + It is now possible to use :class:`staticmethod` with + :func:`abstractmethod`, making this decorator redundant. -.. function:: abstractproperty(fget=None, fset=None, fdel=None, doc=None) +.. decorator:: abstractproperty(fget=None, fset=None, fdel=None, doc=None) - A subclass of the built-in :func:`property`, indicating an abstract property. + A subclass of the built-in :func:`property`, indicating an abstract + property. - Using this function requires that the class's metaclass is :class:`ABCMeta` or - is derived from it. - A class that has a metaclass derived from :class:`ABCMeta` cannot be - instantiated unless all of its abstract methods and properties are overridden. - The abstract properties can be called using any of the normal - 'super' call mechanisms. + Using this function requires that the class's metaclass is :class:`ABCMeta` + or is derived from it. A class that has a metaclass derived from + :class:`ABCMeta` cannot be instantiated unless all of its abstract methods + and properties are overridden. The abstract properties can be called using + any of the normal 'super' call mechanisms. - Usage:: + This special case is deprecated, as the :func:`property` decorator + is now correctly identified as abstract when applied to an abstract + method:: class C(metaclass=ABCMeta): - @abstractproperty + @property + @abstractmethod 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:: + The above example defines a read-only property; you can also define a + read-write abstract property by appropriately marking one or more of the + underlying methods as abstract:: class C(metaclass=ABCMeta): - def getx(self): ... - def setx(self, value): ... - x = abstractproperty(getx, setx) + @property + def x(self): + ... + + @x.setter + @abstractmethod + def x(self, val): + ... + + If only some components are abstract, only those components need to be + updated to create a concrete property in a subclass:: + + class D(C): + @C.x.setter + def x(self, val): + ... + + + .. deprecated:: 3.3 + It is now possible to use :class:`property`, :meth:`property.getter`, + :meth:`property.setter` and :meth:`property.deleter` with + :func:`abstractmethod`, making this decorator redundant. .. rubric:: Footnotes |