gh-94912: deprecate asyncio.iscoroutinefunction when it behaves differently to inspect.iscoroutinefunction

[graingert]

• Issue: make asyncio.iscoroutinefunction a deprecated alias of inspect.iscoroutinefunction and remove asyncio.coroutines._is_coroutine #94912

[graingert]

this will insist on objects being real awaitables rather than virtual awaitables - eg:

importasyncio.tasksimportcollections.abcimportunittest.mock@collections.abc.Awaitable.registerclasssleep_0:
def__init__(self):
self.__await__=lambda: iter((None, ))
asyncdef_wrap_awaitable(awaitable):
returnawaitawaitableasyncdefamain():
awaitasyncio.ensure_future(sleep_0()) # this works currently but with the new code:withunittest.mock.patch("asyncio.tasks._wrap_awaitable", new=_wrap_awaitable):
awaitasyncio.ensure_future(sleep_0()) # it will breakasyncio.run(amain())

[graingert]

this is to fix #94924

[graingert]

I'll need to do a doc change for this too

[graingert]

cc @hugovk for removals

[hugovk]

Please could you add it to a 3.14 section like https://docs.python.org/3.12/whatsnew/3.12.html#pending-removal-in-python-3-13 ?

And add a .. deprecated-removed:: 3.12 3.14 to the function in its module rst page.

[graingert]

@hugovk asyncio.iscoroutinefunction's module rst page was already removed: https://github.com/python/cpython/pull/26369/files#diff-5e9a5bb933b1bd1d6092f7e5adb5c06da7a6792e0597f55f911245acacfce7a7L1025

(oops maybe I shouldn't have approved that PR)

[graingert]

This is another very subtle change - before the signature was checked when the function was called - and now the signature is checked when the coro is primed, but I think this is a better behavior and worth it to allow inspect.iscoroutinefunction to work