Improved the comments and docs

david-caro · david-caro · commit a020a97cf819 · 2020-08-08T14:06:47.000+01:00
Signed-off-by: David Caro &lt;david@dcaro.es&gt;
diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst
@@ -572,10 +572,22 @@ The :mod:`functools` module defines the following functions:
    on the wrapper function). :exc:`AttributeError` is still raised if the
    wrapper function itself is missing any attributes named in *updated*.
 
-   If the wrapper function defined any type annotations, they will always be
-   preserved. But if not, they will be extracted from the wrapped function
-   ``__annotations__`` if available and ``__annotations__`` is in the *updated*
-   list.
+   When assigning the ``__annotations__`` attribute (when it's part of the
+   ``assigned`` list parameter), it will be populated only if missing some
+   annotations as follows:
+
+   * If the wrapper function defines it's own return type and parameter
+     annotations, those will be preserved.
+
+   * If the wrapper function does not annotate the return type, it will be
+     copied from the wrapped if any.
+
+   * If the wrapped function does not annotate any parameters, the annotations
+     for them will be copied over from the wrapped if any.
+
+   That ensures that any custom annotations from the wrapper will not be
+   overridden by the wrapped, allowing to change the annotated types of
+   the wrapped function.
 
    .. versionadded:: 3.2
       Automatic addition of the ``__wrapped__`` attribute.
diff --git a/Lib/functools.py b/Lib/functools.py
@@ -46,6 +46,12 @@ def update_wrapper(wrapper,
        updated is a tuple naming the attributes of the wrapper that
        are updated with the corresponding attribute from the wrapped
        function (defaults to functools.WRAPPER_UPDATES)
+
+       There's a special treatment for the `__annotations__` attribute:
+       * If the wrapper defines a return type, then that will be used, if not,
+         the one from the wrapped function will be used if any.
+       * If the wrapper defines any parameter types, those will be used, if
+         not, the ones from the wrapped function will be used if any.
     """
     for attr in assigned:
         try:
@@ -59,24 +65,24 @@ def update_wrapper(wrapper,
 
     if '__annotations__' in assigned:
         try:
-            # Issue #41231: copy the annotations only if there's none defined
-            # in the wrapper
+            # Issue #41231: copy the annotations from wrapped, only if they are
+            #  not already defined in the wrapper
             if not wrapper.__annotations__:
                 wrapper.__annotations__ = wrapped.__annotations__
-            # if only the return wrapped has annotations, assume that the
-            # parameters stay the same
+            # if the wrapper does not annotate the parameters, copy their
+            # annotations over from the wrapped
             elif ('return' in wrapper.__annotations__
                   and len(wrapper.__annotations__) == 1):
                 wrapper.__annotations__ = {
                     **wrapped.__annotations__,
                     **wrapper.__annotations__,
                 }
-            # if only the parameters have annotations, assume that the return
-            # type stays the same
+            # if the wrapper does not annotate the return type, copy the
+            # annotation from the wrapped
             elif ('return' not in wrapper.__annotations__
                   and 'return' in wrapped.__annotations__):
                 wrapper.__annotations__['return'] = wrapped.__annotations__['return']
-        except AttributeError as error:
+        except AttributeError:
             pass
 
     for attr in updated:
