Skip to content
Tutorials Center
My learning

Topics

Lesson 23 of 40 ยท Networking and Streams

A TCP Echo Server and Client with asyncio

Build a TCP echo server and client with asyncio.start_server and open_connection: handlers, many clients at once, graceful shutdown and a runnable in-memory demo.

The classic first network program is an echo server: whatever a client sends, the server sends back. It is small, but it contains every moving part of a real asyncio server: a handler coroutine per connection, concurrency between clients, error handling and clean shutdown.

You will first read the real-socket version, which you can run on your own machine, and then run the same handler code in the browser against an in-memory stand-in for the network.

The real server

Python
import asyncio

async def handle_client(reader, writer):
    peer = writer.get_extra_info("peername")
    print("connected:", peer)
    try:
        while data := await reader.readline():
            writer.write(data)
            await writer.drain()
    except ConnectionError:
        pass                      # the client vanished; nothing to do
    finally:
        writer.close()
        await writer.wait_closed()
        print("disconnected:", peer)

async def main():
    server = await asyncio.start_server(handle_client, "127.0.0.1", 8888)
    addresses = ", ".join(str(s.getsockname()) for s in server.sockets)
    print("listening on", addresses)
    async with server:
        await server.serve_forever()

asyncio.run(main())

asyncio.start_server(callback, host, port) binds the port and returns a Server. For every incoming connection the event loop creates a new task running handle_client(reader, writer). That single sentence is why asyncio servers scale so well: a thousand idle clients are a thousand suspended tasks, each costing a few kilobytes, and none blocks the others.

Points worth noting:

  • The handler can be a plain function or a coroutine function; use a coroutine so you can await.
  • When the handler returns, asyncio does not close the writer for you in all cases, so close it yourself in finally.
  • Use host="127.0.0.1" while developing, which accepts only local connections. "0.0.0.0" listens on every network interface.
  • port=0 asks the operating system for a free port; read it back from server.sockets[0].getsockname().
  • serve_forever() runs until the task is cancelled. Leaving the async with server: block closes the listening sockets.

The real client

Python
import asyncio

async def echo_client(message: str) -> str:
    reader, writer = await asyncio.open_connection("127.0.0.1", 8888)
    writer.write(message.encode() + b"\n")
    await writer.drain()
    reply = await reader.readline()
    writer.close()
    await writer.wait_closed()
    return reply.decode().rstrip()

print(asyncio.run(echo_client("hello")))

Because every call is awaited, you can start many clients at once with asyncio.gather, each on its own connection.

Running it in the browser

The sandbox cannot open sockets, so here is a tiny MemoryServer. Its open_connection() method mimics asyncio.open_connection(): it makes a fresh in-memory connection and starts your handler task on the server side, the same thing start_server does for every accepted socket. Your handler code is unchanged.

Python Echo server with three clients

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The output interleaves the three clients because they genuinely run at the same time on one thread: whenever a handler waits for the next line, the loop switches to another.

A protocol with state: the handler as a conversation

A handler is a coroutine, so a conversation reads like straight-line code. Compare this with callback-style servers, where the "state" of each client lives in a class with half a dozen flags. Here the state is simply where the code currently is.

Python A tiny command server

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Graceful shutdown

A production server should stop accepting new clients and let existing ones finish. The usual recipe:

Python
server.close()                  # stop listening
await server.wait_closed()      # wait for the listening sockets to close
# then cancel or await your own handler tasks (see the cancellation lessons)

On Python 3.12 and later, wait_closed() also waits for active connections to finish, so a long-lived client can hold shutdown up. Keep a set of handler tasks if you need to cancel them yourself; cancelling tasks shows how, and timeouts shows how to put a deadline on a client that never sends data.

Common mistakes

  • Forgetting drain(): the buffer grows if a client reads slowly. See flow control.
  • Blocking the loop in a handler (a long calculation or time.sleep): every other client freezes. Move heavy work out as described in running blocking code.
  • Letting one client's exception kill the server: exceptions in a handler end only that handler's task, but they are logged noisily; catch the errors you expect.
  • No read timeout: a silent client holds a task and a socket forever. Wrap reads in asyncio.timeout().

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does asyncio.start_server() do for every client that connects?

    Each accepted connection gets its own task running your handler, so clients are served concurrently on one thread.
  2. 2. What does port=0 mean in start_server()?

    Port 0 requests an ephemeral port; read the real one with server.sockets[0].getsockname().
  3. 3. Which statement about the handler is correct?

    Close the writer yourself so resources are released even when the handler raises.
  4. 4. Why can a handler containing time.sleep(5) harm a server?

    time.sleep is blocking, so nothing else on the loop can run for five seconds. Use asyncio.sleep or move the work to a thread.

Summary

  • start_server() calls your handler once per connection, each in its own task; open_connection() is the client side.
  • Handlers read like a conversation: await a line, decide, write, drain.
  • Close the writer in finally, set timeouts on reads, and never block the loop.
  • In the browser the same handler runs against an in-memory connection; on your computer it runs against real sockets.

Next: Protocols and transports