WebSocket support

MicroPie includes first‑class support for WebSockets. WebSockets are a persistent, bidirectional communication channel over a single TCP connection. They enable real‑time applications such as chat, live notifications and collaborative editing.

Mapping WebSocket routes

WebSocket handlers live on the same App subclass that serves your HTTP routes. The naming convention is similar to HTTP handlers, but with a ws_ prefix. For example, a method called ws_chat handles WebSocket connections at /chat. If the path is empty, ws_index handles the root WebSocket route.

When a WebSocket connection is initiated, MicroPie constructs a WebSocket object and passes it as the first argument to your handler, along with any path or query parameters. A typical handler must call accept() to accept the connection and then use receive_text() and send_text() (or their bytes counterparts) to communicate.

Example: echo server

The example below implements a simple echo server. The server accepts the WebSocket connection and then echoes back whatever text it receives. When the client disconnects, the handler finishes.

from micropie import App, ConnectionClosed

class MyApp(App):
    async def ws_echo(self, ws):
        # Accept the connection before receiving or sending messages.
        await ws.accept()
        while True:
            try:
                message = await ws.receive_text()
            except ConnectionClosed:
                # Client closed the connection
                break
            # Send the same message back to the client
            await ws.send_text(f"Echo: {message}")

app = MyApp()

To test this endpoint, run your application and connect to ws://127.0.0.1:8000/echo using a WebSocket client. Most modern browsers support WebSockets via JavaScript.

Accessing query and path parameters

Just like HTTP handlers, WebSocket handlers receive path and query parameters. Additional positional arguments come from the path, and keyword arguments are filled from the query string or session. For example:

class MyApp(App):
    async def ws_greet(self, ws, name="Guest"):
        await ws.accept()
        await ws.send_text(f"Hello {name}!")
        await ws.close()

Connecting to ws://localhost:8000/greet/Alice sends back "Hello Alice!". Connecting to ws://localhost:8000/greet?name=Bob sends "Hello Bob!". See WebSocket class for the complete API of the WebSocket class.

Integrating Socket.IO

MicroPie focuses on the core WebSocket protocol. If you need more advanced real‑time features—automatic reconnection, broadcasting, or fallback transports such as polling—you can integrate python‑socketio. See the examples/socketio directory in the MicroPie source distribution for sample code and instructions. When integrating Socket.IO, you still run your MicroPie application behind an ASGI server and attach the Socket.IO server as additional middleware or route.