Loading repository data…

mr_wshandler_fastapi GitHub Details, Stars and Alternatives | OpenRepoFinder

moeezraza35 / repository

mr_wshandler_fastapi

A lightweight, reusable WebSocket handler for Fast-API that simplifies connection management, broadcasting, and client‑specific messaging. Reduce boilerplate and build real‑time features (chat, notifications, live updates) in minutes.

#fastapi#python#real-time#socket-server#websocket

View Repository on GitHub ↗

REPOSITORY OVERVIEW

Live repository statistics

★ 0Stars

⑂ 0Forks

◯ 0Open issues

◉ 0Watchers

56/100

OPENREPOHUB HEALTH SIGNAL

Mixed signals

A transparent discovery signal based on current public GitHub metadata.

Recent activity35% weight

Community adoption25% weight

Maintenance state20% weight

100

License clarity10% weight

100

Project information10% weight

This score does not audit code, security, maintainers, documentation quality, or suitability. Verify the repository and its current documentation before adoption.

README preview

MR WS Handler for FastAPI

A lightweight, reusable WebSocket handler for FastAPI – developed by Moeez Raza.

The goal of this project is to make using WebSockets in FastAPI easier, simpler, and faster. Stop copying connection‑management code between projects. Just install, import, and focus on your real‑time logic.

✨ Features

✅ Simple connection manager – automatically handles accept, store, and disconnect.
✅ Broadcast to all connected clients – one line to send a message to everyone.
✅ Send to specific client ID – direct messaging with integer or string IDs.
✅ Room support – group clients into rooms and send messages to a room only.
✅ Multiple message types – str, bytes, dict (auto‑converted to JSON via send_message).
✅ Flexible endpoint modes – choose mode="str", "bytes", or "dict" for incoming messages.
✅ Lifecycle decorators – @onopen and @onclose callbacks for connection events.
✅ Ready‑to‑use HTML/JS test client – full UI to test connections, client IDs, and rooms.
✅ Fully async – built for high‑performance FastAPI apps.
✅ Global connection manager – a single connectionManager instance, accessible anywhere.
✅ Reusable – publish to PyPI and pip install in any project.

📦 Installation

pip install mr-wshandler-fastapi

Or install directly from GitHub:

pip install git+https://github.com/moeezraza35/mr_wshandler_fastapi.git

🚀 Quick Start

Run the demo (easiest way to test)

Clone the repository and run the included demo server:

git clone https://github.com/your-username/mr_wshandler_fastapi.git
cd mr_wshandler_fastapi
python -m venv venv
source venv/bin/activate  # or venv\Scripts\activate on Windows
pip install -r requirements.txt
python demo/main.py

@ws.onopen
async def on_open(websocket: WebSocket):
    print(f"New client connected: {websocket}")

@ws.onclose
async def on_close(websocket: WebSocket):
    print(f"Client disconnected")

Method	Description
`async connect(websocket: WebSocket)`	Accepts the WebSocket and stores the connection. Called automatically by `@ws.endpoint`.
`async disconnect(websocket: WebSocket)`	Closes the WebSocket (server‑initiated) and removes it from the manager.
`async remove_connection(websocket: WebSocket)`	Removes a connection without closing it – used when the client has already disconnected.
`async set_client_id(websocket: WebSocket, clientId: int \| str)`	Assigns a unique identifier to a connection (e.g., user ID, session ID) default is `0`.

Method	Description
`async send_message(message: str \| bytes \| dict, websocket: WebSocket)`	Core sender – automatically handles the message type (string → `send_text`, bytes → `send_bytes`, dict → `send_json`). Used internally by all other send methods.
`async send_message_to_connection(...)`	Alias for `send_message`. Sends a message to a specific connection.
`async send_message_to_client_id(message, clientId: int \| str)`	Looks up the connection by `clientId`, then calls `send_message` to deliver the message.
`async broadcast(message: str \| bytes \| dict)`	Iterates over all active connections and calls `send_message` for each one.

Method	Description
`add_client_id_to_room(clientId: int \| str, room: str)`	Adds a client (by ID) to a room.
`remove_client_id_from_room(clientId: int \| str, room: str)`	Removes a client from a room.
`add_connection_to_room(websocket: WebSocket, room: str)`	Adds a connection (by WebSocket object) to a room.
`remove_connection_from_room(websocket: WebSocket, room: str)`	Removes a connection from a room.
`async send_message_to_room(message: str \| bytes \| dict, room: str)`	Iterates over all connections in the given room and calls `send_message` for each one.

# Inside your WebSocket callback
connectionManager.add_connection_to_room(websocket, "general")
await connectionManager.send_message_to_room("Hello room!", "general")

from mr_wshandler import WSHandler, connectionManager

ws = WSHandler()

@ws.onopen
async def onopen(websocket):
    print("New connection")

@ws.endpoint(mode="dict")
async def onMessage(data: dict, websocket: WebSocket):
    if "room" in data:
        # Join a room
        connectionManager.add_connection_to_room(websocket, data["room"])
        await connectionManager.send_message_to_room(f"{websocket} joined", data["room"])
    else:
        # Broadcast to all
        await connectionManager.broadcast(data)

python demo/main.py

mr_wshandler_fastapi

Live repository statistics

Mixed signals

README preview

MR WS Handler for FastAPI

✨ Features

📦 Installation

🚀 Quick Start

Run the demo (easiest way to test)

📚 API Reference

WSHandler

connectionManager (global instance)

Core Connection Management

Sending Messages

Room Management

Example:

Typical Usage Flow

🧪 Testing

🤝 Contributing

📄 License

🔗 References