SIMPLE-WEBSOCKET(1)

✨ SIMPLE-WEBSOCKET(1) ✨

okay bestie, sit down, hydrate, because we're talking about simple-websocket — that's the manual page name and also literally the whole vibe. it's a Simple WebSocket server and client for Python. that's it. that's the girl. 💖

---

🌸 GETTING STARTED 🌸

so simple-websocket ships a whole collection of WebSocket servers and clients for Python, and it's got your back whether you're on the traditional workflow or the async (asyncio) one. and the servers? designed so you can slot them into bigger web applications if you want to. main character energy, but make it modular. 🫶

🎀 Installation 🎀

you install this package with pip, no biggie:

pip install simple-websocket

🦋 Server Example #1: Flask 🦋

here's how you add a WebSocket route to a Flask application, look at her go:

from flask import Flask, request
from simple_websocket import Server, ConnectionClosed

app = Flask(__name__)

@app.route('/echo', websocket=True)
def echo():
    ws = Server.accept(request.environ)
    try:
        while True:
            data = ws.receive()
            ws.send(data)
    except ConnectionClosed:
        pass
    return ''

ngl, integrating with web applications that use other WSGI frameworks works basically the same way. the only requirement is that you pass the environ dictionary to the Server.accept() method to kick off the WebSocket handshake. that's the whole rule. periodt. 💅

🌈 Server Example #2: Aiohttp 🌈

and now, adding a WebSocket route to a web app built with the aiohttp framework:

from aiohttp import web
from simple_websocket import AioServer, ConnectionClosed

app = web.Application()

async def echo(request):
    ws = await AioServer.accept(aiohttp=request)
    try:
        while True:
            data = await ws.receive()
            await ws.send(data)
    except ConnectionClosed:
        pass
    return web.Response(text='')

app.add_routes([web.get('/echo', echo)])

if __name__ == '__main__':
    web.run_app(app, port=5000)

🧚 Server Example #3: ASGI 🧚

next up, an asynchronous application that supports the ASGI protocol:

from simple_websocket import AioServer, ConnectionClosed

async def echo(scope, receive, send):
    ws = await AioServer.accept(asgi=(scope, receive, send))
    try:
        while True:
            data = await ws.receive()
            await ws.send(data)
    except ConnectionClosed:
        pass

⭐ Client Example #1: Synchronous ⭐

this client can connect to any of the server examples above, and it does it with a synchronous interface:

from simple_websocket import Client, ConnectionClosed

def main():
    ws = Client.connect('ws://localhost:5000/echo')
    try:
        while True:
            data = input('> ')
            ws.send(data)
            data = ws.receive()
            print(f'< {data}')
    except (KeyboardInterrupt, EOFError, ConnectionClosed):
        ws.close()

if __name__ == '__main__':
    main()

💜 Client Example #2: Asynchronous 💜

and this next client is out here using Python's asyncio framework:

import asyncio
from simple_websocket import AioClient, ConnectionClosed

async def main():
    ws = await AioClient.connect('ws://localhost:5000/echo')
    try:
        while True:
            data = input('> ')
            await ws.send(data)
            data = await ws.receive()
            print(f'< {data}')
    except (KeyboardInterrupt, EOFError, ConnectionClosed):
        await ws.close()

if __name__ == '__main__':
    asyncio.run(main())

---

👑 API REFERENCE 👑

💫 The Server class 💫

💫 The AioServer class 💫

💫 The Client class 💫

💫 The AioClient class 💫

💫 Exceptions 💫

• Search Page

---

🍓 AUTHOR 🍓

Miguel Grinberg — iconic, we stan. 💖

---

🌸 COPYRIGHT 🌸

2021, Miguel Grinberg

---

aaaand that's the whole page bestie, no cap. this one's from the simple-websocket manual, Mar 04, 2025, and yeah the source/version stamp at the bottom says SIMPLE-WEBSOCKET(1) too, which is just her being consistent. go build something cute with it. 💅✨🎀🦋