[Python-checkins] cpython (3.3): Close issue #16267: better docs for @abstractmethod composition

[nick.coghlan]

http://hg.python.org/cpython/rev/3345afd6dc61
changeset:   80753:3345afd6dc61
branch:      3.3
parent:      80751:8ba3c975775b
user:        Nick Coghlan <ncoghlan at gmail.com>
date:        Sat Dec 08 22:56:02 2012 +1000
summary:
  Close issue #16267: better docs for @abstractmethod composition

files:
  Doc/library/abc.rst |  59 ++++++++++++++++++++++++--------
  Misc/NEWS           |   3 +
  2 files changed, 47 insertions(+), 15 deletions(-)


diff --git a/Doc/library/abc.rst b/Doc/library/abc.rst
--- a/Doc/library/abc.rst
+++ b/Doc/library/abc.rst
@@ -208,16 +208,20 @@
    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
-       Use :class:`classmethod` with :func:`abstractmethod` instead.
+       It is now possible to use :class:`classmethod` with
+       :func:`abstractmethod`, making this decorator redundant.
 
 
 .. decorator:: abstractstaticmethod(function)
@@ -225,21 +229,26 @@
    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
-       Use :class:`staticmethod` with :func:`abstractmethod` instead.
+       It is now possible to use :class:`staticmethod` with
+       :func:`abstractmethod`, making this decorator redundant.
 
 
 .. 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
@@ -247,23 +256,43 @@
    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
-       Use :class:`property` with :func:`abstractmethod` instead
+       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
diff --git a/Misc/NEWS b/Misc/NEWS
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -322,6 +322,9 @@
 Documentation
 -------------
 
+- Issue #16267: Better document the 3.3+ approach to combining
+  @abstractmethod with @staticmethod, @classmethod and @property
+
 - Issue #15209: Clarify exception chaining description in exceptions module
   documentation
 

-- 
Repository URL: http://hg.python.org/cpython