multilinkk 0.1.0__tar.gz

multilinkk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Marcus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

multilinkk-0.1.0/PKG-INFO

@@ -0,0 +1,231 @@
+Metadata-Version: 2.4
+Name: multilinkk
+Version: 0.1.0
+Summary: A high-level Python multiplayer library. Just works.
+Author: Marcus
+License: MIT
+Project-URL: Homepage, https://github.com/yourusername/multilink
+Project-URL: Repository, https://github.com/yourusername/multilink
+Project-URL: Issues, https://github.com/yourusername/multilink/issues
+Keywords: multiplayer,networking,websocket,gamedev,realtime
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+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: Topic :: Games/Entertainment
+Classifier: Topic :: Internet
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: websockets>=12.0
+Dynamic: license-file
+
+# multilink
+
+**A high-level Python multiplayer library. Just works.**
+
+No presets. No opinions. You define the events, the data, and the behavior — multilink handles the connections, state sync, and networking underneath.
+
+```
+pip install multilink
+```
+
+---
+
+## Quickstart
+
+**Server:**
+```python
+from multilink import Server
+
+server = Server(port=5000)
+
+@server.on("connect")
+def on_connect(player):
+    server.broadcast("joined", {"id": player.id})
+
+@server.on("move")
+def on_move(player, data):
+    player.update_state({"x": data["x"], "y": data["y"]})
+
+@server.on("disconnect")
+def on_disconnect(player):
+    server.broadcast("left", {"id": player.id})
+
+@server.on_error()
+def on_error(error, player):
+    print(f"Error from {player.id}: {error}")
+
+server.start()
+```
+
+**Client:**
+```python
+from multilink import Client
+
+client = Client("localhost", 5000)
+
+@client.on("connect")
+def on_connect():
+    client.send("move", {"x": 10, "y": 20})
+
+@client.on("joined")
+def on_joined(data):
+    print(f"Player {data['id']} joined!")
+
+@client.on("__state_sync__")
+def on_sync(data):
+    for player_id, state in data["players"].items():
+        print(f"{player_id}: {state}")
+
+@client.on_error()
+def on_error(error):
+    print(f"Error: {error}")
+
+client.connect()
+```
+
+---
+
+## Core concepts
+
+### Events
+Everything is event-based. Send an event from the client, handle it on the server (and vice versa) with a simple decorator.
+
+```python
+# Client sends:
+client.send("chat", {"msg": "hello!"})
+
+# Server handles:
+@server.on("chat")
+def on_chat(player, data):
+    server.broadcast("chat", {"from": player.id, "msg": data["msg"]})
+
+# All clients receive:
+@client.on("chat")
+def on_chat(data):
+    print(f"[{data['from']}]: {data['msg']}")
+```
+
+### Player state sync
+Each player has a `.state` dict. Update it on the server and multilink automatically broadcasts only the changed fields to all clients at 20 ticks/sec.
+
+```python
+@server.on("move")
+def on_move(player, data):
+    player.update_state({"x": data["x"], "y": data["y"]})
+    # That's it — state is synced automatically
+```
+
+Force an immediate sync if you can't wait for the next tick:
+```python
+server.sync_state()        # delta only
+server.sync_state(full=True)  # full state
+```
+
+### Sending to one player
+```python
+@server.on("connect")
+def on_connect(player):
+    # Send something only to this player
+    asyncio.ensure_future(player.send("welcome", {"id": player.id}))
+```
+
+### Error handling
+Errors in event handlers are caught and routed to your error handler instead of crashing everything.
+
+```python
+@server.on_error()
+def on_error(error, player):
+    print(f"Error from {player.id}: {error}")
+
+@client.on_error()
+def on_error(error):
+    print(f"Client error: {error}")
+```
+
+### Send queue
+Messages sent before the client is fully connected are automatically queued and delivered the moment the connection opens. No timing issues.
+
+```python
+client.send("hello", {"msg": "this works even before connect() is called"})
+client.connect()  # queued message is flushed on connect
+```
+
+---
+
+## API Reference
+
+### `Server(host, port, tick_rate, delta_only)`
+
+| Arg | Default | Description |
+|-----|---------|-------------|
+| `host` | `"0.0.0.0"` | Hostname to bind to |
+| `port` | `5000` | Port to listen on |
+| `tick_rate` | `20` | State syncs per second |
+| `delta_only` | `True` | Only broadcast changed fields |
+
+| Method | Description |
+|--------|-------------|
+| `server.on(event)` | Register an event handler |
+| `server.on_error()` | Register an error handler |
+| `server.broadcast(event, data)` | Send event to all players |
+| `server.sync_state(full=False)` | Force immediate state sync |
+| `server.get_players()` | List of all connected Players |
+| `server.get_player(id)` | Look up a player by ID |
+| `server.player_count` | Number of connected players |
+| `server.start()` | Start the server (blocking) |
+
+### `Client(host, port)`
+
+| Method | Description |
+|--------|-------------|
+| `client.on(event)` | Register an event handler |
+| `client.on_error()` | Register an error handler |
+| `client.send(event, data)` | Send event to server |
+| `client.connect()` | Connect and start listening (blocking) |
+
+### `Player`
+
+| Attribute/Method | Description |
+|-----------------|-------------|
+| `player.id` | Unique player ID |
+| `player.state` | Dict of synced values |
+| `player.set_state(key, value)` | Set one state value |
+| `player.get_state(key, default)` | Get one state value |
+| `player.update_state(dict)` | Merge dict into state |
+| `player.clear_state()` | Wipe state entirely |
+| `player.send(event, data)` | Send directly to this player |
+| `player.connected_at` | Unix timestamp of connection time |
+| `player.last_seen` | Unix timestamp of last message |
+
+---
+
+## Built-in events
+
+| Event | Where | Handler signature |
+|-------|-------|------------------|
+| `"connect"` | server | `fn(player)` |
+| `"disconnect"` | server | `fn(player)` |
+| `"connect"` | client | `fn()` |
+| `"disconnect"` | client | `fn()` |
+| `"__state_sync__"` | client | `fn(data)` — `data["players"]` is a dict of `player_id -> state_delta` |
+
+---
+
+## Requirements
+
+- Python 3.8+
+- `websockets >= 12.0`
+
+---
+
+## License
+
+MIT

