Issue 24342: Let wrapper set by sys.set_coroutine_wrapper fail gracefully

1 files changed, 14 insertions, 0 deletions

diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
index 3e8fd82..f9733b2 100644
--- a/Doc/library/sys.rst
+++ b/Doc/library/sys.rst
@@ -1085,6 +1085,20 @@ always available.
    If called twice, the new wrapper replaces the previous one.  The function
    is thread-specific.
 
+   The *wrapper* callable cannot define new coroutines directly or indirectly::
+
+        def wrapper(coro):
+            async def wrap(coro):
+                return await coro
+            return wrap(coro)
+        sys.set_coroutine_wrapper(wrapper)
+
+        async def foo(): pass
+
+        # The following line will fail with a RuntimeError, because
+        # `wrapper` creates a `wrap(coro)` coroutine:
+        foo()
+
    See also :func:`get_coroutine_wrapper`.
 
    .. versionadded:: 3.5