gh-79012: Add asyncio chat server HOWTO #144604

kovan · 2026-02-08T20:21:58Z

Summary

Adds a focused HOWTO for building a TCP chat server with asyncio streams, as suggested by @ZeroIntensity in the review of #144594:

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.

The guide progressively builds from an echo server to a full chat server:

Starting with an echo server — introduces the streams API (start_server, StreamReader/StreamWriter, write/drain, close/wait_closed)
Building the chat server — adds client tracking, broadcasting, and cleanup
Extending the chat server — idle timeouts with asyncio.timeout, plus exercises
Common pitfalls — forgetting to await, blocking the event loop, fire-and-forget tasks

No overlap with the existing Conceptual Overview — this is purely a practical, hands-on HOWTO.

Test plan

make -C Doc check passes
make -C Doc html passes (no warnings)
All cross-references resolve correctly

🤖 Generated with Claude Code

Issue: Asyncio Tutorial #79012

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

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Doc/howto/asyncio-chat-server.rst

ZeroIntensity · 2026-02-10T13:34:14Z

Doc/howto/asyncio-chat-server.rst

+Common pitfalls
+===============


This section isn't really about the chat server. These are just common asyncio traps that would fit better in the tutorial or the reference docs.

Doc/howto/asyncio-chat-server.rst

Doc/library/asyncio.rst

- Explain concepts (start_server, StreamReader/StreamWriter) before code - Use asyncio.TaskGroup for concurrent broadcasting - Use contextlib.suppress instead of bare except/pass - Remove Python test client, keep only nc/telnet - Properly explain asyncio.timeout before showing usage - Move implementation notes to code comments - Remove Exercises and Common pitfalls sections - Reorder seealso links in asyncio.rst Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

kovan · 2026-02-10T15:44:16Z

I have made the requested changes; please review again

bedevere-app · 2026-02-10T15:44:24Z

Thanks for making the requested changes!

: please review the changes made to this pull request.

Doc/howto/asyncio-chat-server.rst

- Move write/drain and close/wait_closed explanations above the echo server example - Explain async with server, serve_forever, and asyncio.run - Break chat server into subsections: client tracking, broadcasting, then the complete example - Show broadcast function separately before the full listing Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

kovan · 2026-02-10T16:42:05Z

I have made the requested changes; please review again

bedevere-app · 2026-02-10T16:42:09Z

Thanks for making the requested changes!

: please review the changes made to this pull request.

ZeroIntensity · 2026-02-11T13:27:38Z

Doc/howto/asyncio-chat-server.rst

+one at a time.  :func:`contextlib.suppress` silently handles any
+:exc:`ConnectionError` from clients that have already disconnected::


I don't think we need to explain contextlib.suppress -- that's not part of asyncio and should fall under the umbrella of "basic Python knowledge". If you want, we can add a comment in the example explaining what it does.

ZeroIntensity · 2026-02-11T13:28:44Z

Doc/howto/asyncio-chat-server.rst

+   Bob: Hi Alice!
+   Hello Bob!
+
+Each message you type is broadcast to all other connected users.


Suggested change

Each message you type is broadcast to all other connected users.

Each message you type is broadcasted to all other connected users.

ZeroIntensity · 2026-02-11T13:31:16Z

Doc/howto/asyncio-chat-server.rst

+Adding an idle timeout
+======================
+
+To disconnect clients who have been idle for too long, wrap the read call in
+:func:`asyncio.timeout`.  This async context manager takes a duration in
+seconds.  If the enclosed ``await`` does not complete within that time, the
+operation is cancelled and :exc:`TimeoutError` is raised.  This frees server
+resources when clients connect but stop sending data.
+
+Replace the message loop in ``handle_client`` with::


This section should go above the complete example, and then the timeout code should be in the full code.

ZeroIntensity · 2026-02-11T13:36:46Z

Doc/howto/asyncio-chat-server.rst

+Before building the chat server, let's start with something simpler: an echo
+server that sends back whatever a client sends.
+
+The core of any asyncio network server is :func:`asyncio.start_server`.  You
+give it a callback function, a host, and a port.  When a client connects,
+asyncio calls your callback with two arguments: a
+:class:`~asyncio.StreamReader` for receiving data and a
+:class:`~asyncio.StreamWriter` for sending data back.  Each connection runs
+as its own coroutine, so multiple clients are handled concurrently.


