Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/nathandraco22/zaptools-python
Event-Driven websocket management
https://github.com/nathandraco22/zaptools-python
asyncio fastapi python sanic websocket websockets
Last synced: 3 months ago
JSON representation
Event-Driven websocket management
- Host: GitHub
- URL: https://github.com/nathandraco22/zaptools-python
- Owner: NathanDraco22
- License: mit
- Created: 2022-02-25T20:53:00.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2024-02-14T01:46:54.000Z (11 months ago)
- Last Synced: 2024-03-15T02:47:14.737Z (10 months ago)
- Topics: asyncio, fastapi, python, sanic, websocket, websockets
- Language: Python
- Homepage:
- Size: 73.2 KB
- Stars: 3
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Zaptools
A toolkit for Event-Driven websocket management
### Also Supported
| Lang |Side |View Source |
|:------------------:|:----:|:------------------------------------------------------------------------------------------------------|
| | Client/Server |[`zaptools_dart`](https://github.com/NathanDraco22/zaptools-dart)|### Getting Started
Zaptools provides tools for building event-driven websocket integration. It includes pre-existing classes to seamless integration with FastApi and Sanic.
#### installation
``` bash
pip install zaptools # windows
pip3 install zaptools # mac
```#### FastAPI
```python
from fastapi import FastAPI, WebSocket
from zaptools.tools import EventRegister, EventContext
from zaptools.connectors import FastApiConnectorapp:FastAPI = FastAPI()
register: EventRegister = EventRegister()@register.on_event("hello")
async def hello_trigger(ctx: EventContext):
conn = ctx.connection
await conn.send("hello", "HELLO FROM SERVER !!!")@app.websocket("/ws")
async def websocket_endpoint(ws: WebSocket):
connector = FastApiConnector(reg, ws)
await connector.start()```
Firstly create a `FastAPI` and `EventRegister` instance. `EventRegister` has the responsability to create events.
```python
from fastapi import FastAPI, WebSocket
from zaptools.tools import EventRegister, EventContext, Connector
from zaptools.adapters import FastApiAdapterapp:FastAPI = FastAPI()
register: EventRegister = EventRegister()
```
For Creating events use the decorator syntax.
This will creates an event named `"hello"` and it will call `hello_trigger` function when an event named `"hello"` is received.
```python
@register.on_event("hello")
async def hello_trigger(ctx: EventContext):
conn = ctx.connection
await conn.send("hello", "HELLO FROM SERVER !!!")
```
> Event it is a class with name("hello") and the callback(hello_trigger)For connecting `EventRegister` with the websocket class provided by FastAPI framework, there is a `FastApiConnector`, use the `plug_and_start` static method of the `FastApiConnector`, it will start to receive events.
```python
@app.websocket("/ws")
async def websocket_endpoint(ws: WebSocket):
connector = FastApiConnector(reg, ws)
await connector.start()
```It's the same way for Sanic Framework
#### Sanic
```python
from sanic import Sanic, Request, Websocketfrom zaptools.tools import EventRegister, EventContext
from zaptools.connectors import SanicConnectorapp = Sanic("MyHelloWorldApp")
register: EventRegister = EventRegister()@register.on_event("hello")
async def hello_trigger(ctx: EventContext):
conn = ctx.connection
await conn.send("hello", "HELLO FROM SERVER !!!")@app.websocket("/")
async def websocket(request: Request, ws: Websocket):
connector = SanicConnector(reg, ws)
await connector.start()```
### EventContext object
Each element is triggered with a `EventContext` object. This `EventContext` object contains information about the current event and which `WebSocketConnection` is invoking it.
```python
EventContext.event_name # name of current event
EventContext.payload # payload the data from the connection
EventContext.connection # WebSocketConnection
```
### Sending Events
In order to response to the client use the `WebSocketConnection.send(event:str, payload:Any)`, this object is provided by the `Context`.
```python
@register.on_event("hello")
async def hello_trigger(ctx: EventContext):
conn = ctx.connection
conn.send("hello", "HELLO FROM SERVER !!!") # sending "hello" event to client with a payload.
```
### WebSocketConnection
`WebSocketConnection` provides a easy interaction with the websocket.```python
WebSocketConnection.id # ID of connectionawait WebSocketConnection.send(event:str, payload:Any) #Send Event to the client
await WebSocketConnection.close() # Close the websocket connection
```
> Coroutines need to be awaited.### Events
The `"connected"`, `"disconnected"` and `"error"` events can be used to trigger an action when a connection is started and after it is closed or when a error ocurred in a event.
```python
@register.on_event("connected")
async def connected_trigger(ctx: EventContext):
print("Connection started")@register.on_event("disconnected")
async def disconnected_trigger(ctx: EventContext):
print("Connection closed")@register.on_event("error")
async def disconnected_trigger(ctx: EventContext):
print("An error ocurred in a event")
print(ctx.payload) # display error details
```
> Error details in `payload`## Contributions are wellcome