asyncio: Transports Move Bytes, Protocols Decide Which Bytes

Why it exists

Transports and Protocols exist to provide a high-performance, callback-based abstraction over raw network and inter-process communication (IPC). They allow library authors to build efficient protocols, like HTTP or a database driver, without managing non-blocking sockets and the event loop manually, while still achieving maximum control.

The mental model

A Transport is the delivery mechanism; it's concerned with how bytes are transmitted over a channel like TCP or a subprocess pipe. A Protocol is the application logic; it determines which bytes to send and how to interpret incoming bytes. There is always a one-to-one relationship: the Protocol calls transport.write() to send data, and the Transport calls the Protocol's data_received() method with incoming data.

How it works

You don't instantiate these classes directly. Instead, you use a low-level event loop method like loop.create_connection(), passing it a protocol_factory (a callable that returns a Protocol instance). The event loop creates the appropriate Transport and links it to your Protocol. Communication is callback-driven. For example, when data arrives on the socket, the event loop calls the transport, which in turn calls your protocol's data_received(data) method. This is fundamentally different from the async/await style of high-level stream APIs.

When to use it

Only when building a networking library or framework from the ground up. If you were implementing a client for a protocol like Redis (RESP) or a custom RPC system, these primitives would offer the necessary performance and control over the byte stream and connection lifecycle.

When not to use it

In almost all application code. Using Transports and Protocols directly is a common footgun. For standard TCP communication, use asyncio.open_connection(), which provides a StreamReader and StreamWriter for use with async/await. For HTTP, use a dedicated library like httpx or aiohttp. These higher-level APIs are safer, easier to reason about, and built upon transports and protocols for you.

One canonical example

A simple TCP echo server. Its Protocol class would define a connection_made(transport) method to store the transport, and a data_received(data) method that simply calls self.transport.write(data). The server itself would be started with loop.create_server(), passing it a factory that creates instances of this echo protocol for each new client connection.