Using asyncio for Network Programming

Using asyncio for Network Programming

An event loop is a traffic controller for work that would otherwise spend much of its time waiting. A network read may wait for a packet; a timer may wait for its deadline; a write may wait until a socket can accept more bytes. Rather than stop the whole program at each wait, the loop keeps track of what is ready and gives that work a turn.

In Python, asyncio tasks cooperate with the loop. When a coroutine reaches await, it can suspend while an operation is pending. The loop is then free to run another task. When the awaited operation completes, the suspended task becomes eligible to run again.

import asyncio

async def show(label, delay):
    print(label, "starts")
    await asyncio.sleep(delay)
    print(label, "finishes")

async def main():
    await asyncio.gather(
        show("A", 1.0),
        show("B", 0.2),
    )

asyncio.run(main())

Both coroutines start before either finishes. Task B resumes after its shorter delay, while task A remains suspended. That is concurrency without requiring a separate operating-system thread for each task. The loop can make progress on other work whenever a coroutine yields control at an await.

The crucial word is cooperates. An event loop cannot interrupt arbitrary Python code that runs too long without awaiting. If a coroutine performs a large calculation or calls a blocking function, it keeps the loop from serving every other task. A small experiment makes the problem visible:

import asyncio
import time

async def blocks_the_loop():
    print("blocking work starts")
    time.sleep(1)
    print("blocking work ends")

async def gets_a_turn():
    print("second task gets a turn")

async def main():
    await asyncio.gather(
        blocks_the_loop(),
        gets_a_turn(),
    )

asyncio.run(main())

Although blocks_the_loop is declared with async def, time.sleep is still blocking. The event loop cannot run gets_a_turn until the sleep returns. Use an asynchronous operation, such as await asyncio.sleep(1), when the work is naturally a wait. For blocking operations that have no asynchronous interface, move them to a thread or process rather than making the loop wait.

For network sockets, the loop’s traffic-control job is tied to readiness. It asks the operating system which sockets can be read or written without blocking. When a socket becomes readable, the loop can resume the task waiting for data; when it becomes writable, it can resume the task waiting to send. A task this is waiting for a socket does not occupy the loop continuously.

Each task therefore has a useful rhythm: run until it reaches an awaitable operation, suspend, and later resume when that operation has a result. The loop does not promise that a particular task will run immediately; it chooses among work that’s ready. Keep each stretch of ordinary Python execution short, and the controller has frequent chances to direct traffic elsewhere.

Coroutines and the flow of network data

A TCP connection is a stream of bytes, not a sequence of messages. If one program sends three pieces of data, the other program may receive them in one read, three reads, or several reads of different sizes. The boundaries chosen by the sender are not preserved by TCP. An application must define its own way to recognize where one unit of data ends and the next begins.

The stream interface in asyncio provides a reader and a writer. A coroutine can ask the reader for a line, a fixed number of bytes, or whatever data is currently available. If the requested data has not arrived, the coroutine suspends and lets the event loop run other tasks.

import asyncio

async def exchange(host, port):
    reader, writer = await asyncio.open_connection(host, port)

    writer.write(b"statusn")
    await writer.drain()

    response = await reader.readline()
    print(response.decode().rstrip())

    writer.close()
    await writer.wait_closed()

asyncio.run(exchange("127.0.0.1", 9000))

open_connection itself is awaited because establishing a connection can take time. The call returns a StreamReader and a StreamWriter once the connection is ready. The writer’s write method places bytes in an output buffer; it does not necessarily mean that those bytes have already crossed the network. drain waits when that buffer needs room, giving the event loop a chance to send data before the coroutine continues.

Reading a line works only when the other side uses a line-ending convention. The newline is a delimiter: it tells readline where the application’s next message ends. For binary protocols, a common alternative is a length prefix. First read a fixed-size header containing the length, then read exactly that many bytes.

async def read_message(reader):
    header = await reader.readexactly(4)
    length = int.from_bytes(header, "big")
    return await reader.readexactly(length)

async def write_message(writer, payload):
    header = len(payload).to_bytes(4, "big")
    writer.write(header + payload)
    await writer.drain()

readexactly may need to wait through several arrivals before it has all the requested bytes. If the peer closes the connection first, it raises asyncio.IncompleteReadError; the exception contains any partial data that was received. That is distinct from receiving an empty message, because a length-prefixed message of zero bytes still has a complete header.

Waiting for incoming data does not make the loop idle. While one coroutine is suspended in reader.readline or reader.readexactly, the loop can resume another connection’s writer, handle a timer, or run a task whose socket has become readable. The bytes move through the operating system’s socket buffers; the coroutine resumes when its particular read operation can make progress.

Output has a corresponding flow of its own. A peer may read slowly, or stop reading altogether. If a program keeps calling write without allowing the buffer to drain, queued data can grow in memory. Awaiting drain makes the producer yield when the transport applies backpressure, so sending speed can respond to the receiver’s ability to accept bytes.

