rlstatsapi 0.1.0__py3-none-any.whl

rlstatsapi/__init__.py

@@ -0,0 +1,7 @@
+"""rlstatsapi public API."""
+
+from .client import StatsClient
+from .models import EventMessage
+from .events import KNOWN_EVENTS
+
+__all__ = ["StatsClient", "EventMessage", "KNOWN_EVENTS"]

rlstatsapi/_websocket.py

@@ -0,0 +1,176 @@
+from __future__ import annotations
+
+import asyncio
+import base64
+import hashlib
+import os
+import ssl
+from dataclasses import dataclass
+
+_WS_GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
+
+
+class WebSocketHandshakeError(ConnectionError):
+    """Raised when websocket upgrade fails."""
+
+
+@dataclass(slots=True)
+class SimpleWebSocket:
+    """Minimal stdlib websocket client optimized for receiving text frames."""
+
+    reader: asyncio.StreamReader
+    writer: asyncio.StreamWriter
+
+    async def recv_text(self) -> str:
+        opcode, payload = await self._read_frame()
+
+        if opcode == 0x8:  # close
+            await self.close()
+            raise ConnectionAbortedError("Websocket closed by peer")
+        if opcode == 0x9:  # ping
+            await self._send_pong(payload)
+            return await self.recv_text()
+        if opcode == 0xA:  # pong
+            return await self.recv_text()
+        if opcode != 0x1:
+            raise ConnectionError(f"Unsupported opcode: {opcode}")
+
+        return payload.decode("utf-8")
+
+    async def close(self) -> None:
+        if self.writer.is_closing():
+            return
+        try:
+            await self._send_frame(0x8, b"")
+        except Exception:
+            pass
+        self.writer.close()
+        await self.writer.wait_closed()
+
+    async def _send_pong(self, payload: bytes) -> None:
+        await self._send_frame(0xA, payload)
+
+    async def _send_frame(self, opcode: int, payload: bytes) -> None:
+        fin_and_opcode = 0x80 | (opcode & 0x0F)
+        mask_and_len = 0x80
+        payload_len = len(payload)
+
+        header = bytearray([fin_and_opcode])
+        if payload_len < 126:
+            header.append(mask_and_len | payload_len)
+        elif payload_len <= 0xFFFF:
+            header.append(mask_and_len | 126)
+            header.extend(payload_len.to_bytes(2, "big"))
+        else:
+            header.append(mask_and_len | 127)
+            header.extend(payload_len.to_bytes(8, "big"))
+
+        mask = os.urandom(4)
+        header.extend(mask)
+
+        masked_payload = bytes(b ^ mask[i % 4] for i, b in enumerate(payload))
+
+        self.writer.write(header)
+        self.writer.write(masked_payload)
+        await self.writer.drain()
+
+    async def _read_frame(self) -> tuple[int, bytes]:
+        first_two = await self.reader.readexactly(2)
+        first, second = first_two[0], first_two[1]
+
+        fin = (first & 0x80) != 0
+        opcode = first & 0x0F
+        masked = (second & 0x80) != 0
+        payload_len = second & 0x7F
+
+        if payload_len == 126:
+            payload_len = int.from_bytes(await self.reader.readexactly(2), "big")
+        elif payload_len == 127:
+            payload_len = int.from_bytes(await self.reader.readexactly(8), "big")
+
+        mask_key = await self.reader.readexactly(4) if masked else b""
+        payload = await self.reader.readexactly(payload_len)
+
+        if masked:
+            payload = bytes(b ^ mask_key[i % 4] for i, b in enumerate(payload))
+
+        if not fin:
+            raise ConnectionError("Fragmented frames are not supported")
+
+        return opcode, payload
+
+
+async def connect_websocket(
+    *,
+    host: str,
+    port: int,
+    path: str = "/",
+    timeout: float = 5.0,
+    secure: bool = False,
+) -> SimpleWebSocket:
+    """Open websocket connection via stdlib stream upgrade."""
+
+    key = base64.b64encode(os.urandom(16)).decode("ascii")
+
+    ssl_ctx = ssl.create_default_context() if secure else None
+    reader, writer = await asyncio.wait_for(
+        asyncio.open_connection(host=host, port=port, ssl=ssl_ctx),
+        timeout=timeout,
+    )
+
+    request = (
+        f"GET {path} HTTP/1.1\r\n"
+        f"Host: {host}:{port}\r\n"
+        "Upgrade: websocket\r\n"
+        "Connection: Upgrade\r\n"
+        f"Sec-WebSocket-Key: {key}\r\n"
+        "Sec-WebSocket-Version: 13\r\n"
+        "\r\n"
+    )
+
+    writer.write(request.encode("ascii"))
+    await writer.drain()
+
+    response = await _read_http_response(reader)
+    status_line = response[0]
+
+    if " 101 " not in status_line:
+        writer.close()
+        await writer.wait_closed()
+        raise WebSocketHandshakeError(f"Handshake failed: {status_line.strip()}")
+
+    headers = _parse_headers(response[1:])
+    accept = headers.get("sec-websocket-accept")
+
+    expected = base64.b64encode(
+        hashlib.sha1((key + _WS_GUID).encode("ascii")).digest()
+    ).decode("ascii")
+    if accept != expected:
+        writer.close()
+        await writer.wait_closed()
+        raise WebSocketHandshakeError("Invalid Sec-WebSocket-Accept from server")
+
+    return SimpleWebSocket(reader=reader, writer=writer)
+
+
+async def _read_http_response(reader: asyncio.StreamReader) -> list[str]:
+    lines: list[str] = []
+    while True:
+        line = (await reader.readline()).decode("iso-8859-1")
+        if not line:
+            raise WebSocketHandshakeError("Unexpected EOF during handshake")
+        lines.append(line)
+        if line == "\r\n":
+            return lines
+
+
+def _parse_headers(lines: list[str]) -> dict[str, str]:
+    headers: dict[str, str] = {}
+    for line in lines:
+        if line == "\r\n":
+            break
+        if ":" not in line:
+            continue
+        key, value = line.split(":", 1)
+        headers[key.strip().lower()] = value.strip()
+    return headers

