qws 0.1.0__py3-none-any.whl

qws/__init__.py

@@ -0,0 +1,9 @@
+from .server import Server
+from .client import Client
+
+server = Server
+client = Client
+
+__all__ = [
+    "server","Server","client","Client"
+]

qws/client.py

@@ -0,0 +1,112 @@
+import asyncio
+from typing import Awaitable, Callable
+
+from websockets.asyncio.client import connect, ClientConnection
+from websockets.exceptions import ConnectionClosed
+
+from .packet import PacketData, PacketError, make_packet, parse_packet, normalize_event_name
+
+
+ClientHandler = Callable[[PacketData], Awaitable[None]]
+
+
+class Client:
+    def __init__(
+        self,
+        uri: str = "ws://127.0.0.1:8765",
+        warn_on_unknown_event: bool = True,
+    ) -> None:
+        self.uri = uri
+        self.warn_on_unknown_event = warn_on_unknown_event
+
+        self.websocket: ClientConnection | None = None
+        self.handlers: dict[str, ClientHandler] = {}
+
+        self.client_id: str | None = None
+        self._connected = asyncio.Event()
+
+    def on(self, event_name: str):
+        """
+        Register an async handler for an event from the server.
+
+        Example:
+
+            @client.on("pong")
+            async def pong(data):
+                ...
+        """
+        normalized_name = normalize_event_name(event_name)
+
+        def decorator(func: ClientHandler):
+            self.handlers[normalized_name] = func
+            return func
+
+        return decorator
+
+    async def wait_until_connected(self) -> None:
+        await self._connected.wait()
+
+    async def send(
+        self,
+        event_name: str,
+        data: PacketData | None = None,
+    ) -> None:
+        """
+        Send a packet to the server.
+        """
+        if self.websocket is None:
+            raise RuntimeError("Client is not connected")
+
+        await self.websocket.send(make_packet(event_name, data))
+
+    async def warning(self, message: str, data: PacketData | None = None) -> None:
+        """
+        Send a warning packet to the server.
+        """
+        await self.send("warning", {
+            "message": message,
+            "data": data or {},
+        })
+
+    async def _dispatch(self, event_name: str, data: PacketData) -> None:
+        handler = self.handlers.get(event_name)
+
+        if handler is None:
+            if self.warn_on_unknown_event:
+                print(f"[qws client warning] no client handler for event: {event_name}")
+            return
+
+        await handler(data)
+
+    async def run(self) -> None:
+        """
+        Connect to the server and keep listening forever.
+        """
+        async with connect(self.uri) as websocket:
+            self.websocket = websocket
+            self._connected.set()
+
+            print(f"[qws client] connected to {self.uri}")
+
+            try:
+                async for raw_message in websocket:
+                    try:
+                        event_name, data, timestamp = parse_packet(raw_message)
+                    except PacketError as error:
+                        print(f"[qws client warning] {error}")
+                        continue
+
+                    if event_name == "client_connected":
+                        raw_client_id = data.get("client_id")
+                        if isinstance(raw_client_id, str):
+                            self.client_id = raw_client_id
+
+                    await self._dispatch(event_name, data)
+
+            except ConnectionClosed:
+                print("[qws client] disconnected")
+
+            finally:
+                self.websocket = None
+                self.client_id = None
+                self._connected.clear()

qws/packet.py

@@ -0,0 +1,57 @@
+import json
+from datetime import datetime, timezone
+from typing import Any
+
+PacketData = dict[str,Any]
+
+class PacketError(Exception):
+    pass
+
+def utc_timestamp() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+def normalize_event_name(event_name:str) -> str:
+    if not isinstance(event_name, str):
+        raise PacketError("event_name must be a string")
+    event_name = event_name.strip().lower()
+
+    if not event_name:
+        raise PacketError("event_name cannot be empty")
+    
+    return event_name
+
+def make_packet(event_name:str, data:PacketData|None={}) -> str:
+    if data is None:
+        data = {}
+    if not isinstance(data,dict):
+        raise PacketError("data must be a dict")
+    
+    return json.dumps({
+        "event_name":normalize_event_name(event_name),
+        "data":data,
+        "timestamp":utc_timestamp(),
+    })
+
+def parse_packet(raw_message:str|bytes) -> tuple[str,PacketData,str]:
+    if isinstance(raw_message,bytes):
+        raw_message = raw_message.decode('utf-8')
+    
+    try:
+        packet = json.loads(raw_message)
+    except json.JSONDecodeError as error:
+        raise PacketError(f"Invalid JSON: {error}") from error
+    
+    if not isinstance(packet, dict):
+        raise PacketError("Packet must be a JSON object")
+    
+    event_name = packet.get('event_name')
+    data = packet.get('data',{})
+    timestamp = packet.get('timestamp',"")
+
+    if not isinstance(data, dict):
+        raise PacketError("Packet field 'data' must be a dict/object")
+    
+    if not isinstance(timestamp, str):
+        raise PacketError("Packet field 'timestamp' must be a string")
+    
+    return event_name, data, timestamp

qws/server.py

