Close #13062: Add inspect.getclosurevars to simplify testing stateful closures

2 files changed, 26 insertions, 0 deletions

diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst
index 611f780..04b724b 100644
--- a/Doc/library/inspect.rst
+++ b/Doc/library/inspect.rst
@@ -497,6 +497,22 @@ Classes and functions
    .. versionadded:: 3.2
 
 
+.. function:: getclosurevars(func)
+
+   Get the mapping of external name references in a Python function or
+   method *func* to their current values. A
+   :term:`named tuple` ``ClosureVars(nonlocals, globals, builtins, unbound)``
+   is returned. *nonlocals* maps referenced names to lexical closure
+   variables, *globals* to the function's module globals and *builtins* to
+   the builtins visible from the function body. *unbound* is the set of names
+   referenced in the function that could not be resolved at all given the
+   current module globals and builtins.
+
+   :exc:`TypeError` is raised if *func* is not a Python function or method.
+
+   .. versionadded:: 3.3
+
+
 .. _inspect-stack:
 
 The interpreter stack
diff --git a/Doc/whatsnew/3.3.rst b/Doc/whatsnew/3.3.rst
index 974cc71..592f9c9 100644
--- a/Doc/whatsnew/3.3.rst
+++ b/Doc/whatsnew/3.3.rst
@@ -1027,6 +1027,16 @@ parameter to control parameters of the secure channel.
 (Contributed by Sijin Joseph in :issue:`8808`)
 
 
+inspect
+-------
+
+A new :func:`~inspect.getclosurevars` function has been added. This function
+reports the current binding of all names referenced from the function body and
+where those names were resolved, making it easier to verify correct internal
+state when testing code that relies on stateful closures.
+
+(Contributed by Meador Inge and Nick Coghlan in :issue:`13062`)
+
 io
 --