Metadata-Version: 2.3
Name: fastapi-socketio-handler
Version: 0.1.0
Summary: Socket.IO wrapper for FastApi applications
License: MIT
Keywords: socketio,asyncio,websockets,python-socketio,asyncio-socketio,websockets-handler,fastapi
Author: Nazarii
Author-email: bandirom@ukr.net
Requires-Python: >=3.9
Classifier: Framework :: FastAPI
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Internet
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: fastapi
Requires-Dist: python-socketio[asyncio] (>=5.13.0,<6.0.0)
Requires-Dist: sqlalchemy (>=2.0.42,<3.0.0)
Project-URL: Homepage, https://github.com/bandirom/fastapi-socketio-handler
Project-URL: Repository, https://github.com/bandirom/fastapi-socketio-handler
Description-Content-Type: text/markdown

# fastapi-socketio-handler

**FastAPI + Socket.IO integration made modular, extensible and simple.**

A clean event-based wrapper that helps you organize your Socket.IO server logic using decorators, handlers, and namespaces — powered by `python-socketio`, `FastAPI`, and `asyncio`.

---

## 🔧 Features

- 📡 Socket.IO server for FastAPI apps
- 🧩 Handler registration via decorators
- 📁 Namespace-based routing
- 🔁 Redis pub/sub support (scaling)
- 💡 Typed, extensible, and testable architecture
- 🧪 Ready for pytest & async testing

---

## 📦 Installation

```shell
pip install fastapi-socketio-handler
```


## 🚀 Quick Start


### 1. Define a handler

```python
# app/chat_handler.py

from fastapi_socketio_handler import BaseSocketHandler, register_handler


@register_handler(namespace="/chat")
class ChatSocketHandlers(BaseSocketHandler):

    def register_events(self):
        self.sio.on("typing", self.event_typing, namespace=self.namespace)
        self.sio.on("stop_typing", self.event_stop_typing, namespace=self.namespace)

    async def connect(self, sid: str, environ: dict, auth: dict = None):
        if not auth or "token" not in auth:
            return False  # Reject connection
        return True

    async def event_typing(self, sid: str, data: dict):
        print(f"Typing: {data}")

    async def event_stop_typing(self, sid: str, data: dict):
        print(f"Stopped typing: {data}")
```


### 2. Use with lifespan (recommended)
```python
# lifespan.py

from contextlib import asynccontextmanager
from fastapi import FastAPI
from fastapi_socketio_handler import get_socket_manager

import app.chat_handler  # 👈 force-import handlers to trigger decorator registration

@asynccontextmanager
async def lifespan(app: FastAPI):
    socket_manager = get_socket_manager(
        redis_url="redis://localhost:6379",           # Optional Redis
        async_session=your_async_session_factory,     # Optional DB session factory
    )
    socket_manager.mount_to_app(app)
    socket_manager.register_events()

    async with socket_manager:
        yield
```

### 3. Connect from frontend
```js
const socket = io('http://localhost:8000/chat', {
  auth: {
    token: 'your-auth-token'
  }
});

socket.emit("typing", { chatId: "..." });
```

