Understanding websockets asyncio ServerConnection: why IDEs miss recv/send and how type hints help

Learn what the handler websocket is in Python websockets asyncio servers: ServerConnection. Fix IDE autocomplete for recv() and send() with precise type hints.

When you work with the Python websockets library, a common early stumbling block is understanding what the connection object actually is in an asyncio server and why an IDE sometimes fails to see methods like .recv() and .send(). The confusion grows when you notice multiple import paths for ServerConnection. Here’s a concise walkthrough that clarifies the type behind the handler’s websocket parameter and resolves IDE recognition issues without changing how your server behaves.

Minimal server that triggers the question

The following example starts an asyncio-based WebSocket server and echoes a friendly greeting. The code is intentionally compact and uses the standard serve entry point:

import asyncio
from websockets.asyncio.server import serve
async def greeter(sock):
    label = await sock.recv()
    print(f"<<< {label}")
    reply = f"Hello {label}!"
    await sock.send(reply)
    print(f">>> {reply}")
async def run():
    async with serve(greeter, "localhost", 8765) as app:
        await app.serve_forever()
if __name__ == "__main__":
    asyncio.run(run())

The logic is straightforward: read a message from the client with .recv(), build a response, and push it back via .send(). The friction typically appears in the editor: autocompletion or static analysis might not “know” that sock is a WebSocket connection and therefore doesn’t suggest .recv() and .send().

What the websocket parameter actually is

In an asyncio server created with websockets.asyncio.server.serve, the first argument of your handler is the connection object to the client. Concretely, that parameter is an instance of websockets.asyncio.server.ServerConnection. The .recv() and .send() methods are defined on this class and are the standard way to receive and send messages.

If an IDE doesn’t recognize these methods on your variable, it’s because it doesn’t know the variable’s type. The code runs fine, but without a type hint the static analyzer often can’t infer that sock is a ServerConnection instance.

Why there are multiple import paths for ServerConnection

You may encounter several ways to import ServerConnection: websockets.ServerConnection, websockets.server.ServerConnection, and websockets.asyncio.server.ServerConnection. These do not represent different types in this context. They exist because the library re-exports ServerConnection in multiple __init__.py files, making it available through several module paths. For an asyncio server created via serve, the concrete class is websockets.asyncio.server.ServerConnection, and the other paths are simply alternative import routes to the same class. Using any of them will not change behavior.

Solution: give the IDE a precise type

To help the IDE, annotate the handler parameter with the correct type. This keeps the runtime behavior exactly the same while enabling completions and method recognition.

import asyncio
from websockets.asyncio.server import serve, ServerConnection
async def greeter(peer: ServerConnection):
    nickname = await peer.recv()
    print(f"<<< {nickname}")
    message = f"Hello {nickname}!"
    await peer.send(message)
    print(f">>> {message}")
async def run():
    async with serve(greeter, "localhost", 8765) as srv:
        await srv.serve_forever()
if __name__ == "__main__":
    asyncio.run(run())

This slight addition makes it explicit that peer is a ServerConnection, which unlocks IDE features without altering the server’s logic.

Why it’s worth knowing

Understanding that the handler parameter is a ServerConnection and that multiple module paths re-export the same class helps you avoid dead ends when reading docs or exploring the codebase. It also clarifies that IDE complaints here are about missing type information, not about missing methods at runtime. With a proper annotation in place, you get better autocompletion and more accurate static checks, making the development loop smoother.

Takeaways

When using websockets.asyncio.server.serve, treat the first handler parameter as a websockets.asyncio.server.ServerConnection. The .recv() and .send() methods belong to that class. The various import paths you might see just re-export the same type, so behavior does not change depending on which one you import. If an IDE doesn’t recognize the methods, add a type hint to the handler argument to make the connection’s API visible during editing, while leaving the runtime behavior intact.