rlstatsapi/client.py

@@ -0,0 +1,152 @@
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import inspect
+import json
+import logging
+from collections import defaultdict
+from typing import Any, AsyncIterator, Awaitable, Callable
+
+from .models import EventMessage
+from ._websocket import SimpleWebSocket, connect_websocket
+
+Handler = Callable[[EventMessage], Awaitable[None] | None]
+
+
+class StatsClient:
+    """High-throughput asyncio client for Rocket League Stats API."""
+
+    def __init__(
+        self,
+        host: str = "127.0.0.1",
+        port: int = 49123,
+        reconnect: bool = True,
+        reconnect_delay: float = 0.5,
+        include_raw: bool = False,
+        queue_size: int = 2048,
+        connect_timeout: float = 5.0,
+        log_enabled: bool = False,
+    ) -> None:
+        self.host = host
+        self.port = port
+        self.reconnect = reconnect
+        self.reconnect_delay = reconnect_delay
+        self.include_raw = include_raw
+        self.connect_timeout = connect_timeout
+        self.log_enabled = log_enabled
+
+        self._queue: asyncio.Queue[EventMessage] = asyncio.Queue(maxsize=queue_size)
+        self._handlers_by_event: dict[str, list[Handler]] = defaultdict(list)
+        self._handlers_any: list[Handler] = []
+        self._logger = logging.getLogger("rlstatsapi")
+
+        self._ws: SimpleWebSocket | None = None
+        self._reader_task: asyncio.Task[None] | None = None
+        self._stopping = False
+
+    async def connect(self) -> None:
+        if self._reader_task and not self._reader_task.done():
+            self._log("connect() ignored: reader already running")
+            return
+
+        self._stopping = False
+        self._reader_task = asyncio.create_task(self._run(), name="rlstatsapi-reader")
+        self._log("reader task started")
+
+    async def disconnect(self) -> None:
+        self._stopping = True
+        self._log("disconnect requested")
+
+        if self._ws is not None:
+            with contextlib.suppress(Exception):
+                await self._ws.close()
+            self._ws = None
+
+        if self._reader_task is not None:
+            self._reader_task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await self._reader_task
+            self._reader_task = None
+        self._log("disconnected")
+
+    def on(self, event_name: str, handler: Handler) -> None:
+        self._handlers_by_event[event_name].append(handler)
+
+    def on_any(self, handler: Handler) -> None:
+        self._handlers_any.append(handler)
+
+    async def events(self) -> AsyncIterator[EventMessage]:
+        while True:
+            yield await self._queue.get()
+
+    async def _run(self) -> None:
+        while not self._stopping:
+            try:
+                self._log(f"connecting to ws://{self.host}:{self.port}")
+                self._ws = await connect_websocket(
+                    host=self.host,
+                    port=self.port,
+                    timeout=self.connect_timeout,
+                )
+                self._log("websocket connected")
+                await self._read_loop(self._ws)
+            except asyncio.CancelledError:
+                self._log("reader task cancelled")
+                raise
+            except Exception as exc:
+                self._log(f"connection/read error: {exc}")
+                if not self.reconnect or self._stopping:
+                    self._log("stopping reader (reconnect disabled or stopping)")
+                    return
+                self._log(f"reconnecting in {self.reconnect_delay:.2f}s")
+                await asyncio.sleep(self.reconnect_delay)
+            finally:
+                if self._ws is not None:
+                    with contextlib.suppress(Exception):
+                        await self._ws.close()
+                    self._ws = None
+                    self._log("websocket closed")
+
+    async def _read_loop(self, ws: SimpleWebSocket) -> None:
+        while not self._stopping:
+            raw = await ws.recv_text()
+            message = _parse_message(raw, include_raw=self.include_raw)
+            if message is None:
+                self._log("ignored invalid message (json/envelope)")
+                continue
+
+            await self._queue.put(message)
+            await self._dispatch(message)
+
+    async def _dispatch(self, message: EventMessage) -> None:
+        handlers = self._handlers_any + self._handlers_by_event.get(message.event, [])
+
+        for handler in handlers:
+            try:
+                result = handler(message)
+                if inspect.isawaitable(result):
+                    await result
+            except Exception as exc:
+                # Never kill the stream because of user handlers.
+                self._log(f"handler error for {message.event}: {exc}")
+                continue
+
+    def _log(self, message: str) -> None:
+        if self.log_enabled:
+            self._logger.info("[StatsClient] %s", message)
+
+
+def _parse_message(raw: str, *, include_raw: bool) -> EventMessage | None:
+    try:
+        decoded = json.loads(raw)
+    except json.JSONDecodeError:
+        return None
+
+    event = decoded.get("Event")
+    data = decoded.get("Data")
+
+    if not isinstance(event, str) or not isinstance(data, dict):
+        return None
+
+    return EventMessage(event=event, data=data, raw=raw if include_raw else None)

