Streams and Protocols

## The two objects `asyncio.open_connection(host, port)` is a coroutine function. Awaiting it opens a TCP connection and gives you back exactly two objects: * an `asyncio.StreamReader` — the **read** side. Everything on it is a coroutine, because bytes may not have arrived yet: `await reader.read(n)`, `await reader.readline()`, `await reader.readexactly(n)`, `await reader.readuntil(sep)`. * an `asyncio.StreamWriter` — the **write** side. `writer.write(data)` and `writer.writelines(chunks)` are ordinary synchronous methods; only `await writer.drain()` and `await writer.wait_closed()` are coroutines. That asymmetry is the single most useful thing to remember. Reading genuinely has to wait for the peer, so it suspends. Writing never waits: the bytes are appended to the transport's write buffer and the event loop flushes them to the socket when the socket becomes writable. `write()` therefore cannot fail with "would block" and cannot apply backpressure on its own — that is what `drain()` is for. ## The server side `asyncio.start_server(client_connected_cb, host, port)` is the mirror image. It returns an `asyncio.Server`. Every time a client connects, asyncio creates a fresh `StreamReader`/ `StreamWriter` pair and schedules your callback with them as its two arguments. The callback is normally an `async def` coroutine function; asyncio wraps each invocation in its own task, so every connection is handled concurrently without you creating threads. A common misreading is that `start_server` blocks. It does not — awaiting it only binds the listening socket and starts accepting. To keep the process alive you either `await server.serve_forever()` or keep the enclosing coroutine alive some other way. `async with server:` closes the listening socket on exit. ## Closing correctly `writer.close()` is synchronous and only *requests* the close: it tells the transport to flush what it can and then shut the socket down. The connection is not gone when it returns. `await writer.wait_closed()` is what actually waits for the underlying transport to finish closing and re-raises any error that happened on the way out. Skipping it in a short-lived script usually "works", which is exactly why it becomes a habit — and then in a long-running process you get sockets in a half-closed state, `ResourceWarning`s at interpreter shutdown, and data written just before the close that never left the buffer. On the server object the same two-step applies: `server.close()` stops accepting new connections, and `await server.wait_closed()` waits. Python 3.13 added `asyncio.Server.close_clients()` and `asyncio.Server.abort_clients()` for the case where you also want to tear down the connections that are already open rather than waiting for handlers to finish on their own. ## What is underneath Streams are a façade. Underneath sits asyncio's transport/protocol layer: a transport owns the socket and the write buffer, and a protocol receives callbacks. `open_connection` builds a protocol that pushes incoming bytes into the `StreamReader`'s internal buffer and wakes whichever coroutine is awaiting a read. You rarely need to know that to use streams, but it explains why a `StreamReader` has no `write` and a `StreamWriter` has no `read`: they are two views on one connection, not two connections. ## Errors and timeouts belong to the caller Neither `open_connection` nor the reader and writer carry a timeout of their own. A read against a peer that connected and then went silent waits forever, which in a long-running process is indistinguishable from a hang. Wrapping the read in `async with asyncio.timeout(...)` is the caller's job, as is deciding what a timeout means for that connection — usually closing it, because a half-consumed stream cannot be reused. Connection failures surface where you would expect: `open_connection` raises `OSError` and its subclasses such as `ConnectionRefusedError`, and a mid-stream failure raises `ConnectionResetError` from a read or from `await writer.drain()`. ## Typical shape A client is usually: connect, write a request, `drain`, read a framed response, close, wait closed — wrapped in `try/finally` so the close happens even when the read raises. A server handler is usually a loop reading one framed request at a time until the reader hits EOF (a read returning `b""`), writing a reply per request, and closing in a `finally`. ## What interviewers listen for Three things, in order: that you know `write()` is not awaited; that you know reads must be *framed* (a `read(n)` can return fewer than `n` bytes, so you use `readline`/`readexactly`/ `readuntil` when you need a message boundary); and that close is `close()` **then** `await wait_closed()`. A candidate who awaits `write()` or who thinks `close()` is sufficient has not run this code against a real peer.