⚡🗞️ FastAPI Websocket Pub/Sub
A fast and durable Pub/Sub channel over Websockets. The easiest way to create a live publish / subscribe multi-cast over the web.
Supports and tested on Python >= 3.7
As seen at PyCon IL 2021 and EuroPython 2021
Installation 🛠️
pip install fastapi_websocket_pubsub
Intro
The classic pub/sub pattern made easily accessible and scalable over the web and across your cloud in realtime; while enjoying the benefits of FastAPI (e.g. dependency injection).
FastAPI + WebSockets + PubSub == ⚡💪 ❤️
-
Subscribe
- Clients subscribe to topics (arbitrary strings) and receive relevant events along with structured data (serialized with Pydantic).
# Callback to be called upon event being published on server async def on_event(data): print("We got an event! with data- ", data) # Subscribe for the event client.subscribe("my event", on_event)
- Clients subscribe to topics (arbitrary strings) and receive relevant events along with structured data (serialized with Pydantic).
-
Publish
- Directly from server code to connected clients.
app = FastAPI() endpoint = PubSubEndpoint() endpoint.register_route(app, path="/pubsub") endpoint.publish(["my_event_topic"], data=["my", "data", 1])
- From client to client (through the servers)
async with PubSubClient(server_uri="ws://localhost/pubsub") as client: endpoint.publish(["my_event_topic"], data=["my", "data", 1])
- Across server instances (using broadcaster and a backend medium (e.g. Redis, Kafka, ...))
- No matter which server a client connects to - it will get the messages it subscribes to
app = FastAPI() endpoint = PubSubEndpoint(broadcaster="postgres://localhost:5432/") @app.websocket("/pubsub") async def websocket_rpc_endpoint(websocket: WebSocket): await endpoint.main_loop(websocket)
see examples/pubsub_broadcaster_server_example.py for full usage example Note: Requires install with dependencies e.g.pip install fastapi_websocket_pubsub[redis],pip install fastapi_websocket_pubsub[postgres],pip install fastapi_websocket_pubsub[kafka]orpip install fastapi_websocket_pubsub[all]to get support for all three backends
- Directly from server code to connected clients.
Usage example (server publishing following HTTP trigger):
In the code below, a client connects to the server and subscribes to a topic named "triggered". Aside from PubSub websocket, the server also exposes a regular http route, which triggers publication of the event.
Server:
import asyncio
import uvicorn
from fastapi import FastAPI
from fastapi.routing import APIRouter
from fastapi_websocket_pubsub import PubSubEndpoint
app = FastAPI()
# Init endpoint
endpoint = PubSubEndpoint()
# register the endpoint on the app
endpoint.register_route(app, "/pubsub")
# Register a regular HTTP route
@app.get("/trigger")
async def trigger_events():
# Upon request trigger an event
endpoint.publish(["triggered"])
Client:
from fastapi_websocket_pubsub import PubSubClient
# Callback to be called upon event being published on server
async def on_trigger(data):
print("Trigger URL was accessed")
async with PubSubClient(server_uri="ws://localhost/pubsub") as client:
# Subscribe for the event
client.subscribe("triggered", on_trigger)
More Examples
- See the examples and tests folders for more server and client examples.
- See fastapi-websocket-rpc depends example to see how to combine with FASTAPI dependency injections
What can I do with this?
The combination of Websockets, and bi-directional Pub/Sub is ideal to create realtime data propagation solution at scale over the web.
- Update mechanism
- Remote control mechanism
- Data processing
- Distributed computing
- Realtime communications over the web
Foundations:
-
Based on fastapi-websocket-rpc for a robust realtime bidirectional channel
-
Based on broadcaster for syncing server instances
-
Server Endpoint:
-
Based on FastAPI: enjoy all the benefits of a full ASGI platform, including Async-io and dependency injections (for example to authenticate connections)
-
Based on Pydantic: easily serialize structured data as part of RPC requests and responses. Simply Pass Pydantic data models as PubSub published data to have it available as part of an event.
-
-
Client :
-
Based on Tenacity: allowing configurable retries to keep to connection alive
- see WebSocketRpcClient.init's retry_config
-
Based on python websockets - a more comprehensive client than the one offered by FastAPI
-
Logging
fastapi-websocket-pubsub uses fastapi-websocket-rpc for logging config.
It provides a helper logging module to control how it produces logs for you.
See fastapi_websocket_rpc/logger.py.
Use logging_config.set_mode or the 'WS_RPC_LOGGING' environment variable to choose the logging method you prefer.
Or override completely via default logging config (e.g. 'logging.config.dictConfig'), all logger name start with: 'fastapi.ws_rpc.pubsub'
example:
# set RPC to log like UVICORN
from fastapi_websocket_rpc.logger import logging_config, LoggingModes
logging_config.set_mode(LoggingModes.UVICORN)
Pull requests - welcome!
- Please include tests for new features
Metadata
Release files for fastapi-websocket-pubsub 1.0.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| fastapi_websocket_pubsub-1.0.1.tar.gz | 21.1 kB | Without provenance | Details for fastapi_websocket_pubsub-1.0.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| fastapi_websocket_pubsub-1.0.1-py3-none-any.whl | Python 3 | none | any | Details for fastapi_websocket_pubsub-1.0.1-py3-none-any.whl |
Total release size: 43.6 kB
Release files / fastapi_websocket_pubsub-1.0.1.tar.gz
| Download URL | fastapi_websocket_pubsub-1.0.1.tar.gz |
|---|---|
| Size | 21.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
df7f64c7b034a2d7ed99fd7b61c4f3c2befd4dd45c5f8fa5bc0a33a7a080e4bd
|
|
BLAKE2b-256 checksum How to use checksums |
06aa8be7de9892a91b40180fa32d9d4414f3e8eada987482245ed613adf1f211
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Release files / fastapi_websocket_pubsub-1.0.1-py3-none-any.whl
| Download URL | fastapi_websocket_pubsub-1.0.1-py3-none-any.whl |
|---|---|
| Size | 22.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
48f70fee785e96c1577ac4eff98439ae37af7d4141399c40966cca6245fdfcbd
|
|
BLAKE2b-256 checksum How to use checksums |
6893555df2858f86c4336fba1999dcbb99a2c231b75bb2066e2899bbea6ffe9f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Security for fastapi-websocket-pubsub 1.0.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.