Skip to content

PyStrands

A lightweight, framework-agnostic real-time communication library for Python applications.

What is PyStrands?

PyStrands provides a client-server architecture for building real-time features without the complexity. A Go-based WebSocket broker handles client connections, while Python backends process messages via TCP — enabling horizontal scaling and clean separation of concerns.

WebSocket Clients ←→ Go Broker ←TCP→ Python Backends

✨ Features

  • Sync & Async clients — Choose between PyStrandsClient (threading) and AsyncPyStrandsClient (asyncio)
  • Room-based messaging — Organize clients into rooms for targeted communication
  • Private & broadcast messaging — Send to specific clients or broadcast to everyone
  • Connection request handling — Authenticate and route clients on connect
  • Auto-reconnect — Built-in exponential backoff for resilient connections
  • Message queuing — Go broker buffers messages when backends are down
  • Framework-agnostic — Works with Flask, FastAPI, Django, or standalone
  • Production tested — 66 tests including real-world production scenarios

🚀 Quick Install

pip install pystrands

🔧 Quick Start

import asyncio
from pystrands import AsyncPyStrandsClient

class ChatBackend(AsyncPyStrandsClient):
    async def on_connection_request(self, request):
        request.context.room_id = request.url.strip("/")
        return True

    async def on_message(self, message, context):
        await self.send_room_message(context.room_id, f"echo: {message}")

client = ChatBackend(host="localhost", port=8081)
asyncio.run(client.run_forever())

from pystrands import PyStrandsClient

class ChatBackend(PyStrandsClient):
    def on_connection_request(self, request):
        request.context.room_id = request.url.strip("/")
        return True

    def on_message(self, message, context):
        self.send_room_message(context.room_id, f"echo: {message}")

client = ChatBackend(host="localhost", port=8081)
client.run_forever()

🏗️ Architecture Overview

┌──────────┐     WebSocket     ┌──────────┐      TCP       ┌──────────────┐
│  Browser  │ ←──────────────→ │ Go Broker │ ←────────────→ │ Python Backend│
│  Client   │                  │           │                │  (your code)  │
└──────────┘                   │  Queue:   │                └──────────────┘
                               │  [msg1]   │                ┌──────────────┐
                               │  [msg2]   │ ←────────────→ │ Python Backend│
                               │  [msg3]   │                │  (replica 2)  │
                               └──────────┘                └──────────────┘
- :material-rocket-launch: **Get Started** --- Install PyStrands and build your first real-time backend in minutes. [→ Getting Started](getting-started.md) - :material-book-open: **Guides** --- Learn about architecture, authentication, and messaging patterns. [→ Architecture](guide/architecture.md) - :material-code-braces: **API Reference** --- Complete API documentation for clients and context classes. [→ API Reference](api/client.md)

Requirements

  • Python >= 3.10

License

MIT — see GitHub repository for details.