rlstatsapi/events.py

@@ -0,0 +1,29 @@
+"""
+Known Rocket League Stats API event names.
+Sources:
+    https://www.rocketleague.com/en/developer/stats-api
+"""
+
+KNOWN_EVENTS: frozenset[str] = frozenset(
+    {
+        "UpdateState",
+        "BallHit",
+        "ClockUpdatedSeconds",
+        "CountdownBegin",
+        "CrossbarHit",
+        "GoalReplayEnd",
+        "GoalReplayStart",
+        "GoalReplayWillEnd",
+        "GoalScored",
+        "MatchCreated",
+        "MatchInitialized",
+        "MatchDestroyed",
+        "MatchEnded",
+        "MatchPaused",
+        "MatchUnpaused",
+        "PodiumStart",
+        "ReplayCreated",
+        "RoundStarted",
+        "StatfeedEvent",
+    }
+)

rlstatsapi/models.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(slots=True)
+class EventMessage:
+    """Normalized Rocket League Stats API message envelope."""
+
+    event: str
+    data: dict[str, Any]
+    raw: str | None = None

rlstatsapi-0.1.0.dist-info/METADATA

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: rlstatsapi
+Version: 0.1.0
+Summary: Rocket League Stats API client
+Author: Manuel Cabral
+License: MIT
+Project-URL: Homepage, https://github.com/manucabral/RocketLeagueStatsAPI
+Keywords: rocket-league,stats,websocket,asyncio
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# rlstatsapi
+
+Simple and fast Python client to read Rocket League Stats API events.
+
+## Install
+
+```bash
+pip install -e .
+```
+
+## Configure Rocket League
+
+Before starting the game, edit:
+
+`<Install Dir>\TAGame\Config\DefaultStatsAPI.ini`
+
+Minimum required values:
+
+- `PacketSendRate=60` (any value > 0)
+- `Port=49123`
+
+Then restart Rocket League.
+
+## Quick usage
+
+```python
+import asyncio
+import logging
+from rlstatsapi import StatsClient
+
+logging.basicConfig(level=logging.INFO)
+
+
+async def main() -> None:
+    client = StatsClient(log_enabled=True)
+    client.on_any(lambda msg: print(msg.event, msg.data))
+
+    await client.connect()
+    try:
+        await asyncio.Event().wait()
+    finally:
+        await client.disconnect()
+
+
+asyncio.run(main())
+```
+
+## Public API
+
+- `StatsClient(...)`
+- `connect()`
+- `disconnect()`
+- `on(event_name, handler)`
+- `on_any(handler)`
+- `events()`

rlstatsapi-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+rlstatsapi/__init__.py,sha256=SoTKr3z3GE7TLVNUZFLC3vPLhRS2H5cwEX61537akxk,188
+rlstatsapi/_websocket.py,sha256=clcv8JyWmKltWaO1rdRz5Ass8Dw-PyLddyFkVVOCtPs,5287
+rlstatsapi/client.py,sha256=1BRMx4DhVhFSwO1RFNr9d48QHzunTc9ETh5Lle8szfc,5322
+rlstatsapi/events.py,sha256=JBiiZPmccErEnKkE4CkUT6itHVV6TzwgcuGReo82TzQ,643
+rlstatsapi/models.py,sha256=BxuLyRCRHMWB6l-gLTq5iJyMQtU5hnL4IbXVMXBcTLk,270
+rlstatsapi-0.1.0.dist-info/licenses/LICENSE,sha256=sGDuB5mcSzEcvUMdHUnzZ33HJOb_ywbBOeccH_yFy08,1082
+rlstatsapi-0.1.0.dist-info/METADATA,sha256=A5S1M8dZIzrbUDDfBddRa8ffPvxsuG5xly8Ji0S5M-Q,1617
+rlstatsapi-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+rlstatsapi-0.1.0.dist-info/top_level.txt,sha256=3EqyA0VBelcI4k7GKueCofwKoTkOhPUaPY8RZm0b36U,11
+rlstatsapi-0.1.0.dist-info/RECORD,,

rlstatsapi-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
+

rlstatsapi-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Manu
+
+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.

rlstatsapi-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+rlstatsapi