Building a simple asynchronous server

A server reverses the direction of the connection. Instead of opening a connection to a known address, it binds a local address and waits for clients. With asyncio.start_server, the event loop watches the listening socket. When a client connects, the server creates a pair of streams and schedules the handler coroutine for that connection.

import asyncio

async def handle_client(reader, writer):
    address = writer.get_extra_info("peername")
    print("connection from", address)

    while line := await reader.readline():
        message = line.decode().rstrip()
        print("received:", message)

        reply = (message.upper() + "n").encode()
        writer.write(reply)
        await writer.drain()

    writer.close()
    await writer.wait_closed()
    print("connection closed:", address)

async def main():
    server = await asyncio.start_server(
        handle_client,
        "127.0.0.1",
        9000,
    )

    async with server:
        await server.serve_forever()

asyncio.run(main())

The handler is called once for each client, but the loop does not dedicate itself to that client. When reader.readline() waits for bytes, the handler suspends. The loop can then accept another connection or resume a different handler whose client has sent data. Several clients can therefore be connected simultaneously, even though each handler is written as a simpler sequence of operations.

The loop in handle_client ends when readline returns an empty byte string, which signals that the peer has closed its sending side. For each complete line, the handler transforms the text, queues a reply with write, and awaits drain before continuing. The newline remains part of the protocol: without it, readline would keep waiting for the end of the message.

The address passed to start_server determines which local interface accepts connections. The loopback address 127.0.0.1 permits connections from the same machine. A server intended to accept connections through its network interfaces can bind to 0.0.0.0, subject to the machine’s firewall and network configuration. The port, here 9000, identifies the listening service on that interface.

Once start_server has created the listening socket, serve_forever suspends the main coroutine while the server remains active. The async with block ensures that the server is closed when control leaves the block, including when the program is cancelled. Each client handler owns its writer and closes it after its input stream ends.

Handling timeouts and connection failures

A coroutine that waits forever can retain a task and its connection forever. A timeout puts a bound on that wait. In Python 3.11 and later, asyncio.timeout cancels the work inside its block when the deadline expires and raises TimeoutError outside the block.

async def read_request(reader):
    try:
        async with asyncio.timeout(10):
            return await reader.readline()
    except TimeoutError:
        return None

The deadline applies to the whole block, not to each individual operation within it. If the block contains several reads and processing steps, they share the same ten seconds. To give each read its own interval, place a separate timeout around each read. The older asyncio.wait_for(awaitable, seconds) form is also available, but it applies to one awaitable at a time.

A server can use an idle timeout to release a client that connects but sends nothing. It should also distinguish an orderly end of stream from a timeout and from an error while reading. The following handler closes its writer in every case, including when its task is cancelled.

async def handle_client(reader, writer):
    address = writer.get_extra_info("peername")

    try:
        while True:
            try:
                async with asyncio.timeout(30):
                    line = await reader.readline()
            except TimeoutError:
                print("idle timeout:", address)
                break

            if not line:
                print("peer closed:", address)
                break

            writer.write(line.upper())
            await writer.drain()

    except (ConnectionResetError, BrokenPipeError) as error:
        print("connection failed:", address, error)

    finally:
        writer.close()
        try:
            await writer.wait_closed()
        except (ConnectionResetError, BrokenPipeError):
            pass

Cancellation is not an ordinary connection error. It’s how the event loop can stop a task, including one whose timeout has expired. Cleanup belongs in a finally block, but a handler should generally allow asyncio.CancelledError to propagate after cleanup rather than treat cancellation as a successful request. Catching every exception with a bare except can conceal shutdown signals and programming errors.

Connection establishment can fail too. The destination may refuse the connection, the name may not resolve, or the attempt may take longer than the application permits. A timeout around open_connection bounds the wait, while operating-system connection errors remain distinct exceptions.

async def connect_to_service(host, port):
    try:
        async with asyncio.timeout(5):
            return await asyncio.open_connection(host, port)
    except TimeoutError:
        print("connection attempt timed out")
    except OSError as error:
        print("connection attempt failed:", error)

    return None

After a connection has been established, a read can fail because the peer closes partway through a message. For a length-prefixed protocol, readexactly reports that condition with IncompleteReadError; its partial attribute holds the bytes already received, and expected records the requested length.

async def receive_message(reader):
    try:
        header = await reader.readexactly(4)
        length = int.from_bytes(header, "big")
        return await reader.readexactly(length)
    except asyncio.IncompleteReadError as error:
        print(
            "truncated message:",
            len(error.partial),
            "of",
            error.expected,
            "bytes",
        )
        return None

A timeout or failed connection should affect the task that owns that operation, not freeze the event loop. Keeping the exception handling close to the awaited network operation makes it clear whether the program is dealing with an expired deadline, a peer that ended its stream, or an operating-system error.

Comments

No comments yet. Why don’t you start the discussion?

Leave a Reply

Your email address will not be published. Required fields are marked *