gh-79012: Add asyncio tutorial (proposal)

[kovan]

Summary

This is a proposal / starting point for discussion — not a finished document. Feedback on structure, scope, tone, and technical content is very welcome.

This PR adds a hands-on asyncio tutorial (Doc/howto/asyncio-tutorial.rst) as discussed in gh-79012. Following the Diátaxis framework, this is a Tutorial (learning-by-doing) complementing the existing Explanation HOWTO (a-conceptual-overview-of-asyncio.rst).

The tutorial progressively teaches asyncio through runnable examples, building up to a complete TCP chat server:

• Why asyncio? — motivation (thread safety, visible suspension points)
• Your first async program — async def, await, asyncio.run()
• Running tasks concurrently — create_task(), TaskGroup
• Handling timeouts — asyncio.timeout()
• Producer-consumer with queues — asyncio.Queue, shutdown()
• Running blocking code — asyncio.to_thread()
• Network programming with streams — echo server/client
• Case study: a chat server — ties all concepts together
• Extending the chat server — idle timeout + exercises
• Common pitfalls — forgetting await, blocking the loop, etc.

Uses only modern, recommended APIs (TaskGroup, asyncio.timeout(), Queue.shutdown()). Avoids low-level event loop management entirely, per maintainer guidance in the issue.

All code examples have been verified to run correctly.

Test plan

• make -C Doc check passes (Sphinx lint, formatting)
• make -C Doc html builds with zero warnings
• All 10 code examples tested and produce expected output
• Cross-references (:func:, :class:, :ref:) resolve correctly

🤖 Generated with Claude Code

---

📚 Documentation preview 📚: https://cpython-previews--144594.org.readthedocs.build/

[ZeroIntensity]

We already have one of these: https://docs.python.org/3/howto/a-conceptual-overview-of-asyncio.html.

There are some things here that look useful for the docs, but I don't think they need to be put under an "asyncio tutorial" umbrella. Instead, let's just make a HOWTO page for a chat server, since that seems to be the primary focus of all the content here.

But as with your previous PRs, please put more time into researching context and prior art before diving into a pull request.

[ZeroIntensity]

This isn't really right. That page functions as the asyncio tutorial, not documentation about how it works.

[kovan]

Yeah but after adding this tutorial, that would be more low level.

[ZeroIntensity]

Well, not really. If we talked about implementing the coroutine protocol or something like that, then that would be "low level", but that article is strictly about teaching the user how to use asyncio from a beginner perspective. We don't need to do that twice in the docs.

The proposed page in this PR seems to be about the skills necessary to build a chat server, so why not frame it as such?

[bedevere-app]

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

[kovan]

But the point is that it is intended to be a tutorial. Thats was the whole point of the original issue also. A tutorial and a HOWTO are two different things: you read HOWTOs to learn how to do a concrete thing that you want to do; and you read tutorials to learn how to use a library, function, or piece of code in general. Very different.

[ZeroIntensity]

Yes, I'm aware. See my comment on the issue; "A Conceptual Overview of asyncio" is not really a HOWTO, despite being named one. It's a tutorial.