rlstatsapi 0.1.0__tar.gz → 0.1.2__tar.gz

rlstatsapi-0.1.2/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: rlstatsapi
+Version: 0.1.2
+Summary: Rocket League Stats API client
+Author: Manuel Cabral
+License: MIT
+Project-URL: Homepage, https://github.com/manucabral/RocketLeagueStatsAPI
+Keywords: rocket-league,stats,socket,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
+
+# RL Stats API
+
+`rlstatsapi` is a simple and fast Python client for reading live Rocket League Stats API events over a local TCP socket.
+
+## Install
+
+From PyPI:
+
+```bash
+pip install rlstatsapi
+```
+
+From GitHub (latest `main`):
+
+```bash
+pip install git+https://github.com/manucabral/RocketLeagueStatsAPI.git
+```
+
+## Rocket League setup
+
+Before launching Rocket League, edit:
+
+`<Install Dir>\TAGame\Config\DefaultStatsAPI.ini`
+
+Use at least:
+
+- `PacketSendRate=30` (any value `> 0` enables the exporter)
+- `Port=49123`
+
+Restart the game after changing the file.
+
+## Quick start
+
+```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())
+```
+
+## Example Event (Goals)
+
+```python
+import asyncio
+from rlstatsapi import StatsClient
+from rlstatsapi.models import EventMessage
+from rlstatsapi.types import GoalScoredPayload, cast_event_data
+
+async def on_goal(msg: EventMessage) -> None:
+    data: GoalScoredPayload = cast_event_data("GoalScored", msg.data)
+    scorer = data.get("Scorer", {})
+    print("Goal by:", scorer.get("Name"))
+
+async def main() -> None:
+    client = StatsClient()
+    client.on("GoalScored", on_goal)
+    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()`
+- typed helpers: `EventName`, `TypedEventMessage[...]`, `cast_event_data(...)`
+
+
+## Notes
+
+- Works for regular matches. Some fields like `MatchGuid` are only present in online/LAN contexts.
+- In current builds this endpoint may behave as plain TCP JSON stream instead of websocket upgrade. This library handles the TCP stream format.

rlstatsapi-0.1.2/README.md

@@ -0,0 +1,93 @@
+# RL Stats API
+
+`rlstatsapi` is a simple and fast Python client for reading live Rocket League Stats API events over a local TCP socket.
+
+## Install
+
+From PyPI:
+
+```bash
+pip install rlstatsapi
+```
+
+From GitHub (latest `main`):
+
+```bash
+pip install git+https://github.com/manucabral/RocketLeagueStatsAPI.git
+```
+
+## Rocket League setup
+
+Before launching Rocket League, edit:
+
+`<Install Dir>\TAGame\Config\DefaultStatsAPI.ini`
+
+Use at least:
+
+- `PacketSendRate=30` (any value `> 0` enables the exporter)
+- `Port=49123`
+
+Restart the game after changing the file.
+
+## Quick start
+
+```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())
+```
+
+## Example Event (Goals)
+
+```python
+import asyncio
+from rlstatsapi import StatsClient
+from rlstatsapi.models import EventMessage
+from rlstatsapi.types import GoalScoredPayload, cast_event_data
+
+async def on_goal(msg: EventMessage) -> None:
+    data: GoalScoredPayload = cast_event_data("GoalScored", msg.data)
+    scorer = data.get("Scorer", {})
+    print("Goal by:", scorer.get("Name"))
+
+async def main() -> None:
+    client = StatsClient()
+    client.on("GoalScored", on_goal)
+    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()`
+- typed helpers: `EventName`, `TypedEventMessage[...]`, `cast_event_data(...)`
+
+
+## Notes
+
+- Works for regular matches. Some fields like `MatchGuid` are only present in online/LAN contexts.
+- In current builds this endpoint may behave as plain TCP JSON stream instead of websocket upgrade. This library handles the TCP stream format.

