bpo-41905: Add abc.update_abstractmethods() (GH-22485)

This function recomputes `cls.__abstractmethods__`.
Also update `@dataclass` to use it.

2 files changed, 28 insertions, 5 deletions

diff --git a/Doc/library/abc.rst b/Doc/library/abc.rst
index 424ae54..3a7414d 100644
--- a/Doc/library/abc.rst
+++ b/Doc/library/abc.rst
@@ -174,10 +174,11 @@ The :mod:`abc` module also provides the following decorator:
    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
-   supported.  The :func:`abstractmethod` only affects subclasses derived using
-   regular inheritance; "virtual subclasses" registered with the ABC's
-   :meth:`register` method are not affected.
+   abstraction status of a method or class once it is created, are only
+   supported using the :func:`update_abstractmethods` function.  The
+   :func:`abstractmethod` only affects subclasses derived using regular
+   inheritance; "virtual subclasses" registered with the ABC's :meth:`register`
+   method are not affected.
 
    When :func:`abstractmethod` is applied in combination with other method
    descriptors, it should be applied as the innermost decorator, as shown in
@@ -235,7 +236,6 @@ The :mod:`abc` module also provides the following decorator:
       super-call in a framework that uses cooperative
       multiple-inheritance.
 
-
 The :mod:`abc` module also supports the following legacy decorators:
 
 .. decorator:: abstractclassmethod
@@ -335,6 +335,22 @@ The :mod:`abc` module also provides the following functions:
 
    .. versionadded:: 3.4
 
+.. function:: update_abstractmethods(cls)
+   A function to recalculate an abstract class's abstraction status. This
+   function should be called if a class's abstract methods have been
+   implemented or changed after it was created. Usually, this function should
+   be called from within a class decorator.
+
+   Returns *cls*, to allow usage as a class decorator.
+
+   If *cls* is not an instance of ABCMeta, does nothing.
+
+   .. note::
+
+      This function assumes that *cls*'s superclasses are already updated.
+      It does not update any subclasses.
+
+   .. versionadded:: 3.10
 
 .. rubric:: Footnotes
 
diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst
index 14aa184..186cb4c 100644
--- a/Doc/library/functools.rst
+++ b/Doc/library/functools.rst
@@ -254,6 +254,13 @@ The :mod:`functools` module defines the following functions:
       application, implementing all six rich comparison methods instead is
       likely to provide an easy speed boost.
 
+   .. note::
+
+      This decorator makes no attempt to override methods that have been
+      declared in the class *or its superclasses*. Meaning that if a
+      superclass defines a comparison operator, *total_ordering* will not
+      implement it again, even if the original method is abstract.
+
    .. versionadded:: 3.2
 
    .. versionchanged:: 3.4