larzws 0.1.0

WebSockets in pure Python — RFC 6455 server and client with framing, masking, ping/pong, and fragmentation. No async, zero dependencies.

larzws

WebSockets in pure Python. Zero dependencies.

A real RFC 6455 WebSocket server and client with nothing to install — no websockets, no aiohttp, no async runtime. Handshake, framing, masking, fragmentation, ping/pong, and close are handled; you just send and receive.

from larzws import serve, connect

# server — echo
def handler(ws):
    for message in ws:                 # iterate messages until the client leaves
        ws.send("echo: " + message)
serve(handler, "127.0.0.1", 8765)

# client
ws = connect("ws://127.0.0.1:8765")
ws.send("hello")
print(ws.recv())                       # "echo: hello"
ws.close()

What makes it different

• No async, no dependency. Most WebSocket libraries drag in an async stack. larzws is plain sockets + threads — drop it into any script or service.
• Server and client, both real. Full RFC 6455: the Upgrade handshake, binary framing with 7/16/64-bit lengths, client-side masking, fragmentation reassembly, automatic ping→pong, and clean close.
• Text and binary. str messages go as text frames, bytes as binary; you get back the right type.
• Easy to embed. Threaded server (one thread per connection) with start_background() for tests and apps.

Pairs naturally with larzrpc for realtime request/response over a socket.

Install

pip install larzws

Server

from larzws import WebSocketServer, serve

def handler(ws):
    ws.send("welcome")
    for message in ws:
        ws.send("you said: " + message)

serve(handler, "0.0.0.0", 8765)          # blocking

# or embed it
server = WebSocketServer("127.0.0.1", 8765, handler)
server.start_background()                # daemon thread; server.port is resolved
...
server.shutdown()

Client

from larzws import connect

ws = connect("ws://127.0.0.1:8765/chat")
ws.send("hi")               # text
ws.send(b"\x00\x01")        # binary
msg = ws.recv()             # str or bytes, or None when closed
for msg in ws:              # or iterate until close
    ...
ws.ping()
ws.close()

Scope

larzws speaks plain ws:// (not wss:///TLS in this version — terminate TLS at a reverse proxy if you need it) and uses a thread per connection, which is ideal for tools, internal services, dashboards, and realtime features up to moderate concurrency. For tens of thousands of idle connections you'd want an async library; for everything else, this is refreshingly simple.

Tests

python -m unittest discover -s tests -v   # 14 tests: RFC handshake, framing, e2e echo

The Larz stack

Pure-Python, zero-dependency building blocks: larz · larzchain · larzmoney · larzcrypt · larzdb · larzagent · larzchart · larzmark · larztask · larzvault · larzvm · larzcache · larzvalidate · larzid · larzrpc · larzstate · larzhttp · larzconf · larzcron · larzlimit · larzlog · larzcli · larzretry · larztime · larzpdf · larzpack · larztemplate · larzcolor · larztable · larzjson · larzbus · larzmigrate · larzgraph · larzws

License

MIT © larz-scripter