{rlstatsapi-0.1.0 → rlstatsapi-0.1.2}/pyproject.toml

@@ -1,30 +1,30 @@
-[build-system]
-requires = ["setuptools>=69", "wheel"]
-build-backend = "setuptools.build_meta"
-
-[project]
-name = "rlstatsapi"
-version = "0.1.0"
-description = "Rocket League Stats API client"
-readme = "README.md"
-requires-python = ">=3.11"
-license = { text = "MIT" }
-authors = [{ name = "Manuel Cabral" }]
-keywords = ["rocket-league", "stats", "websocket", "asyncio"]
-classifiers = [
-  "Programming Language :: Python :: 3",
-  "Programming Language :: Python :: 3 :: Only",
-  "License :: OSI Approved :: MIT License",
-  "Operating System :: OS Independent",
-  "Topic :: Games/Entertainment",
-  "Topic :: Software Development :: Libraries",
-]
-
-[project.urls]
-Homepage = "https://github.com/manucabral/RocketLeagueStatsAPI"
-
-[tool.setuptools]
-package-dir = {"" = "src"}
-
-[tool.setuptools.packages.find]
-where = ["src"]
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "rlstatsapi"
+version = "0.1.2"
+description = "Rocket League Stats API client"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Manuel Cabral" }]
+keywords = ["rocket-league", "stats", "socket", "asyncio"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Topic :: Games/Entertainment",
+  "Topic :: Software Development :: Libraries",
+]
+
+[project.urls]
+Homepage = "https://github.com/manucabral/RocketLeagueStatsAPI"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

rlstatsapi-0.1.2/src/rlstatsapi/__init__.py

@@ -0,0 +1,25 @@
+"""rlstatsapi public API."""
+
+from .client import StatsClient
+from .events import KNOWN_EVENTS
+from .models import EventMessage
+from .types import (
+    EventName,
+    GoalScoredPayload,
+    KnownEventMessage,
+    TypedEventMessage,
+    UpdateStatePayload,
+    cast_event_data,
+)
+
+__all__ = [
+    "StatsClient",
+    "EventMessage",
+    "KNOWN_EVENTS",
+    "EventName",
+    "TypedEventMessage",
+    "KnownEventMessage",
+    "UpdateStatePayload",
+    "GoalScoredPayload",
+    "cast_event_data",
+]

{rlstatsapi-0.1.0 → rlstatsapi-0.1.2}/src/rlstatsapi/client.py

@@ -9,7 +9,6 @@ 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]
 
@@ -41,7 +40,8 @@ class StatsClient:
         self._handlers_any: list[Handler] = []
         self._logger = logging.getLogger("rlstatsapi")
 
-        self._ws: SimpleWebSocket | None = None
+        self._reader: asyncio.StreamReader | None = None
+        self._writer: asyncio.StreamWriter | None = None
         self._reader_task: asyncio.Task[None] | None = None
         self._stopping = False
 
@@ -58,10 +58,12 @@ class StatsClient:
         self._stopping = True
         self._log("disconnect requested")
 
-        if self._ws is not None:
+        if self._writer is not None:
             with contextlib.suppress(Exception):
-                await self._ws.close()
-            self._ws = None
+                self._writer.close()
+                await self._writer.wait_closed()
+            self._writer = None
+            self._reader = None
 
         if self._reader_task is not None:
             self._reader_task.cancel()
@@ -83,14 +85,13 @@ class StatsClient:
     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,
+                self._log(f"connecting to tcp://{self.host}:{self.port}")
+                self._reader, self._writer = await asyncio.wait_for(
+                    asyncio.open_connection(host=self.host, port=self.port),
                     timeout=self.connect_timeout,
                 )
-                self._log("websocket connected")
-                await self._read_loop(self._ws)
+                self._log("tcp socket connected")
+                await self._read_loop(self._reader)
             except asyncio.CancelledError:
                 self._log("reader task cancelled")
                 raise
