bpo-36921: Deprecate @coroutine for sake of async def

[asvetlov]

The second attempt. Now deprecate @coroutine only, keep yield from fut as is.

https://bugs.python.org/issue36921

[asvetlov]

The same functionality but without @coroutine

[ilevkivskyi]

The typing part LGTM.

[Carreau]

want to update asyncio-task.rst to use the .. deprecated-removed:: 3.8 3.10 directive ?

[Carreau]

Also side-question (and maybe this is better suited for bpo , should asyncio.iscoroutine and asyncio.iscoroutinefunction be deprecated at the same time ?

Because presumably once @coroutine is removed, the two other have quasy no chance of encountering a coroutine that would not be properly detected by inspect.iscoroutine.

I'm thinking they are still useful from inter-library compatibility and across python version; so maybe deprecate as well but remove even later ?

[1st1]

Overall LGTM. Please fix the few nits I commented on.

[1st1]

Also side-question (and maybe this is better suited for bpo , should asyncio.iscoroutine and asyncio.iscoroutinefunction be deprecated at the same time ?

We can deprecate them when we remove @asyncio.coroutine (in 3.9?)

[asvetlov]

@caavery the funny thing that @coroutine is already deprecated in docs. Now we have the support of this statement explicitly in code.
Removal is scheduled for 3.10, that's fine.
I agree with @1st1 that asyncio.iscoroutine and asyncio.iscoroutinefunction should be deprecated later.
As the maintainer of several asyncio based libraries, I want a smooth transition path.
My libraries don't use @coroutine already but sometimes accept async callbacks and calls asyncio checkers for them. I want to support user-written old-style coros in my libraries as long as possible (but discourage them).
Basically the same as asyncio itself does.
Deprecation checkers after removal the root functionality absolutely makes sense to me. We can consider deprecation in 3.9 if you want but I pretty sure we shouldn't do it in 3.8.

[asvetlov]

Replace free-form deprecation text with more standardized one.

[asvetlov]

The last call for a review.
I have a plan to merge the PR in a day.

[1st1]

The last call for a review.

I think it's ready.