gh-122858: Deprecate `asyncio.iscoroutinefunction` (#122875)

Deprecate `asyncio.iscoroutinefunction` in favor of `inspect.iscoroutinefunction`.

Co-authored-by: Kumar Aditya <kumaraditya@python.org>

Doc/library/unittest.mock.rst

@@ -882,7 +882,7 @@ object::
   call is an awaitable.
 
     >>> mock = AsyncMock()
-    >>> asyncio.iscoroutinefunction(mock)
+    >>> inspect.iscoroutinefunction(mock)
     True
     >>> inspect.isawaitable(mock())  # doctest: +SKIP
     True

Doc/whatsnew/3.14.rst

@@ -434,6 +434,11 @@ Deprecated
   :c:macro:`!isfinite` available from :file:`math.h`
   since C99.  (Contributed by Sergey B Kirpichev in :gh:`119613`.)
 
+* :func:`!asyncio.iscoroutinefunction` is deprecated
+  and will be removed in Python 3.16,
+  use :func:`inspect.iscoroutinefunction` instead.
+  (Contributed by Jiahao Li and Kumar Aditya in :gh:`122875`.)
+
 .. Add deprecations above alphabetically, not here at the end.
 
 .. include:: ../deprecations/c-api-pending-removal-in-3.15.rst

Lib/asyncio/base_events.py

@@ -837,7 +837,7 @@ class BaseEventLoop(events.AbstractEventLoop):
 
     def _check_callback(self, callback, method):
         if (coroutines.iscoroutine(callback) or
-                coroutines.iscoroutinefunction(callback)):
+                coroutines._iscoroutinefunction(callback)):
             raise TypeError(
                 f"coroutines cannot be used with {method}()")
         if not callable(callback):

Lib/asyncio/coroutines.py

@@ -18,7 +18,16 @@ _is_coroutine = object()
 
 
 def iscoroutinefunction(func):
+    import warnings
     """Return True if func is a decorated coroutine function."""
+    warnings._deprecated("asyncio.iscoroutinefunction",
+                         f"{warnings._DEPRECATED_MSG}; "
+                         "use inspect.iscoroutinefunction() instead",
+                         remove=(3,16))
+    return _iscoroutinefunction(func)
+
+
+def _iscoroutinefunction(func):
     return (inspect.iscoroutinefunction(func) or
             getattr(func, '_is_coroutine', None) is _is_coroutine)
 

Lib/asyncio/unix_events.py

@@ -95,7 +95,7 @@ class _UnixSelectorEventLoop(selector_events.BaseSelectorEventLoop):
         Raise RuntimeError if there is a problem setting up the handler.
         """
         if (coroutines.iscoroutine(callback) or
-                coroutines.iscoroutinefunction(callback)):
+                coroutines._iscoroutinefunction(callback)):
             raise TypeError("coroutines cannot be used "
                             "with add_signal_handler()")
         self._check_signal(sig)

Lib/test/test_asyncio/test_pep492.py

@@ -124,10 +124,10 @@ class CoroutineTests(BaseTest):
 
         self.assertFalse(asyncio.iscoroutine(foo()))
 
-
     def test_iscoroutinefunction(self):
         async def foo(): pass
-        self.assertTrue(asyncio.iscoroutinefunction(foo))
+        with self.assertWarns(DeprecationWarning):
+            self.assertTrue(asyncio.iscoroutinefunction(foo))
 
     def test_async_def_coroutines(self):
         async def bar():

Lib/test/test_asyncio/test_tasks.py

@@ -20,6 +20,7 @@ from asyncio import tasks
 from test.test_asyncio import utils as test_utils
 from test import support
 from test.support.script_helper import assert_python_ok
+from test.support.warnings_helper import ignore_warnings
 
 
 def tearDownModule():
@@ -1939,6 +1940,7 @@ class BaseTaskTests:
         self.assertFalse(task.cancelled())
         self.assertIs(task.exception(), base_exc)
 
+    @ignore_warnings(category=DeprecationWarning)
     def test_iscoroutinefunction(self):
         def fn():
             pass
@@ -1956,6 +1958,7 @@ class BaseTaskTests:
         self.assertFalse(asyncio.iscoroutinefunction(mock.Mock()))
         self.assertTrue(asyncio.iscoroutinefunction(mock.AsyncMock()))
 
+    @ignore_warnings(category=DeprecationWarning)
     def test_coroutine_non_gen_function(self):
         async def func():
             return 'test'

Lib/test/test_unittest/testmock/testmagicmethods.py

@@ -1,7 +1,7 @@
 import math
 import unittest
 import os
-from asyncio import iscoroutinefunction
+from inspect import iscoroutinefunction
 from unittest.mock import AsyncMock, Mock, MagicMock, _magics
 
 

Lib/unittest/mock.py

@@ -32,7 +32,7 @@ import pprint
 import sys
 import builtins
 import pkgutil
-from asyncio import iscoroutinefunction
+from inspect import iscoroutinefunction
 import threading
 from types import CodeType, ModuleType, MethodType
 from unittest.util import safe_repr
@@ -2456,7 +2456,7 @@ class AsyncMock(AsyncMockMixin, AsyncMagicMixin, Mock):
     recognized as an async function, and the result of a call is an awaitable:
 
     >>> mock = AsyncMock()
-    >>> iscoroutinefunction(mock)
+    >>> inspect.iscoroutinefunction(mock)
     True
     >>> inspect.isawaitable(mock())
     True

Misc/NEWS.d/next/Library/2024-08-10-10-21-44.gh-issue-122858.ZC1rJD.rst

@@ -0,0 +1,2 @@
+Deprecate :func:`!asyncio.iscoroutinefunction` in favor of
+:func:`inspect.iscoroutinefunction`.