multilinkk-0.1.0/README.md

@@ -0,0 +1,203 @@
+# multilink
+
+**A high-level Python multiplayer library. Just works.**
+
+No presets. No opinions. You define the events, the data, and the behavior — multilink handles the connections, state sync, and networking underneath.
+
+```
+pip install multilink
+```
+
+---
+
+## Quickstart
+
+**Server:**
+```python
+from multilink import Server
+
+server = Server(port=5000)
+
+@server.on("connect")
+def on_connect(player):
+    server.broadcast("joined", {"id": player.id})
+
+@server.on("move")
+def on_move(player, data):
+    player.update_state({"x": data["x"], "y": data["y"]})
+
+@server.on("disconnect")
+def on_disconnect(player):
+    server.broadcast("left", {"id": player.id})
+
+@server.on_error()
+def on_error(error, player):
+    print(f"Error from {player.id}: {error}")
+
+server.start()
+```
+
+**Client:**
+```python
+from multilink import Client
+
+client = Client("localhost", 5000)
+
+@client.on("connect")
+def on_connect():
+    client.send("move", {"x": 10, "y": 20})
+
+@client.on("joined")
+def on_joined(data):
+    print(f"Player {data['id']} joined!")
+
+@client.on("__state_sync__")
+def on_sync(data):
+    for player_id, state in data["players"].items():
+        print(f"{player_id}: {state}")
+
+@client.on_error()
+def on_error(error):
+    print(f"Error: {error}")
+
+client.connect()
+```
+
+---
+
+## Core concepts
+
+### Events
+Everything is event-based. Send an event from the client, handle it on the server (and vice versa) with a simple decorator.
+
+```python
+# Client sends:
+client.send("chat", {"msg": "hello!"})
+
+# Server handles:
+@server.on("chat")
+def on_chat(player, data):
+    server.broadcast("chat", {"from": player.id, "msg": data["msg"]})
+
+# All clients receive:
+@client.on("chat")
+def on_chat(data):
+    print(f"[{data['from']}]: {data['msg']}")
+```
+
+### Player state sync
+Each player has a `.state` dict. Update it on the server and multilink automatically broadcasts only the changed fields to all clients at 20 ticks/sec.
+
+```python
+@server.on("move")
+def on_move(player, data):
+    player.update_state({"x": data["x"], "y": data["y"]})
+    # That's it — state is synced automatically
+```
+
+Force an immediate sync if you can't wait for the next tick:
+```python
+server.sync_state()        # delta only
+server.sync_state(full=True)  # full state
+```
+
+### Sending to one player
+```python
+@server.on("connect")
+def on_connect(player):
+    # Send something only to this player
+    asyncio.ensure_future(player.send("welcome", {"id": player.id}))
+```
+
+### Error handling
+Errors in event handlers are caught and routed to your error handler instead of crashing everything.
+
+```python
+@server.on_error()
+def on_error(error, player):
+    print(f"Error from {player.id}: {error}")
+
+@client.on_error()
+def on_error(error):
+    print(f"Client error: {error}")
+```
+
+### Send queue
+Messages sent before the client is fully connected are automatically queued and delivered the moment the connection opens. No timing issues.
+
+```python
+client.send("hello", {"msg": "this works even before connect() is called"})
+client.connect()  # queued message is flushed on connect
+```
+
+---
+
+## API Reference
+
+### `Server(host, port, tick_rate, delta_only)`
+
+| Arg | Default | Description |
+|-----|---------|-------------|
+| `host` | `"0.0.0.0"` | Hostname to bind to |
+| `port` | `5000` | Port to listen on |
+| `tick_rate` | `20` | State syncs per second |
+| `delta_only` | `True` | Only broadcast changed fields |
+
+| Method | Description |
+|--------|-------------|
+| `server.on(event)` | Register an event handler |
+| `server.on_error()` | Register an error handler |
+| `server.broadcast(event, data)` | Send event to all players |
+| `server.sync_state(full=False)` | Force immediate state sync |
+| `server.get_players()` | List of all connected Players |
+| `server.get_player(id)` | Look up a player by ID |
+| `server.player_count` | Number of connected players |
+| `server.start()` | Start the server (blocking) |
+
+### `Client(host, port)`
+
+| Method | Description |
+|--------|-------------|
+| `client.on(event)` | Register an event handler |
+| `client.on_error()` | Register an error handler |
+| `client.send(event, data)` | Send event to server |
+| `client.connect()` | Connect and start listening (blocking) |
+
+### `Player`
+
+| Attribute/Method | Description |
+|-----------------|-------------|
+| `player.id` | Unique player ID |
+| `player.state` | Dict of synced values |
+| `player.set_state(key, value)` | Set one state value |
+| `player.get_state(key, default)` | Get one state value |
+| `player.update_state(dict)` | Merge dict into state |
+| `player.clear_state()` | Wipe state entirely |
+| `player.send(event, data)` | Send directly to this player |
+| `player.connected_at` | Unix timestamp of connection time |
+| `player.last_seen` | Unix timestamp of last message |
+
+---
+
+## Built-in events
+
+| Event | Where | Handler signature |
+|-------|-------|------------------|
+| `"connect"` | server | `fn(player)` |
+| `"disconnect"` | server | `fn(player)` |
+| `"connect"` | client | `fn()` |
+| `"disconnect"` | client | `fn()` |
+| `"__state_sync__"` | client | `fn(data)` — `data["players"]` is a dict of `player_id -> state_delta` |
+
+---
+
+## Requirements
+
+- Python 3.8+
+- `websockets >= 12.0`
+
+---
+
+## License
+
+MIT