It would be nice if we provided a small example of this before diving into the full echo server. We should start with something small, and then slowly build on that as we introduce concepts to the user.

ZeroIntensity · 2026-02-11T13:37:58Z

Doc/howto/asyncio-chat-server.rst

+The :meth:`~asyncio.StreamWriter.write` method buffers data without sending
+it immediately.  Awaiting :meth:`~asyncio.StreamWriter.drain` flushes the
+buffer and applies back-pressure if the client is slow to read.  Similarly,
+:meth:`~asyncio.StreamWriter.close` initiates shutdown, and awaiting
+:meth:`~asyncio.StreamWriter.wait_closed` waits until the connection is
+fully closed.
+
+Using the server as an async context manager (``async with server``) ensures
+it is properly cleaned up when done.  Calling
+:meth:`~asyncio.Server.serve_forever` keeps the server running until the
+program is interrupted.  Finally, :func:`asyncio.run` starts the event loop
+and runs the top-level coroutine.


Same here -- let's introduce both these concepts with their own examples.

ZeroIntensity · 2026-02-11T13:39:22Z

Doc/howto/asyncio-chat-server.rst

+   asyncio.run(main())
+
+To test, run the server in one terminal and connect from another using ``nc``
+(or ``telnet``):


Why is this in parentheses?

Suggested change

(or ``telnet``):

or ``telnet``:

ZeroIntensity · 2026-02-11T13:41:41Z

Doc/howto/asyncio-chat-server.rst

+We store each connected client's name and :class:`~asyncio.StreamWriter` in a
+module-level dictionary.  When a client connects, ``handle_client`` prompts for
+a name and adds the writer to the dictionary.  A ``finally`` block ensures the
+client is always removed on disconnect, even if the connection drops
+unexpectedly.


This is introduced as a solution, but we didn't explain the problem. Why do we need to store writers? Why do we need to remove them?

ZeroIntensity · 2026-02-11T13:42:54Z

FTR, you don't have to say "I have made the requested changes" unless someone actually requested changes. You can just re-request a review.

pythongh-79012: Add asyncio chat server HOWTO

61b700c

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

kovan requested review from 1st1, asvetlov, kumaraditya303 and willingc as code owners February 8, 2026 20:21

bedevere-app bot added the awaiting review label Feb 8, 2026

bedevere-app bot mentioned this pull request Feb 8, 2026

Asyncio Tutorial #79012

Closed

bedevere-app bot added docs Documentation in the Doc dir skip news labels Feb 8, 2026

github-project-automation bot added this to Docs PRs Feb 8, 2026

github-project-automation bot moved this to Todo in Docs PRs Feb 8, 2026

ZeroIntensity self-requested a review February 9, 2026 11:59

ZeroIntensity reviewed Feb 10, 2026

View reviewed changes

bedevere-app bot added awaiting change review and removed awaiting review labels Feb 10, 2026

ZeroIntensity reviewed Feb 10, 2026

View reviewed changes

Doc/howto/asyncio-chat-server.rst Outdated Show resolved Hide resolved

Doc/howto/asyncio-chat-server.rst Outdated Show resolved Hide resolved

Doc/howto/asyncio-chat-server.rst Show resolved Hide resolved

Doc/howto/asyncio-chat-server.rst Show resolved Hide resolved

ZeroIntensity reviewed Feb 11, 2026

View reviewed changes

		one at a time. :func:`contextlib.suppress` silently handles any
		:exc:`ConnectionError` from clients that have already disconnected::

	Each message you type is broadcast to all other connected users.
	Each message you type is broadcasted to all other connected users.

Uh oh!

gh-79012: Add asyncio chat server HOWTO #144604

Are you sure you want to change the base?

gh-79012: Add asyncio chat server HOWTO #144604

Conversation

kovan commented Feb 8, 2026 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kovan commented Feb 10, 2026

Uh oh!

bedevere-app bot commented Feb 10, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kovan commented Feb 10, 2026

Uh oh!

bedevere-app bot commented Feb 10, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ZeroIntensity commented Feb 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

kovan commented Feb 8, 2026 •

edited by github-actions bot

Loading