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:

import asyncio.tasks
import collections.abc
import unittest.mock


@collections.abc.Awaitable.register
class sleep_0:
    def __init__(self):
        self.__await__ = lambda: iter((None, ))


async def _wrap_awaitable(awaitable):
    return await awaitable


async def amain():
    await asyncio.ensure_future(sleep_0())  # this works currently but with the new code:
    with unittest.mock.patch("asyncio.tasks._wrap_awaitable", new=_wrap_awaitable):
        await asyncio.ensure_future(sleep_0())  # it will break
asyncio.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