multilinkk-0.1.0/multilink/__init__.py

@@ -0,0 +1,38 @@
+"""
+multilink
+~~~~~~~~~
+A high-level Python multiplayer library. Just works.
+
+Basic usage::
+
+    from multilink import Server, Client
+
+    # Server
+    server = Server(port=5000)
+
+    @server.on("connect")
+    def on_connect(player):
+        server.broadcast("joined", {"id": player.id})
+
+    server.start()
+
+    # Client
+    client = Client("localhost", 5000)
+
+    @client.on("joined")
+    def on_joined(data):
+        print(f"Player {data['id']} joined!")
+
+    client.connect()
+
+:copyright: 2024 Marcus
+:license: MIT
+"""
+
+from .server import Server
+from .client import Client
+from .player import Player
+
+__version__ = "0.1.0"
+__author__ = "Marcus"
+__all__ = ["Server", "Client", "Player"]

multilinkk-0.1.0/multilink/client.py

@@ -0,0 +1,221 @@
+"""
+multilink.client
+~~~~~~~~~~~~~~~~
+The multilink Client.
+"""
+
+import asyncio
+import json
+import logging
+from typing import Any, Callable, Dict, List, Optional
+
+import websockets
+from websockets.exceptions import ConnectionClosed
+
+logger = logging.getLogger("multilink.client")
+
+
+class Client:
+    """
+    A multilink client.
+
+    Args:
+        host: server hostname (default ``"localhost"``)
+        port: server port (default ``5000``)
+
+    Example::
+
+        from multilink import Client
+
+        client = Client("localhost", 5000)
+
+        @client.on("connect")
+        def on_connect():
+            client.send("hello", {"msg": "hi!"})
+
+        @client.on("welcome")
+        def on_welcome(data):
+            print(f"Server said: {data}")
+
+        @client.on("disconnect")
+        def on_disconnect():
+            print("Lost connection.")
+
+        @client.on_error()
+        def on_error(error):
+            print(f"Error: {error}")
+
+        client.connect()
+    """
+
+    def __init__(self, host: str = "localhost", port: int = 5000):
+        self.host = host
+        self.port = port
+        self._uri = f"ws://{host}:{port}"
+
+        self._handlers: Dict[str, List[Callable]] = {}
+        self._error_handlers: List[Callable] = []
+
+        self._ws = None
+        self._connected = False
+        self._loop: Optional[asyncio.AbstractEventLoop] = None
+        # Messages sent before the connection is ready are queued
+        # and flushed automatically once connected
+        self._send_queue: List[tuple] = []
+
+    def on(self, event: str) -> Callable:
+        """
+        Register a handler for a server event.
+
+        Built-in events: ``"connect"``, ``"disconnect"``
+
+        Handler signatures:
+
+        - connect / disconnect: ``fn()``
+        - all others: ``fn(data)``
+
+        Example::
+
+            @client.on("game_start")
+            def on_start(data):
+                print("Game starting!")
+        """
+        def decorator(fn: Callable) -> Callable:
+            self._handlers.setdefault(event, []).append(fn)
+            return fn
+        return decorator
+
+    def on_error(self) -> Callable:
+        """
+        Register an error handler.
+
+        Example::
+
+            @client.on_error()
+            def on_error(error):
+                print(f"Something went wrong: {error}")
+        """
+        def decorator(fn: Callable) -> Callable:
+            self._error_handlers.append(fn)
+            return fn
+        return decorator
+
+    def connect(self) -> None:
+        """Connect to the server. Blocks until disconnected."""
+        try:
+            asyncio.run(self._run())
+        except KeyboardInterrupt:
+            logger.info("Client disconnected.")
+
+    async def _run(self) -> None:
+        self._loop = asyncio.get_event_loop()
+        did_connect = False
+        logger.info(f"Connecting to {self._uri}")
+        try:
+            async with websockets.connect(self._uri) as ws:
+                self._ws = ws
+                self._connected = True
+                did_connect = True
+                # Flush any messages queued before connection was ready
+                for queued_event, queued_data in self._send_queue:
+                    await self._send_raw(queued_event, queued_data)
+                self._send_queue.clear()
+                await self._fire_single("connect")
+
+                async for raw in ws:
+                    try:
+                        message = json.loads(raw)
+                        await self._handle_message(message)
+                    except json.JSONDecodeError:
+                        logger.warning(f"Malformed message: {raw!r}")
+                    except Exception as e:
+                        logger.error(f"Message error: {e}", exc_info=True)
+                        await self._fire_error(e)
+
+        except ConnectionClosed:
+            logger.info("Disconnected from server")
+        except OSError as e:
+            err = ConnectionError(f"Could not connect to {self._uri}: {e}")
+            logger.error(str(err))
+            await self._fire_error(err)
+        finally:
+            self._connected = False
+            self._ws = None
+            self._loop = None
+            if did_connect:
+                await self._fire_single("disconnect")
+
+    async def _handle_message(self, message: dict) -> None:
+        event = message.get("event")
+        data = message.get("data", {})
+        if event:
+            await self._fire(event, data)
+
+    def send(self, event: str, data: Any = None) -> None:
+        """
+        Send an event + data to the server.
+
+        Safe to call from any thread. Messages sent before the connection
+        is established are queued and delivered automatically once connected.
+
+        Example::
+
+            client.send("move", {"x": 10, "y": 20})
+            client.send("chat", {"msg": "hello!"})
+        """
+        if not self._connected or not self._ws:
+            self._send_queue.append((event, data))
+            return
+
+        coro = self._send_raw(event, data)
+        if self._loop and self._loop.is_running():
+            try:
+                asyncio.ensure_future(coro, loop=self._loop)
+            except RuntimeError:
+                asyncio.run_coroutine_threadsafe(coro, self._loop)
+        elif self._loop:
+            asyncio.run_coroutine_threadsafe(coro, self._loop)
+
+    async def _send_raw(self, event: str, data: Any = None) -> None:
+        if self._ws and self._connected:
+            try:
+                await self._ws.send(json.dumps({"event": event, "data": data}))
+            except ConnectionClosed:
+                self._connected = False
+            except Exception as e:
+                logger.error(f"Send error: {e}")
+                await self._fire_error(e)
+
+    async def _fire_single(self, event: str) -> None:
+        for handler in self._handlers.get(event, []):
+            try:
+                result = handler()
+                if asyncio.iscoroutine(result):
+                    await result
+            except Exception as e:
+                logger.error(f"Error in '{event}' handler: {e}", exc_info=True)
+                await self._fire_error(e)
+
+    async def _fire(self, event: str, data: Any) -> None:
+        for handler in self._handlers.get(event, []):
+            try:
+                result = handler(data)
+                if asyncio.iscoroutine(result):
+                    await result
+            except Exception as e:
+                logger.error(f"Error in '{event}' handler: {e}", exc_info=True)
+                await self._fire_error(e)
+
+    async def _fire_error(self, error: Exception) -> None:
+        if self._error_handlers:
+            for handler in self._error_handlers:
+                try:
+                    result = handler(error)
+                    if asyncio.iscoroutine(result):
+                        await result
+                except Exception as e:
+                    logger.error(f"Error in error handler: {e}", exc_info=True)
+        else:
+            logger.error(
+                f"Unhandled error (register @client.on_error() to catch): {error}"
+            )