@@ -0,0 +1,138 @@
+import asyncio
+import uuid
+from typing import Awaitable, Callable, Any
+
+from websockets.asyncio.server import serve, ServerConnection
+from websockets.exceptions import ConnectionClosed
+
+from .packet import PacketData, PacketError, make_packet, parse_packet, normalize_event_name
+
+ServerHandler = Callable[[str, PacketData], Awaitable[None]]
+
+class Server:
+    def __init__(
+            self,
+            host:str='127.0.0.1',
+            port:int = 8765,
+            warn_on_unknown_event:bool = True
+
+    ):
+        self.host:str = host
+        self.port:int = port
+        self.warn_on_unknown_event:bool = warn_on_unknown_event
+
+        self.clients:dict[str, ServerConnection] = {}
+        self.handlers:dict[str, ServerHandler] = {}
+
+    def on(self, event_name:str):
+        """
+        Register an async handler for an event.
+
+        Example:
+
+            @server.on("ping")
+            async def ping(client_id, data):
+                ...
+        """
+        normalized_name = normalize_event_name(event_name)
+        def decorator(func:ServerHandler):
+            self.handlers[normalized_name] = func
+            return func
+        return decorator
+    
+    async def send(
+            self,
+            client_id:str,
+            event_name:str,
+            data:PacketData|None=None
+    ) -> bool:
+        """
+        Send a packet to one specific client.
+
+        Returns False if the client does not exist.
+        """
+        websocket = self.clients.get(client_id)
+        if websocket is None:
+            return False
+        await websocket.send(make_packet(event_name,data))
+        return True
+    
+    async def warning(
+            self,
+            client_id:str,
+            message:str,
+            data:PacketData|None=None
+    ) -> bool:
+        """
+        Send a warning packet to one specific client.
+        """
+        return await self.send(client_id,"warning",{
+            'message':message,
+            'data':data or {}
+        })
+
+    async def broadcast(
+        self,
+        event_name: str,
+        data: PacketData | None = None,
+    ) -> None:
+        """
+        Send a packet to every connected client.
+        """
+        packet = make_packet(event_name, data)
+        dead_clients: list[str] = []
+
+        for client_id, websocket in self.clients.items():
+            try:
+                await websocket.send(packet)
+            except ConnectionClosed:
+                dead_clients.append(client_id)
+
+        for client_id in dead_clients:
+            self.clients.pop(client_id, None)
+    
+    async def _dispatch(self, client_id:str, event_name:str, data:PacketData) -> None:
+        handler = self.handlers.get(event_name)
+        if handler is None:
+            if self.warn_on_unknown_event:
+                await self.warning(client_id, f"No server handler for event: {event_name}", {
+                    "unknown_event": event_name,
+                })
+            return
+        await handler(client_id, data)
+    
+    async def _handle_client(self, websocket: ServerConnection) -> None:
+        client_id = str(uuid.uuid4())
+        self.clients[client_id] = websocket
+
+        print(f"[qws server] client connected: {client_id}")
+
+        await self.send(client_id, "client_connected", {
+            "client_id": client_id,
+        })
+
+        try:
+            async for raw_message in websocket:
+                try:
+                    event_name, data, timestamp = parse_packet(raw_message)
+                except PacketError as error:
+                    await self.warning(client_id, str(error))
+                    continue
+
+                await self._dispatch(client_id, event_name, data)
+
+        except ConnectionClosed:
+            pass
+
+        finally:
+            self.clients.pop(client_id, None)
+            print(f"[qws server] client disconnected: {client_id}")
+
+    async def start(self) -> None:
+        """
+        Start the server and run forever.
+        """
+        print(f"[qws server] running at ws://{self.host}:{self.port}")
+
+        async with serve(self._handle_client, self.host, self.port):
+            await asyncio.Future()

qws-0.1.0.dist-info/METADATA

@@ -0,0 +1,25 @@
+Metadata-Version: 2.4
+Name: qws
+Version: 0.1.0
+Summary: A tiny async JSON event WebSocket wrapper.
+Author: Kevin d'Anunciacao
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/yourusername/qws
+Project-URL: Repository, https://github.com/yourusername/qws
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: websockets>=16.0
+Dynamic: license-file
+
+# qws
+
+A tiny async JSON event WebSocket wrapper.
+
+## Install
+
+```bash
+pip install qws

qws-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+qws/__init__.py,sha256=-mlwUvRY1GuS2aUYSp3DnsgiFjGjJ0KJ9ZM8lOhIX4w,149
+qws/client.py,sha256=gsk0ZkJJGjmGPcVhUPkunKh2519GdiLsuCRnSI6JQhU,3454
+qws/packet.py,sha256=U6iHDI3xdbPNST6WjXaixDGAOyajNjeF1LQgajcRqvk,1720
+qws/server.py,sha256=D4f7uGNI4_14J3tJxdERfvY9iVIH-6A2sjnLA7ag-mA,4256
+qws-0.1.0.dist-info/licenses/LICENSE,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+qws-0.1.0.dist-info/METADATA,sha256=2l9qqchOiqNWescVBXTnIa0a5_4DBaQ9-27WMD_zp4Y,674
+qws-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+qws-0.1.0.dist-info/top_level.txt,sha256=pBbV9Inwc59HerH-P9NDSAJxpbcUAENjyRJL0yecYaU,4
+qws-0.1.0.dist-info/RECORD,,

qws-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

qws-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+qws