@@ -102,22 +103,48 @@ class StatsClient:
                 self._log(f"reconnecting in {self.reconnect_delay:.2f}s")
                 await asyncio.sleep(self.reconnect_delay)
             finally:
-                if self._ws is not None:
+                if self._writer 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:
+                        self._writer.close()
+                        await self._writer.wait_closed()
+                    self._writer = None
+                    self._reader = None
+                    self._log("tcp socket closed")
+
+    async def _read_loop(self, reader: asyncio.StreamReader) -> None:
+        decoder = json.JSONDecoder()
+        buffer = ""
         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
+            chunk = await reader.read(4096)
+            if not chunk:
+                raise ConnectionAbortedError("Socket closed by peer")
+            buffer += chunk.decode("utf-8", errors="ignore")
+
+            while True:
+                lstripped = buffer.lstrip()
+                if not lstripped:
+                    buffer = ""
+                    break
+                if lstripped is not buffer:
+                    buffer = lstripped
+
+                try:
+                    decoded, end_idx = decoder.raw_decode(buffer)
+                except json.JSONDecodeError:
+                    break
+
+                raw = buffer[:end_idx]
+                buffer = buffer[end_idx:]
+
+                message = _parse_message_obj(
+                    decoded, raw=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)
+                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, [])
@@ -137,16 +164,21 @@ class StatsClient:
             self._logger.info("[StatsClient] %s", message)
 
 
-def _parse_message(raw: str, *, include_raw: bool) -> EventMessage | None:
-    try:
-        decoded = json.loads(raw)
-    except json.JSONDecodeError:
+def _parse_message_obj(
+    decoded: Any, *, raw: str, include_raw: bool
+) -> EventMessage | None:
+    if not isinstance(decoded, dict):
         return None
-
     event = decoded.get("Event")
     data = decoded.get("Data")
 
+    if isinstance(data, str):
+        try:
+            data = json.loads(data)
+        except json.JSONDecodeError:
+            return None
+
     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)
+    return EventMessage(event=event, data=data, raw=raw if include_raw else None)

rlstatsapi-0.1.2/src/rlstatsapi/types.py

