{"id":15288721,"url":"https://github.com/nathandraco22/zaptools-python","last_synced_at":"2025-04-13T08:10:13.884Z","repository":{"id":62590933,"uuid":"463672446","full_name":"NathanDraco22/zaptools-python","owner":"NathanDraco22","description":"Event-Driven websocket management","archived":false,"fork":false,"pushed_at":"2025-04-10T04:21:29.000Z","size":140,"stargazers_count":10,"open_issues_count":1,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-13T08:09:55.225Z","etag":null,"topics":["asyncio","fastapi","python","sanic","websocket","websockets"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NathanDraco22.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-02-25T20:53:00.000Z","updated_at":"2025-04-08T03:14:12.000Z","dependencies_parsed_at":"2022-11-04T07:17:56.919Z","dependency_job_id":"39678de6-eef1-4ed9-8f47-820c1ab3e0f9","html_url":"https://github.com/NathanDraco22/zaptools-python","commit_stats":null,"previous_names":["nathandraco22/zap-adapter-python"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NathanDraco22%2Fzaptools-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NathanDraco22%2Fzaptools-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NathanDraco22%2Fzaptools-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NathanDraco22%2Fzaptools-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NathanDraco22","download_url":"https://codeload.github.com/NathanDraco22/zaptools-python/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248681491,"owners_count":21144700,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asyncio","fastapi","python","sanic","websocket","websockets"],"created_at":"2024-09-30T15:52:27.879Z","updated_at":"2025-04-13T08:10:13.857Z","avatar_url":"https://github.com/NathanDraco22.png","language":"Python","readme":"\u003ch1 align=\"center\"\u003eZaptools\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/NathanDraco22/zaptools-dart/main/assets/zaptools-logo-150.png\" /\u003e\n  \u003ch3 align=\"center\"\u003e\n    A toolkit for Event-Driven websocket management\n  \u003ch3\u003e\n\u003c/p\u003e\n\u003cdiv align=\"center\"\u003e\n    \u003ca href=\"https://pypi.org/project/zaptools/\"\u003e\u003cimg src=\"https://badge.fury.io/py/zaptools.svg\" alt=\"PyPI version\" height=\"18\"\u003e\u003c/a\u003e\n\u003c/div\u003e\n\n### Also Supported\n| Lang               |Side  |View Source                                                                                           |\n|:------------------:|:----:|:------------------------------------------------------------------------------------------------------|\n|\u003ca href=\"https://www.python.org\" target=\"_blank\"\u003e \u003cimg src=\"https://www.vectorlogo.zone/logos/dartlang/dartlang-icon.svg\" alt=\"python\" width=\"25\" height=\"25\"/\u003e \u003c/a\u003e| Client/Server |[`zaptools_dart`](https://github.com/NathanDraco22/zaptools-dart)|\n\n### Getting Started\n\nZaptools provides tools for building event-driven websocket integration. It includes pre-existing classes to seamless integration with FastApi and Sanic.\n\n\n#### installation\n``` bash\npip install zaptools # windows\npip3 install zaptools # mac\n```\n\n#### FastAPI\n```python\nfrom fastapi import FastAPI, WebSocket\nfrom zaptools.tools import EventRegister, EventContext\nfrom zaptools.connectors import FastApiConnector\n\napp:FastAPI = FastAPI()\nregister: EventRegister = EventRegister() \n\n@register.on_event(\"hello\") \nasync def hello_trigger(ctx: EventContext):\n    conn = ctx.connection\n    await conn.send(\"hello\", \"HELLO FROM SERVER !!!\") \n\n\n@app.websocket(\"/ws\")\nasync def websocket_endpoint(ws: WebSocket):\n    connector = FastApiConnector(reg, ws)\n    await connector.start()\n\n```\n\nFirstly create a `FastAPI` and `EventRegister` instance. `EventRegister` has the responsability to create events.\n```python\nfrom fastapi import FastAPI, WebSocket\nfrom zaptools.tools import EventRegister, EventContext, Connector\nfrom zaptools.adapters import FastApiAdapter\n\napp:FastAPI = FastAPI()\nregister: EventRegister = EventRegister() \n```\nFor Creating events use the decorator syntax.\nThis will creates an event named `\"hello\"` and it will call `hello_trigger` function when an event named `\"hello\"` is received.\n```python\n@register.on_event(\"hello\") \nasync def hello_trigger(ctx: EventContext):\n    conn = ctx.connection\n    await conn.send(\"hello\", \"HELLO FROM SERVER !!!\") \n```\n\u003e Event it is a class with name(\"hello\") and the callback(hello_trigger)\n\nFor 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.\n```python\n@app.websocket(\"/ws\")\nasync def websocket_endpoint(ws: WebSocket):\n    connector = FastApiConnector(reg, ws)\n    await connector.start()\n```\n\nIt's the same way for Sanic Framework\n#### Sanic\n```python\nfrom sanic import Sanic, Request, Websocket\n\nfrom zaptools.tools import EventRegister, EventContext\nfrom zaptools.connectors import SanicConnector\n\napp = Sanic(\"MyHelloWorldApp\")\nregister: EventRegister = EventRegister()\n\n@register.on_event(\"hello\") \nasync def hello_trigger(ctx: EventContext):\n    conn = ctx.connection\n    await conn.send(\"hello\", \"HELLO FROM SERVER !!!\") \n\n@app.websocket(\"/\")\nasync def websocket(request: Request, ws: Websocket):\n    connector = SanicConnector(reg, ws)\n    await connector.start()\n\n```\n### EventContext object\nEach element is triggered with a `EventContext` object. This `EventContext` object contains information about the current event and which `WebSocketConnection` is invoking it.\n```python\nEventContext.event_name # name of current event\nEventContext.payload # payload the data from the connection\nEventContext.connection # WebSocketConnection \n```\n### Sending Events\nIn order to response to the client use the `WebSocketConnection.send(event:str, payload:Any)`, this object is provided by the `Context`.\n```python\n@register.on_event(\"hello\") \nasync def hello_trigger(ctx: EventContext):\n    conn = ctx.connection\n    conn.send(\"hello\", \"HELLO FROM SERVER !!!\") # sending \"hello\" event to client with a payload.\n```\n### WebSocketConnection\n`WebSocketConnection` provides a easy interaction with the websocket.\n\n```python\nWebSocketConnection.id # ID of connection\n\nawait WebSocketConnection.send(event:str, payload:Any) #Send Event to the client\n\nawait WebSocketConnection.close() # Close the websocket connection\n```\n\u003e Coroutines need to be awaited.\n\n### Events\n\nThe `\"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.\n\n```python\n@register.on_event(\"connected\")\nasync def connected_trigger(ctx: EventContext):\n    print(\"Connection started\")\n\n@register.on_event(\"disconnected\")\nasync def disconnected_trigger(ctx: EventContext):\n    print(\"Connection closed\")\n\n@register.on_event(\"error\")\nasync def disconnected_trigger(ctx: EventContext):\n    print(\"An error ocurred in a event\")\n    print(ctx.payload) # display error details\n```\n\u003e Error details in `payload`\n\n## Client\n\nZaptools provides a python client to connect with others zaptools server\n\n```python\nfrom zaptools.client import ZapClient\n\nclient = ZapClient()\nawait client.connect(\"ws://localhost:8000/\") #Connect to the server\n\nawait client.send(\"event1\", {\"hello\":\"from client\"}, {}) # send a event\n\n# A generator with all event stream\n# Receive all events\nasync for event in client.event_stream(): \n        print(event.payload)\n\n\n# A generator with all connection state\n# Receive connection state\n# ONLINE, OFFLINE, CONNNECTING and ERROR state\nasync for state in client.connection_state(): \n        print(state)\n\n```\n\n\n## Contributions are wellcome\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnathandraco22%2Fzaptools-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnathandraco22%2Fzaptools-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnathandraco22%2Fzaptools-python/lists"}