rlstatsapi 0.1.1__tar.gz → 0.1.2__tar.gz

{rlstatsapi-0.1.1/src/rlstatsapi.egg-info → rlstatsapi-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rlstatsapi
-Version: 0.1.1
+Version: 0.1.2
 Summary: Rocket League Stats API client
 Author: Manuel Cabral
 License: MIT
@@ -32,7 +32,7 @@ pip install rlstatsapi
 From GitHub (latest `main`):
 
 ```bash
-pip install git+https://github.com/nania/RocketLeagueStatsAPI.git
+pip install git+https://github.com/manucabral/RocketLeagueStatsAPI.git
 ```
 
 ## Rocket League setup
@@ -57,7 +57,6 @@ 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))
@@ -68,17 +67,44 @@ async def main() -> None:
     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(host="127.0.0.1", port=49123, reconnect=True, reconnect_delay=0.5, include_raw=False, queue_size=2048, connect_timeout=5.0, log_enabled=False)`
+- `StatsClient(...)`
 - `connect()` / `disconnect()`
 - `on(event_name, handler)`
 - `on_any(handler)`
 - `events()`
+- typed helpers: `EventName`, `TypedEventMessage[...]`, `cast_event_data(...)`
+
 
 ## Notes
 

{rlstatsapi-0.1.1 → rlstatsapi-0.1.2}/README.md

@@ -13,7 +13,7 @@ pip install rlstatsapi
 From GitHub (latest `main`):
 
 ```bash
-pip install git+https://github.com/nania/RocketLeagueStatsAPI.git
+pip install git+https://github.com/manucabral/RocketLeagueStatsAPI.git
 ```
 
 ## Rocket League setup
@@ -38,7 +38,6 @@ 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))
@@ -49,19 +48,46 @@ async def main() -> None:
     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(host="127.0.0.1", port=49123, reconnect=True, reconnect_delay=0.5, include_raw=False, queue_size=2048, connect_timeout=5.0, log_enabled=False)`
+- `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.
+- 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.1 → 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.1"
-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"]
+[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.1 → rlstatsapi-0.1.2}/src/rlstatsapi/client.py

@@ -181,4 +181,4 @@ def _parse_message_obj(
     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.1 → rlstatsapi-0.1.2/src/rlstatsapi.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rlstatsapi
-Version: 0.1.1
+Version: 0.1.2
 Summary: Rocket League Stats API client
 Author: Manuel Cabral
 License: MIT
@@ -32,7 +32,7 @@ pip install rlstatsapi
 From GitHub (latest `main`):
 
 ```bash
-pip install git+https://github.com/nania/RocketLeagueStatsAPI.git
+pip install git+https://github.com/manucabral/RocketLeagueStatsAPI.git
 ```
 
 ## Rocket League setup
@@ -57,7 +57,6 @@ 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))
@@ -68,17 +67,44 @@ async def main() -> None:
     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(host="127.0.0.1", port=49123, reconnect=True, reconnect_delay=0.5, include_raw=False, queue_size=2048, connect_timeout=5.0, log_enabled=False)`
+- `StatsClient(...)`
 - `connect()` / `disconnect()`
 - `on(event_name, handler)`
 - `on_any(handler)`
 - `events()`
+- typed helpers: `EventName`, `TypedEventMessage[...]`, `cast_event_data(...)`
+
 
 ## Notes
 

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

@@ -5,6 +5,7 @@ src/rlstatsapi/__init__.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.1/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"]