@@ -0,0 +1,373 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Generic, Literal, Mapping, TypeAlias, TypeVar, TypedDict, cast, overload
+
+EventName: TypeAlias = Literal[
+    "UpdateState",
+    "BallHit",
+    "ClockUpdatedSeconds",
+    "CountdownBegin",
+    "CrossbarHit",
+    "GoalReplayEnd",
+    "GoalReplayStart",
+    "GoalReplayWillEnd",
+    "GoalScored",
+    "MatchCreated",
+    "MatchInitialized",
+    "MatchDestroyed",
+    "MatchEnded",
+    "MatchPaused",
+    "MatchUnpaused",
+    "PodiumStart",
+    "ReplayCreated",
+    "RoundStarted",
+    "StatfeedEvent",
+]
+
+
+class Vector3(TypedDict):
+    X: float
+    Y: float
+    Z: float
+
+
+class PlayerRef(TypedDict):
+    Name: str
+    Shortcut: int
+    TeamNum: int
+
+
+class TeamState(TypedDict):
+    Name: str
+    TeamNum: int
+    Score: int
+    ColorPrimary: str
+    ColorSecondary: str
+
+
+class BallState(TypedDict):
+    Speed: float
+    TeamNum: int
+
+
+class PlayerAttacker(TypedDict):
+    Name: str
+    Shortcut: int
+    TeamNum: int
+
+
+class TargetRef(TypedDict):
+    Name: str
+    Shortcut: int
+    TeamNum: int
+
+
+class UpdateStatePlayer(TypedDict, total=False):
+    Name: str
+    PrimaryId: str
+    Shortcut: int
+    TeamNum: int
+    Score: int
+    Goals: int
+    Shots: int
+    Assists: int
+    Saves: int
+    Touches: int
+    CarTouches: int
+    Demos: int
+    bHasCar: bool
+    Speed: float
+    Boost: int
+    bBoosting: bool
+    bOnGround: bool
+    bOnWall: bool
+    bPowersliding: bool
+    bDemolished: bool
+    Attacker: PlayerAttacker
+    bSupersonic: bool
+
+
+class UpdateStateGame(TypedDict, total=False):
+    Teams: list[TeamState]
+    TimeSeconds: int
+    bOvertime: bool
+    Frame: int
+    Elapsed: float
+    Ball: BallState
+    bReplay: bool
+    bHasWinner: bool
+    Winner: str
+    Arena: str
+    bHasTarget: bool
+    Target: TargetRef
+
+
+class UpdateStatePayload(TypedDict, total=False):
+    MatchGuid: str
+    Players: list[UpdateStatePlayer]
+    Game: UpdateStateGame
+
+
+class BallHitBall(TypedDict):
+    PreHitSpeed: float
+    PostHitSpeed: float
+    Location: Vector3
+
+
+class BallHitPayload(TypedDict, total=False):
+    MatchGuid: str
+    Players: list[PlayerRef]
+    Ball: BallHitBall
+
+
+class ClockUpdatedSecondsPayload(TypedDict, total=False):
+    MatchGuid: str
+    TimeSeconds: int
+    bOvertime: bool
+
+
+class CountdownBeginPayload(TypedDict, total=False):
+    MatchGuid: str
+
+
+class BallLastTouch(TypedDict):
+    Player: PlayerRef
+    Speed: float
+
+
+class CrossbarHitPayload(TypedDict, total=False):
+    MatchGuid: str
+    BallLocation: Vector3
+    BallSpeed: float
+    ImpactForce: float
+    BallLastTouch: BallLastTouch
+
+
+class GoalReplayEndPayload(TypedDict, total=False):
+    MatchGuid: str
+
+
+class GoalReplayStartPayload(TypedDict, total=False):
+    MatchGuid: str
+
+
+class GoalReplayWillEndPayload(TypedDict, total=False):
+    MatchGuid: str
+
+
+class GoalScoredPayload(TypedDict, total=False):
+    MatchGuid: str
+    GoalSpeed: float
+    GoalTime: float
+    ImpactLocation: Vector3
+    Scorer: PlayerRef
+    Assister: PlayerRef
+    BallLastTouch: BallLastTouch
+
+
+class MatchCreatedPayload(TypedDict, total=False):
+    MatchGuid: str
+
+
+class MatchInitializedPayload(TypedDict, total=False):
+    MatchGuid: str
+
+
+class MatchDestroyedPayload(TypedDict, total=False):
+    MatchGuid: str
+
+
+class MatchEndedPayload(TypedDict, total=False):
+    MatchGuid: str
+    WinnerTeamNum: int
+
+
+class MatchPausedPayload(TypedDict, total=False):
+    MatchGuid: str
+
+
+class MatchUnpausedPayload(TypedDict, total=False):
+    MatchGuid: str
+
+
+class PodiumStartPayload(TypedDict, total=False):
+    MatchGuid: str
+
+
+class ReplayCreatedPayload(TypedDict, total=False):
+    MatchGuid: str
+
+
+class RoundStartedPayload(TypedDict, total=False):
+    MatchGuid: str
+
+
+class StatfeedEventPayload(TypedDict, total=False):
+    MatchGuid: str
+    EventName: str
+    Type: str
+    MainTarget: PlayerRef
+    SecondaryTarget: PlayerRef
+
+
+KnownEventPayload: TypeAlias = (
+    UpdateStatePayload
+    | BallHitPayload
+    | ClockUpdatedSecondsPayload
+    | CountdownBeginPayload
+    | CrossbarHitPayload
+    | GoalReplayEndPayload
+    | GoalReplayStartPayload
+    | GoalReplayWillEndPayload
+    | GoalScoredPayload
+    | MatchCreatedPayload
+    | MatchInitializedPayload
+    | MatchDestroyedPayload
+    | MatchEndedPayload
+    | MatchPausedPayload
+    | MatchUnpausedPayload
+    | PodiumStartPayload
+    | ReplayCreatedPayload
+    | RoundStartedPayload
+    | StatfeedEventPayload
+)
+
+KnownEventPayloadMap: TypeAlias = dict[EventName, KnownEventPayload]
+
+TData = TypeVar("TData", bound=Mapping[str, Any])
+
+
+@dataclass(slots=True)
+class TypedEventMessage(Generic[TData]):
+    event: str
+    data: TData
+    raw: str | None = None
+
+
+KnownEventMessage: TypeAlias = TypedEventMessage[KnownEventPayload]
+
+
+@overload
+def cast_event_data(
+    event_name: Literal["UpdateState"], data: Mapping[str, Any]
+) -> UpdateStatePayload: ...
+
+
+@overload
+def cast_event_data(
+    event_name: Literal["BallHit"], data: Mapping[str, Any]
+) -> BallHitPayload: ...
+
+
+@overload
+def cast_event_data(
+    event_name: Literal["ClockUpdatedSeconds"], data: Mapping[str, Any]
+) -> ClockUpdatedSecondsPayload: ...
+
+
+@overload
+def cast_event_data(
+    event_name: Literal["CountdownBegin"], data: Mapping[str, Any]
+) -> CountdownBeginPayload: ...
+
+
+@overload
+def cast_event_data(
+    event_name: Literal["CrossbarHit"], data: Mapping[str, Any]
+) -> CrossbarHitPayload: ...
+
+
+@overload
+def cast_event_data(
+    event_name: Literal["GoalReplayEnd"], data: Mapping[str, Any]
+) -> GoalReplayEndPayload: ...
+
+
+@overload
+def cast_event_data(
+    event_name: Literal["GoalReplayStart"], data: Mapping[str, Any]
+) -> GoalReplayStartPayload: ...
+
+
+@overload
+def cast_event_data(
+    event_name: Literal["GoalReplayWillEnd"], data: Mapping[str, Any]
+) -> GoalReplayWillEndPayload: ...
+
+
+@overload
+def cast_event_data(
+    event_name: Literal["GoalScored"], data: Mapping[str, Any]
+) -> GoalScoredPayload: ...
+
+
+@overload
+def cast_event_data(
+    event_name: Literal["MatchCreated"], data: Mapping[str, Any]
+) -> MatchCreatedPayload: ...
+
+
+@overload
+def cast_event_data(
+    event_name: Literal["MatchInitialized"], data: Mapping[str, Any]
+) -> MatchInitializedPayload: ...
+
+
+@overload
+def cast_event_data(
+    event_name: Literal["MatchDestroyed"], data: Mapping[str, Any]
+) -> MatchDestroyedPayload: ...
+
+
+@overload
+def cast_event_data(
+    event_name: Literal["MatchEnded"], data: Mapping[str, Any]
+) -> MatchEndedPayload: ...
+
+
+@overload
+def cast_event_data(
+    event_name: Literal["MatchPaused"], data: Mapping[str, Any]
+) -> MatchPausedPayload: ...
+
+
+@overload
+def cast_event_data(
+    event_name: Literal["MatchUnpaused"], data: Mapping[str, Any]
+) -> MatchUnpausedPayload: ...
+
+
+@overload
+def cast_event_data(
+    event_name: Literal["PodiumStart"], data: Mapping[str, Any]
+) -> PodiumStartPayload: ...
+
+
+@overload
+def cast_event_data(
+    event_name: Literal["ReplayCreated"], data: Mapping[str, Any]
+) -> ReplayCreatedPayload: ...
+
+
+@overload
+def cast_event_data(
+    event_name: Literal["RoundStarted"], data: Mapping[str, Any]
+) -> RoundStartedPayload: ...
+
+
+@overload
+def cast_event_data(
+    event_name: Literal["StatfeedEvent"], data: Mapping[str, Any]
+) -> StatfeedEventPayload: ...
+
+
+@overload
+def cast_event_data(event_name: str, data: Mapping[str, Any]) -> Mapping[str, Any]: ...
+
+
+def cast_event_data(event_name: str, data: Mapping[str, Any]) -> Mapping[str, Any]:
+    """Type-only helper to narrow `data` based on event name."""
+
+    _ = event_name
+    return cast(Mapping[str, Any], data)

