asyncio Streams: Reader, Writer, and TCP addresses a recurring problem in Python projects: Read and write asynchronous TCP protocols with high-level APIs and explicit bounds. This guide explains the mechanism, provides an executable example, and identifies the boundaries that keep an implementation reliable.
Concept and use case
open_connection returns a reader and writer. The reader supports line or sized reads; the writer buffers output and drain provides flow control.
For the related fundamentals, also read the async and await guide. Integration stays simpler when functions receive dependencies and data explicitly instead of relying on global state.
Practical example
import asyncio
async def fetch(host: str, port: int) -> bytes:
reader, writer = await asyncio.open_connection(host, port)
try:
writer.write(b"PING\n")
await writer.drain()
return await reader.readline()
finally:
writer.close()
await writer.wait_closed()Define protocol framing, limit messages, and put timeouts around connections and reads. Always close and await wait_closed.
Important decisions
The correct choice depends on the public contract, expected volume, and failure behavior.
Consider concurrency, empty inputs, and partial failures. Document every limit that affects consumers and choose names that express intent.
Common mistakes
A minimal example does not replace bounds, error handling, and observability. read may wait forever when a peer violates the protocol. Skipping drain grows buffers; assuming one read equals one message misunderstands TCP.
Avoid catching exceptions without context or returning partial output as if it were complete. An explicit failure is usually safer than silently incorrect data.
How to validate
Validate behavior, not only the happy path. Test fragmented messages, several messages in one packet, mid-message disconnects, and input above the limit.