Close issue 17482: don't overwrite __wrapped__

2 files changed, 16 insertions, 2 deletions

diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst
index 3d70955c58..2f6d9afe0f 100644
--- a/Doc/library/functools.rst
+++ b/Doc/library/functools.rst
@@ -306,8 +306,8 @@ The :mod:`functools` module defines the following functions:
 
    To allow access to the original function for introspection and other purposes
    (e.g. bypassing a caching decorator such as :func:`lru_cache`), this function
-   automatically adds a __wrapped__ attribute to the wrapper that refers to
-   the original function.
+   automatically adds a ``__wrapped__`` attribute to the wrapper that refers to
+   the function being wrapped.
 
    The main intended use for this function is in :term:`decorator` functions which
    wrap the decorated function and return the wrapper. If the wrapper function is
@@ -330,6 +330,11 @@ The :mod:`functools` module defines the following functions:
    .. versionchanged:: 3.2
       Missing attributes no longer trigger an :exc:`AttributeError`.
 
+   .. versionchanged:: 3.4
+      The ``__wrapped__`` attribute now always refers to the wrapped
+      function, even if that function defined a ``__wrapped__`` attribute.
+      (see :issue:`17482`)
+
 
 .. decorator:: wraps(wrapped, assigned=WRAPPER_ASSIGNMENTS, updated=WRAPPER_UPDATES)
 
diff --git a/Doc/whatsnew/3.4.rst b/Doc/whatsnew/3.4.rst
index 406894743d..2b114f135b 100644
--- a/Doc/whatsnew/3.4.rst
+++ b/Doc/whatsnew/3.4.rst
@@ -315,3 +315,12 @@ that may require changes to your code.
   found but improperly structured. If you were catching ImportError before and
   wish to continue to ignore syntax or decoding issues, catch all three
   exceptions now.
+
+* :func:`functools.update_wrapper` and :func:`functools.wraps` now correctly
+  set the ``__wrapped__`` attribute even if the wrapped function had a
+  wrapped attribute set. This means ``__wrapped__`` attributes now correctly
+  link a stack of decorated functions rather than every ``__wrapped__``
+  attribute in the chain referring to the innermost function. Introspection
+  libraries that assumed the previous behaviour was intentional will need to
+  be updated to walk the chain of ``__wrapped__`` attributes to find the
+  innermost function.