Close #13266: Add inspect.unwrap

Initial patch by Daniel Urban and Aaron Iles

2 files changed, 28 insertions, 3 deletions

diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst
index 40f482b..af6c96b 100644
--- a/Doc/library/inspect.rst
+++ b/Doc/library/inspect.rst
@@ -797,6 +797,23 @@ Classes and functions
    .. versionadded:: 3.3
 
 
+.. function:: unwrap(func, *, stop=None)
+
+   Get the object wrapped by *func*. It follows the chain of :attr:`__wrapped__`
+   attributes returning the last object in the chain.
+
+   *stop* is an optional callback accepting an object in the wrapper chain
+   as its sole argument that allows the unwrapping to be terminated early if
+   the callback returns a true value. If the callback never returns a true
+   value, the last object in the chain is returned as usual. For example,
+   :func:`signature` uses this to stop unwrapping if any object in the
+   chain has a ``__signature__`` attribute defined.
+
+   :exc:`ValueError` is raised if a cycle is encountered.
+
+   .. versionadded:: 3.4
+
+
 .. _inspect-stack:
 
 The interpreter stack
diff --git a/Doc/whatsnew/3.4.rst b/Doc/whatsnew/3.4.rst
index 40b8243..b5be568 100644
--- a/Doc/whatsnew/3.4.rst
+++ b/Doc/whatsnew/3.4.rst
@@ -185,6 +185,15 @@ functools
 
 New :func:`functools.singledispatch` decorator: see the :pep:`443`.
 
+
+inspect
+-------
+
+:func:`~inspect.unwrap` makes it easy to unravel wrapper function chains
+created by :func:`functools.wraps` (and any other API that sets the
+``__wrapped__`` attribute on a wrapper function).
+
+
 smtplib
 -------
 
@@ -327,6 +336,5 @@ that may require changes to your code.
   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.
+  libraries that assumed the previous behaviour was intentional can use
+  :func:`inspect.unwrap` to gain equivalent behaviour.