rlstatsapi-0.1.2/src/rlstatsapi.egg-info/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: rlstatsapi
+Version: 0.1.2
+Summary: Rocket League Stats API client
+Author: Manuel Cabral
+License: MIT
+Project-URL: Homepage, https://github.com/manucabral/RocketLeagueStatsAPI
+Keywords: rocket-league,stats,socket,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
+
+# RL Stats API
+
+`rlstatsapi` is a simple and fast Python client for reading live Rocket League Stats API events over a local TCP socket.
+
+## Install
+
+From PyPI:
+
+```bash
+pip install rlstatsapi
+```
+
+From GitHub (latest `main`):
+
+```bash
+pip install git+https://github.com/manucabral/RocketLeagueStatsAPI.git
+```
+
+## Rocket League setup
+
+Before launching Rocket League, edit:
+
+`<Install Dir>\TAGame\Config\DefaultStatsAPI.ini`
+
+Use at least:
+
+- `PacketSendRate=30` (any value `> 0` enables the exporter)
+- `Port=49123`
+
+Restart the game after changing the file.
+
+## Quick start
+
+```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())
+```
+
+## Example Event (Goals)
+
+```python
+import asyncio
+from rlstatsapi import StatsClient
+from rlstatsapi.models import EventMessage
+from rlstatsapi.types import GoalScoredPayload, cast_event_data
+
+async def on_goal(msg: EventMessage) -> None:
+    data: GoalScoredPayload = cast_event_data("GoalScored", msg.data)
+    scorer = data.get("Scorer", {})
+    print("Goal by:", scorer.get("Name"))
+
+async def main() -> None:
+    client = StatsClient()
+    client.on("GoalScored", on_goal)
+    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()`
+- typed helpers: `EventName`, `TypedEventMessage[...]`, `cast_event_data(...)`
+
+
+## Notes
+
+- Works for regular matches. Some fields like `MatchGuid` are only present in online/LAN contexts.
+- In current builds this endpoint may behave as plain TCP JSON stream instead of websocket upgrade. This library handles the TCP stream format.

{rlstatsapi-0.1.0 → rlstatsapi-0.1.2}/src/rlstatsapi.egg-info/SOURCES.txt

@@ -2,10 +2,10 @@ LICENSE
 README.md
 pyproject.toml
 src/rlstatsapi/__init__.py
-src/rlstatsapi/_websocket.py
 src/rlstatsapi/client.py
 src/rlstatsapi/events.py
 src/rlstatsapi/models.py
+src/rlstatsapi/types.py
 src/rlstatsapi.egg-info/PKG-INFO
 src/rlstatsapi.egg-info/SOURCES.txt
 src/rlstatsapi.egg-info/dependency_links.txt

rlstatsapi-0.1.0/PKG-INFO

@@ -1,74 +0,0 @@
-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/README.md

@@ -1,55 +0,0 @@
-# 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/src/rlstatsapi/__init__.py

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

rlstatsapi-0.1.0/src/rlstatsapi/_websocket.py

@@ -1,176 +0,0 @@
-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-0.1.0/src/rlstatsapi.egg-info/PKG-INFO

@@ -1,74 +0,0 @@
-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()`