rlstatsapi 0.1.5__tar.gz → 0.1.6__tar.gz

{rlstatsapi-0.1.5/src/rlstatsapi.egg-info → rlstatsapi-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rlstatsapi
-Version: 0.1.5
+Version: 0.1.6
 Summary: Rocket League Stats API client
 Author: Manuel Cabral
 License-Expression: MIT
@@ -19,6 +19,7 @@ License-File: LICENSE
 Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: black; extra == "dev"
 Dynamic: license-file
 
 <img width="600" alt="rlstatsapi-logo" src="https://github.com/manucabral/RocketLeagueStatsAPI/blob/main/docs/assets/social-preview.png" />

{rlstatsapi-0.1.5 → rlstatsapi-0.1.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "rlstatsapi"
-version = "0.1.5"
+version = "0.1.6"
 description = "Rocket League Stats API client"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -28,7 +28,7 @@ Repository = "https://github.com/manucabral/RocketLeagueStatsAPI"
 rlstatsapi = "rlstatsapi.__main__:main"
 
 [project.optional-dependencies]
-dev = ["pytest>=8", "pytest-asyncio>=0.23"]
+dev = ["pytest>=8", "pytest-asyncio>=0.23", "black"]
 
 [tool.pytest.ini_options]
 asyncio_mode = "auto"

{rlstatsapi-0.1.5 → rlstatsapi-0.1.6}/src/rlstatsapi/__init__.py

@@ -8,7 +8,7 @@ helpers so consumers can import from `rlstatsapi` directly.
 from importlib.metadata import PackageNotFoundError
 from importlib.metadata import version as _pkg_version
 
-from .client import StatsClient
+from .client import ConnectionState, StatsClient
 from .config import (
     DEFAULT_PACKET_SEND_RATE,
     DEFAULT_STATS_API_FILENAME,
@@ -22,7 +22,7 @@ from .config import (
     set_stats_api_port,
 )
 from .events import KNOWN_EVENTS
-from .models import ClientMetrics, EventMessage, MatchStateSnapshot
+from .models import ClientMetrics, EventMessage, MatchStateSnapshot, PlayerSnapshot
 from .state import MatchStateTracker
 from .types import (
     BallHitPayload,
@@ -58,10 +58,12 @@ except PackageNotFoundError:
 __all__ = [
     "__version__",
     "StatsClient",
+    "ConnectionState",
     "StatsAPIConfigStatus",
     "EventMessage",
     "ClientMetrics",
     "MatchStateSnapshot",
+    "PlayerSnapshot",
     "MatchStateTracker",
     "KNOWN_EVENTS",
     "DEFAULT_PACKET_SEND_RATE",

{rlstatsapi-0.1.5 → rlstatsapi-0.1.6}/src/rlstatsapi/__main__.py

@@ -26,6 +26,7 @@ def main(argv: Sequence[str] | None = None) -> int:
 
 
 def _build_parser() -> argparse.ArgumentParser:
+    """Build and return the top-level argument parser with all subcommands."""
     parser = argparse.ArgumentParser(prog="rlstatsapi")
     subparsers = parser.add_subparsers(dest="command", required=True)
 
@@ -87,12 +88,14 @@ def _build_parser() -> argparse.ArgumentParser:
 
 
 def _run_status(args: argparse.Namespace) -> int:
+    """Print the current TAStatsAPI.ini config as JSON."""
     status = get_stats_api_status(args.path)
     print(json.dumps(asdict(status), indent=2))
     return 0
 
 
 def _run_enable(args: argparse.Namespace) -> int:
+    """Enable the Stats API exporter in TAStatsAPI.ini and print the result."""
     status = configure_stats_api(
         enabled=True,
         port=args.port,
@@ -105,6 +108,7 @@ def _run_enable(args: argparse.Namespace) -> int:
 
 
 def _run_disable(args: argparse.Namespace) -> int:
+    """Disable the Stats API exporter in TAStatsAPI.ini and print the result."""
     status = configure_stats_api(
         enabled=False,
         port=args.port,
@@ -117,10 +121,12 @@ def _run_disable(args: argparse.Namespace) -> int:
 
 
 def _run_listen(args: argparse.Namespace) -> int:
+    """Bridge the sync CLI entry point into the async ``_listen`` coroutine."""
     return asyncio.run(_listen(args))
 
 
 async def _listen(args: argparse.Namespace) -> int:
+    """Connect to the local Stats API and stream events to stdout until Ctrl+C."""
     async with StatsClient(
         host=args.host,
         port=args.port,

{rlstatsapi-0.1.5 → rlstatsapi-0.1.6}/src/rlstatsapi/client.py

@@ -8,11 +8,13 @@ from __future__ import annotations
 
 import asyncio
 import contextlib
+import functools
 import inspect
 import json
 import logging
 import random
 from collections import defaultdict
+from enum import Enum
 from typing import Any, AsyncIterator, Awaitable, Callable, Iterable, Literal, overload
 
 from .models import ClientMetrics, EventMessage, MatchStateSnapshot
@@ -43,11 +45,22 @@ from .types import (
 Handler = Callable[[EventMessage], Awaitable[None] | None]
 _AnyCallable = Callable[..., Any]
 _SimpleHandler = Callable[[], Awaitable[None] | None]
-_ErrorHandler = Callable[[str, Exception], Awaitable[None] | None]
+_ErrorHandler = Callable[
+    [EventMessage, Exception, _AnyCallable], Awaitable[None] | None
+]
+
+
+class ConnectionState(Enum):
+    """Granular connection lifecycle state for a StatsClient."""
+
+    DISCONNECTED = "disconnected"
+    CONNECTING = "connecting"
+    CONNECTED = "connected"
+    FAILED = "failed"
 
 
 class StatsClient:
-    """High-level event client for Rocket League Stats API."""
+    """Event client for Rocket League Stats API."""
 
     def __init__(
         self,
@@ -62,7 +75,31 @@ class StatsClient:
         overflow: Literal["block", "drop", "raise"] = "block",
         connect_timeout: float = 5.0,
         drain_on_disconnect: bool = False,
+        handler_timeout: float | None = None,
     ) -> None:
+        """Configure the client.
+
+        Does not connect until ``connect()`` or async context manager entry.
+
+        Args:
+            host: Stats API host address.
+            port: Stats API TCP port.
+            reconnect: Whether to reconnect automatically on connection loss.
+            reconnect_delay: Initial delay in seconds before the first reconnect attempt.
+            max_reconnect_delay: Upper bound for exponential backoff delay.
+            max_reconnect_attempts: Stop reconnecting after this many failures.
+                None means unlimited.
+            include_raw: Attach the original JSON string to each ``EventMessage.raw``.
+            queue_size: Max events buffered in the internal queue.
+            overflow: Queue-full behavior ``"block"`` waits, ``"drop"`` discards,
+                ``"raise"`` kills the connection.
+            connect_timeout: Seconds to wait for TCP handshake before raising.
+            drain_on_disconnect: Clear the queue when the session ends.
+            handler_timeout: Max seconds an async handler may run before being cancelled.
+                Sync handlers are not affected. None disables the timeout.
+        """
+        if reconnect_delay <= 0:
+            raise ValueError("reconnect_delay must be positive")
         self.host = host
         self.port = port
         self.reconnect = reconnect
@@ -73,6 +110,7 @@ class StatsClient:
         self.connect_timeout = connect_timeout
         self.overflow = overflow
         self.drain_on_disconnect = drain_on_disconnect
+        self.handler_timeout = handler_timeout
 
         self._queue: asyncio.Queue[EventMessage] = asyncio.Queue(maxsize=queue_size)
         self._handlers_by_event: dict[str, list[_AnyCallable]] = defaultdict(list)
@@ -86,18 +124,21 @@ class StatsClient:
         self._writer: asyncio.StreamWriter | None = None
         self._reader_task: asyncio.Task[None] | None = None
         self._stopping = False
-        self._connected = False
+        self._connection_state = ConnectionState.DISCONNECTED
         self._permanently_failed = False
         self._last_error: Exception | None = None
         self._metrics = ClientMetrics()
         self._state_tracker = MatchStateTracker()
 
+    @property
+    def connection_state(self) -> ConnectionState:
+        """Return the current connection lifecycle state."""
+        return self._connection_state
+
     @property
     def is_connected(self) -> bool:
-        """
-        Returns True if the client is currently connected to the Stats API.
-        """
-        return self._connected
+        """Return True if the client is currently connected to the Stats API."""
+        return self._connection_state == ConnectionState.CONNECTED
 
     @property
     def metrics(self) -> ClientMetrics:
@@ -120,13 +161,16 @@ class StatsClient:
         return self._permanently_failed
 
     async def __aenter__(self) -> StatsClient:
+        """Connect and return self for use as an async context manager."""
         await self.connect()
         return self
 
     async def __aexit__(self, *_: object) -> None:
+        """Disconnect when leaving the async context manager."""
         await self.disconnect()
 
     async def connect(self) -> None:
+        """Start the background reader task and begin connecting. No-op if already running."""
         if self._reader_task and not self._reader_task.done():
             self._logger.debug("connect() ignored: reader already running")
             return
@@ -137,15 +181,17 @@ class StatsClient:
         self._reader_task = asyncio.create_task(self._run(), name="rlstatsapi-reader")
         self._logger.debug("reader task started")
 
-    async def disconnect(self) -> None:
-        """
-        Disconnects from the Stats API and stops the reader task.
+    async def disconnect(self, timeout: float = 5.0) -> None:
+        """Disconnect from the Stats API and stop the reader task.
+
+        Args:
+            timeout: Seconds to wait for the reader task to finish before giving up.
         """
         self._stopping = True
         self._logger.debug("disconnect requested")
 
         if self._writer is not None:
-            with contextlib.suppress(Exception):
+            with contextlib.suppress(OSError, asyncio.TimeoutError):
                 self._writer.close()
                 await self._writer.wait_closed()
             self._writer = None
@@ -153,8 +199,8 @@ class StatsClient:
 
         if self._reader_task is not None:
             self._reader_task.cancel()
-            with contextlib.suppress(asyncio.CancelledError):
-                await self._reader_task
+            with contextlib.suppress(asyncio.TimeoutError, asyncio.CancelledError):
+                await asyncio.wait_for(self._reader_task, timeout=timeout)
             self._reader_task = None
         if self.drain_on_disconnect:
             self.clear_queue()
@@ -460,8 +506,12 @@ class StatsClient:
         if handler is None:
 
             def decorator(h: _AnyCallable) -> _AnyCallable:
-                self._handlers_by_event[event_name].append(h)
-                return h
+                @functools.wraps(h)
+                def wrapper(*args: Any, **kwargs: Any) -> Any:
+                    return h(*args, **kwargs)
+
+                self._handlers_by_event[event_name].append(wrapper)
+                return wrapper
 
             return decorator
         self._handlers_by_event[event_name].append(handler)
@@ -490,9 +540,11 @@ class StatsClient:
 
     def clear_queue(self) -> None:
         """Drop any queued events that have not been consumed yet."""
-        while not self._queue.empty():
-            with contextlib.suppress(asyncio.QueueEmpty):
+        while True:
+            try:
                 self._queue.get_nowait()
+            except asyncio.QueueEmpty:
+                break
 
     def once(self, event_name: str, handler: _AnyCallable) -> None:
         """Register a handler that runs once and removes itself automatically."""
@@ -682,17 +734,51 @@ class StatsClient:
             if not filters or message.event in filters:
                 yield message
 
+    async def wait_for(
+        self,
+        event_name: str,
+        *,
+        timeout: float | None = None,
+    ) -> EventMessage:
+        """Wait until the next occurrence of ``event_name`` and return the message.
+
+        Args:
+            event_name: The event to wait for (e.g. ``"GoalScored"``).
+            timeout: Seconds before raising ``asyncio.TimeoutError``. None waits forever.
+
+        Returns:
+            The first matching ``EventMessage`` received after this call.
+
+        Raises:
+            asyncio.TimeoutError: If ``timeout`` elapses before the event arrives.
+        """
+        loop = asyncio.get_event_loop()
+        future: asyncio.Future[EventMessage] = loop.create_future()
+
+        def _handler(msg: EventMessage) -> None:
+            if not future.done():
+                self.off(event_name, _handler)
+                future.set_result(msg)
+
+        self._handlers_by_event[event_name].append(_handler)
+        try:
+            return await asyncio.wait_for(future, timeout=timeout)
+        except asyncio.TimeoutError:
+            self.off(event_name, _handler)
+            raise
+
     async def _run(self) -> None:
         """Main loop to manage connection and reading from the Stats API."""
         attempt = 0
         while not self._stopping:
             try:
                 self._logger.debug("connecting to tcp://%s:%d", self.host, self.port)
+                self._connection_state = ConnectionState.CONNECTING
                 self._reader, self._writer = await asyncio.wait_for(
                     asyncio.open_connection(host=self.host, port=self.port),
                     timeout=self.connect_timeout,
                 )
-                self._connected = True
+                self._connection_state = ConnectionState.CONNECTED
                 attempt = 0
                 self._logger.debug("tcp socket connected")
                 await self._fire_simple(self._on_connect_handlers)
@@ -716,6 +802,7 @@ class StatsClient:
                     and attempt > self.max_reconnect_attempts
                 ):
                     self._permanently_failed = True
+                    self._connection_state = ConnectionState.FAILED
                     self._logger.debug(
                         "max reconnect attempts (%d) reached",
                         self.max_reconnect_attempts,
@@ -728,11 +815,11 @@ class StatsClient:
                 self._logger.debug("reconnecting in %.2fs (attempt %d)", delay, attempt)
                 await asyncio.sleep(delay)
             finally:
-                if self._connected:
-                    self._connected = False
+                if self._connection_state == ConnectionState.CONNECTED:
+                    self._connection_state = ConnectionState.DISCONNECTED
                     await self._fire_simple(self._on_disconnect_handlers)
                 if self._writer is not None:
-                    with contextlib.suppress(Exception):
+                    with contextlib.suppress(OSError, asyncio.TimeoutError):
                         self._writer.close()
                         await self._writer.wait_closed()
                     self._writer = None
@@ -749,14 +836,19 @@ class StatsClient:
             chunk = await reader.read(4096)
             if not chunk:
                 raise ConnectionAbortedError("Socket closed by peer")
-            buffer += chunk.decode("utf-8", errors="ignore")
+            decoded_chunk = chunk.decode("utf-8", errors="replace")
+            if "�" in decoded_chunk:
+                self._logger.warning(
+                    "received invalid UTF-8 bytes; replaced with U+FFFD"
+                )
+            buffer += decoded_chunk
 
             while True:
                 lstripped = buffer.lstrip()
                 if not lstripped:
                     buffer = ""
                     break
-                if lstripped is not buffer:
+                if lstripped != buffer:
                     buffer = lstripped
 
                 try:
@@ -796,9 +888,7 @@ class StatsClient:
                 await self._dispatch(message)
 
     async def _dispatch(self, message: EventMessage) -> None:
-        """
-        Dispatches to handlers for `message.event` and global handlers.
-        """
+        """Dispatches to handlers for `message.event` and global handlers."""
         handlers = list(self._handlers_any) + list(
             self._handlers_by_event.get(message.event, [])
         )
@@ -806,25 +896,40 @@ class StatsClient:
             try:
                 result = handler(message)
                 if inspect.isawaitable(result):
-                    await result
+                    if (
+                        self.handler_timeout is not None
+                        and inspect.iscoroutinefunction(handler)
+                    ):
+                        await asyncio.wait_for(result, timeout=self.handler_timeout)
+                    else:
+                        await result
             except Exception as exc:
                 self._metrics.handler_errors += 1
                 if self._error_handlers:
                     for error_handler in list(self._error_handlers):
-                        with contextlib.suppress(Exception):
-                            r = error_handler(message.event, exc)
+                        try:
+                            r = error_handler(message, exc, handler)
                             if inspect.isawaitable(r):
                                 await r
+                        except Exception as err_exc:
+                            self._logger.error(
+                                "error handler itself raised: %s", err_exc
+                            )
                 else:
                     self._logger.error("handler error for %s: %s", message.event, exc)
 
     async def _fire_simple(self, handlers: list[_SimpleHandler]) -> None:
         """Run connection lifecycle callbacks and await async ones when needed."""
         for handler in list(handlers):
-            with contextlib.suppress(Exception):
+            try:
                 result = handler()
                 if inspect.isawaitable(result):
                     await result
+            except Exception as exc:
+                self._logger.error("lifecycle handler error: %s", exc)
+
+
+_MAX_JSON_FIELD_BYTES = 1 << 20  # 1 MiB
 
 
 def _parse_message_obj(
@@ -836,6 +941,8 @@ def _parse_message_obj(
     event = decoded.get("Event")
     data = decoded.get("Data")
     if isinstance(data, str):
+        if len(data) > _MAX_JSON_FIELD_BYTES:
+            return None
         try:
             data = json.loads(data)
         except json.JSONDecodeError:

{rlstatsapi-0.1.5 → rlstatsapi-0.1.6}/src/rlstatsapi/config.py

@@ -7,10 +7,13 @@ prepare the game config before starting Rocket League and then connect with
 
 from __future__ import annotations
 
+import logging
 import os
 from dataclasses import dataclass
 from pathlib import Path
 
+_logger = logging.getLogger("rlstatsapi.config")
+
 DEFAULT_PACKET_SEND_RATE = 30
 DEFAULT_STATS_API_PORT = 49123
 DEFAULT_STATS_API_FILENAME = "TAStatsAPI.ini"
@@ -165,6 +168,7 @@ def configure_stats_api(
 
 
 def _require_config_path(path: str | Path | None) -> Path:
+    """Return the resolved config path or raise ``FileNotFoundError`` if not found."""
     config_path = find_stats_api_config(path)
     if config_path is None:
         raise FileNotFoundError(_WARNING)
@@ -172,6 +176,7 @@ def _require_config_path(path: str | Path | None) -> Path:
 
 
 def _parse_int(value: str | None) -> int | None:
+    """Parse a string to int, returning None on failure or missing input."""
     if value is None:
         return None
     try:
@@ -181,10 +186,14 @@ def _parse_int(value: str | None) -> int | None:
 
 
 def _read_key_values(text: str) -> dict[str, str]:
+    """Parse ``key=value`` pairs from INI-style text, ignoring comments and blank lines."""
     values: dict[str, str] = {}
     for line in text.splitlines():
         stripped = line.strip()
-        if not stripped or stripped.startswith(("#", ";")) or "=" not in stripped:
+        if not stripped or stripped.startswith(("#", ";")):
+            continue
+        if "=" not in stripped:
+            _logger.warning("skipped malformed config line: %r", stripped)
             continue
         key, value = stripped.split("=", 1)
         values[key.strip().casefold()] = value.strip()
@@ -192,7 +201,18 @@ def _read_key_values(text: str) -> dict[str, str]:
 
 
 def _status_for_path(path: Path) -> StatsAPIConfigStatus:
-    text = path.read_text(encoding="utf-8")
+    """Build a ``StatsAPIConfigStatus`` by reading and parsing an existing config file."""
+    try:
+        text = path.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        return StatsAPIConfigStatus(
+            found=False,
+            enabled=False,
+            path=str(path),
+            packet_send_rate=None,
+            port=None,
+            warning=_WARNING,
+        )
     values = _read_key_values(text)
     packet_send_rate = _parse_int(values.get("packetsendrate"))
     port = _parse_int(values.get("port"))
@@ -207,6 +227,7 @@ def _status_for_path(path: Path) -> StatsAPIConfigStatus:
 
 
 def _set_or_append_key(lines: list[str], key: str, value: str) -> list[str]:
+    """Replace an existing ``key=value`` line in-place, or append it if not present."""
     output: list[str] = []
     replaced = False
     for line in lines:
@@ -227,17 +248,18 @@ def _set_or_append_key(lines: list[str], key: str, value: str) -> list[str]:
 
 
 def _write_lines(path: Path, lines: list[str], original_text: str) -> None:
+    """Write lines back to file, preserving the original trailing newline."""
     newline = "\n" if original_text.endswith(("\n", "\r\n")) else ""
     path.write_text("\n".join(lines) + newline, encoding="utf-8")
 
 
 def _validate_packet_send_rate(packet_send_rate: int) -> None:
-    if packet_send_rate < 0 or packet_send_rate > 120:
-        raise ValueError("packet_send_rate must be between 0 and 120")
-    if packet_send_rate == 0:
-        raise ValueError("packet_send_rate must be greater than 0 when enabled")
+    """Raise ``ValueError`` if packet_send_rate is outside the valid range [1, 120]."""
+    if packet_send_rate < 1 or packet_send_rate > 120:
+        raise ValueError("packet_send_rate must be between 1 and 120 when enabled")
 
 
 def _validate_port(port: int) -> None:
+    """Raise ``ValueError`` if port is outside the valid range [1, 65535]."""
     if port < 1 or port > 65535:
         raise ValueError("port must be between 1 and 65535")

{rlstatsapi-0.1.5 → rlstatsapi-0.1.6}/src/rlstatsapi/models.py

@@ -7,6 +7,7 @@ through internal queues and user callbacks.
 from __future__ import annotations
 
 from dataclasses import dataclass, field
+from datetime import datetime
 from typing import Any
 
 from .types import EventName, TypedEventMessage, cast_event_data
@@ -40,6 +41,34 @@ class ClientMetrics:
     reconnect_count: int = 0
     handler_errors: int = 0
     connection_failures: int = 0
+    started_at: datetime = field(default_factory=datetime.now)
+
+    def reset(self) -> None:
+        """Reset all counters and update started_at to now."""
+        self.received_events = 0
+        self.queued_events = 0
+        self.dropped_events = 0
+        self.reconnect_count = 0
+        self.handler_errors = 0
+        self.connection_failures = 0
+        self.started_at = datetime.now()
+
+
+@dataclass(slots=True)
+class PlayerSnapshot:
+    """Per-player state extracted from the latest UpdateState event."""
+
+    name: str
+    shortcut: int
+    team_num: int
+    score: int = 0
+    goals: int = 0
+    assists: int = 0
+    saves: int = 0
+    shots: int = 0
+    boost: int = 0
+    speed: float = 0.0
+    is_demolished: bool = False
 
 
 @dataclass(slots=True)
@@ -58,4 +87,6 @@ class MatchStateSnapshot:
     last_event: str | None = None
     last_scorer: str | None = None
     last_goal_speed: float | None = None
+    players: list[PlayerSnapshot] = field(default_factory=list)
+    target_player: PlayerSnapshot | None = None
     event_counts: dict[str, int] = field(default_factory=dict)

{rlstatsapi-0.1.5 → rlstatsapi-0.1.6}/src/rlstatsapi/state.py

@@ -8,7 +8,7 @@ without forcing users to rebuild the same state cache in every script.
 
 from __future__ import annotations
 
-from .models import EventMessage, MatchStateSnapshot
+from .models import EventMessage, MatchStateSnapshot, PlayerSnapshot
 
 
 class MatchStateTracker:
@@ -58,11 +58,13 @@ class MatchStateTracker:
         snapshot: MatchStateSnapshot,
         message: EventMessage,
     ) -> None:
+        """Extract game-level fields from an UpdateState payload into the snapshot."""
         game = message.data.get("Game", {})
         if not isinstance(game, dict):
             return
 
         self._apply_teams(snapshot, game.get("Teams", []))
+        self._apply_players(snapshot, message.data.get("Players", []), game)
 
         time_seconds = game.get("TimeSeconds")
         if isinstance(time_seconds, int):
@@ -81,6 +83,7 @@ class MatchStateTracker:
             snapshot.winner = winner
 
     def _apply_teams(self, snapshot: MatchStateSnapshot, teams: object) -> None:
+        """Update blue/orange score from the Teams list in an UpdateState payload."""
         if not isinstance(teams, list):
             return
 
@@ -94,11 +97,62 @@ class MatchStateTracker:
             if team_num == 1 and isinstance(score, int):
                 snapshot.orange_score = score
 
+    def _apply_players(
+        self,
+        snapshot: MatchStateSnapshot,
+        players: object,
+        game: dict,
+    ) -> None:
+        """Rebuild the players list and resolve target_player from UpdateState."""
+        if not isinstance(players, list):
+            snapshot.players = []
+            snapshot.target_player = None
+            return
+
+        result: list[PlayerSnapshot] = []
+        for p in players:
+            if not isinstance(p, dict):
+                continue
+            name = p.get("Name")
+            shortcut = p.get("Shortcut")
+            team_num = p.get("TeamNum")
+            if not isinstance(name, str) or not isinstance(shortcut, int):
+                continue
+            result.append(
+                PlayerSnapshot(
+                    name=name,
+                    shortcut=shortcut,
+                    team_num=team_num if isinstance(team_num, int) else 0,
+                    score=p.get("Score") or 0,
+                    goals=p.get("Goals") or 0,
+                    assists=p.get("Assists") or 0,
+                    saves=p.get("Saves") or 0,
+                    shots=p.get("Shots") or 0,
+                    boost=p.get("Boost") or 0,
+                    speed=float(p.get("Speed") or 0.0),
+                    is_demolished=bool(p.get("bDemolished", False)),
+                )
+            )
+        snapshot.players = result
+
+        target_player: PlayerSnapshot | None = None
+        if game.get("bHasTarget"):
+            target = game.get("Target")
+            if isinstance(target, dict):
+                target_shortcut = target.get("Shortcut")
+                if isinstance(target_shortcut, int):
+                    for player in result:
+                        if player.shortcut == target_shortcut:
+                            target_player = player
+                            break
+        snapshot.target_player = target_player
+
     def _apply_goal_scored(
         self,
         snapshot: MatchStateSnapshot,
         message: EventMessage,
     ) -> None:
+        """Update last scorer name and goal speed from a GoalScored payload."""
         scorer = message.data.get("Scorer", {})
         if isinstance(scorer, dict):
             name = scorer.get("Name")

{rlstatsapi-0.1.5 → rlstatsapi-0.1.6/src/rlstatsapi.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rlstatsapi
-Version: 0.1.5
+Version: 0.1.6
 Summary: Rocket League Stats API client
 Author: Manuel Cabral
 License-Expression: MIT
@@ -19,6 +19,7 @@ License-File: LICENSE
 Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: black; extra == "dev"
 Dynamic: license-file
 
 <img width="600" alt="rlstatsapi-logo" src="https://github.com/manucabral/RocketLeagueStatsAPI/blob/main/docs/assets/social-preview.png" />

{rlstatsapi-0.1.5 → rlstatsapi-0.1.6}/src/rlstatsapi.egg-info/SOURCES.txt

@@ -16,4 +16,6 @@ src/rlstatsapi.egg-info/dependency_links.txt
 src/rlstatsapi.egg-info/entry_points.txt
 src/rlstatsapi.egg-info/requires.txt
 src/rlstatsapi.egg-info/top_level.txt
+tests/test_client.py
+tests/test_client_unit.py
 tests/test_config.py

{rlstatsapi-0.1.5 → rlstatsapi-0.1.6}/src/rlstatsapi.egg-info/requires.txt

@@ -2,3 +2,4 @@
 [dev]
 pytest>=8
 pytest-asyncio>=0.23
+black

rlstatsapi-0.1.6/tests/test_client.py

@@ -0,0 +1,49 @@
+"""Real integration test for StatsClient against a live Rocket League exporter."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import socket
+
+import pytest
+
+from rlstatsapi import StatsClient
+
+RL_STATSAPI_HOST = os.getenv("RL_STATSAPI_HOST", "127.0.0.1")
+RL_STATSAPI_PORT = int(os.getenv("RL_STATSAPI_PORT", "49123"))
+
+
+def _tcp_open(host: str, port: int) -> bool:
+    try:
+        with socket.create_connection((host, port), timeout=1.0):
+            return True
+    except OSError:
+        return False
+
+
+@pytest.mark.asyncio
+@pytest.mark.integration
+async def test_client_receives_real_event() -> None:
+    """Connects to a real RL exporter and verifies one event is received."""
+
+    if not _tcp_open(RL_STATSAPI_HOST, RL_STATSAPI_PORT):
+        pytest.skip(
+            f"Rocket League exporter is not reachable at {RL_STATSAPI_HOST}:{RL_STATSAPI_PORT}"
+        )
+
+    client = StatsClient(
+        host=RL_STATSAPI_HOST,
+        port=RL_STATSAPI_PORT,
+        reconnect=False,
+        connect_timeout=2.0,
+    )
+
+    await client.connect()
+    try:
+        message = await asyncio.wait_for(client.events().__anext__(), timeout=3.0)
+        assert isinstance(message.event, str)
+        assert isinstance(message.data, dict)
+        assert message.event
+    finally:
+        await client.disconnect()

rlstatsapi-0.1.6/tests/test_client_unit.py

@@ -0,0 +1,340 @@
+"""Unit coverage for client parsing, filtering, and convenience helpers."""
+
+# pylint: disable=protected-access
+
+from __future__ import annotations
+
+import asyncio
+from datetime import datetime
+from typing import Any, Callable
+
+import pytest
+
+from rlstatsapi.client import ConnectionState, StatsClient, _parse_message_obj
+from rlstatsapi.models import EventMessage, PlayerSnapshot
+
+
+def test_parse_message_decodes_string_data_payload() -> None:
+    message = _parse_message_obj(
+        {
+            "Event": "GoalScored",
+            "Data": '{"Scorer":{"Name":"PlayerA","Shortcut":1,"TeamNum":0}}',
+        },
+        raw="{}",
+        include_raw=True,
+    )
+
+    assert message is not None
+    assert message.event == "GoalScored"
+    assert message.data["Scorer"]["Name"] == "PlayerA"
+    assert message.raw == "{}"
+
+
+def test_event_message_as_type_exposes_typed_data() -> None:
+    message = EventMessage(
+        event="GoalScored",
+        data={"Scorer": {"Name": "PlayerA", "Shortcut": 1, "TeamNum": 0}},
+    )
+
+    typed_message = message.as_type("GoalScored")
+
+    assert typed_message.event == "GoalScored"
+    assert typed_message.data["Scorer"]["Name"] == "PlayerA"
+
+
+@pytest.mark.asyncio
+async def test_events_filter_only_yields_requested_names() -> None:
+    client = StatsClient(reconnect=False)
+    await client._queue.put(EventMessage(event="UpdateState", data={}))
+    await client._queue.put(EventMessage(event="GoalScored", data={}))
+
+    iterator = client.events("GoalScored")
+    message = await asyncio.wait_for(iterator.__anext__(), timeout=1.0)
+
+    assert message.event == "GoalScored"
+
+
+def test_on_many_registers_same_handler_for_multiple_events() -> None:
+    client = StatsClient(reconnect=False)
+
+    def handler(_message: EventMessage) -> None:
+        return None
+
+    client.on_many(["GoalScored", "MatchEnded"], handler)
+
+    assert handler in client._handlers_by_event["GoalScored"]
+    assert handler in client._handlers_by_event["MatchEnded"]
+
+
+def test_off_removes_specific_handler() -> None:
+    client = StatsClient(reconnect=False)
+
+    def handler(_: EventMessage) -> None:
+        return None
+
+    client.on("GoalScored", handler)
+    client.off("GoalScored", handler)
+
+    assert handler not in client._handlers_by_event["GoalScored"]
+
+
+def test_off_any_removes_global_handler() -> None:
+    client = StatsClient(reconnect=False)
+
+    def handler(_: EventMessage) -> None:
+        return None
+
+    client.on_any(handler)
+    client.off_any(handler)
+
+    assert handler not in client._handlers_any
+
+
+@pytest.mark.asyncio
+async def test_once_handler_fires_once_and_removes_itself() -> None:
+    client = StatsClient(reconnect=False)
+    calls: list[str] = []
+
+    def handler(msg: EventMessage) -> None:
+        calls.append(msg.event)
+
+    client.once("GoalScored", handler)
+    msg = EventMessage(event="GoalScored", data={})
+    await client._dispatch(msg)
+    await client._dispatch(msg)
+
+    assert len(calls) == 1
+
+
+def test_clear_queue_empties_all_items() -> None:
+    client = StatsClient(reconnect=False)
+    client._queue.put_nowait(EventMessage(event="A", data={}))
+    client._queue.put_nowait(EventMessage(event="B", data={}))
+    client.clear_queue()
+
+    assert client._queue.empty()
+
+
+@pytest.mark.asyncio
+async def test_events_no_filter_yields_all() -> None:
+    client = StatsClient(reconnect=False)
+    await client._queue.put(EventMessage(event="UpdateState", data={}))
+    await client._queue.put(EventMessage(event="GoalScored", data={}))
+
+    iterator = client.events()
+    msg1 = await asyncio.wait_for(iterator.__anext__(), timeout=1.0)
+    msg2 = await asyncio.wait_for(iterator.__anext__(), timeout=1.0)
+
+    assert {msg1.event, msg2.event} == {"UpdateState", "GoalScored"}
+
+
+@pytest.mark.asyncio
+async def test_overflow_drop_increments_dropped_metric() -> None:
+    client = StatsClient(reconnect=False, queue_size=1, overflow="drop")
+    client._queue.put_nowait(EventMessage(event="A", data={}))
+
+    try:
+        client._queue.put_nowait(EventMessage(event="B", data={}))
+        client._metrics.queued_events += 1
+    except asyncio.QueueFull:
+        client._metrics.dropped_events += 1
+
+    assert client._metrics.dropped_events == 1
+
+
+@pytest.mark.asyncio
+async def test_on_handler_error_called_on_handler_exception() -> None:
+    client = StatsClient(reconnect=False)
+    errors: list[tuple[EventMessage, Exception, Callable[..., Any]]] = []
+
+    def error_handler(
+        msg: EventMessage, exc: Exception, handler: Callable[..., Any]
+    ) -> None:
+        errors.append((msg, exc, handler))
+
+    client.on_handler_error(error_handler)
+
+    def bad_handler(_: EventMessage) -> None:
+        raise RuntimeError("boom")
+
+    client.on("GoalScored", bad_handler)
+    msg = EventMessage(event="GoalScored", data={})
+    await client._dispatch(msg)
+
+    assert len(errors) == 1
+    assert errors[0][0] is msg
+    assert isinstance(errors[0][1], RuntimeError)
+    assert errors[0][2] is bad_handler
+
+
+def test_reconnect_delay_zero_raises() -> None:
+    with pytest.raises(ValueError, match="reconnect_delay"):
+        StatsClient(reconnect_delay=0)
+
+
+def test_state_tracker_updates_from_update_state() -> None:
+    client = StatsClient(reconnect=False)
+    client._state_tracker.update(
+        EventMessage(
+            event="UpdateState",
+            data={
+                "MatchGuid": "abc",
+                "Game": {
+                    "TimeSeconds": 120,
+                    "bOvertime": False,
+                    "Arena": "Stadium_P",
+                    "Teams": [
+                        {"TeamNum": 0, "Score": 2},
+                        {"TeamNum": 1, "Score": 1},
+                    ],
+                },
+            },
+        )
+    )
+
+    assert client.state.match_guid == "abc"
+    assert client.state.blue_score == 2
+    assert client.state.orange_score == 1
+    assert client.state.time_seconds == 120
+    assert client.state.arena == "Stadium_P"
+
+
+def test_connection_state_starts_disconnected() -> None:
+    client = StatsClient(reconnect=False)
+    assert client.connection_state == ConnectionState.DISCONNECTED
+    assert not client.is_connected
+
+
+def test_metrics_reset_clears_counters() -> None:
+    client = StatsClient(reconnect=False)
+    client._metrics.received_events = 10
+    client._metrics.handler_errors = 3
+    before = client.metrics.started_at
+    client.metrics.reset()
+    assert client.metrics.received_events == 0
+    assert client.metrics.handler_errors == 0
+    assert client.metrics.started_at >= before
+
+
+def test_metrics_started_at_is_set() -> None:
+    client = StatsClient(reconnect=False)
+    assert isinstance(client.metrics.started_at, datetime)
+
+
+@pytest.mark.asyncio
+async def test_wait_for_resolves_on_matching_event() -> None:
+    client = StatsClient(reconnect=False)
+    msg = EventMessage(event="GoalScored", data={"GoalSpeed": 99.0})
+
+    async def dispatch_later() -> None:
+        await asyncio.sleep(0)
+        await client._dispatch(msg)
+
+    asyncio.create_task(dispatch_later())
+    result = await asyncio.wait_for(client.wait_for("GoalScored"), timeout=1.0)
+    assert result is msg
+
+
+@pytest.mark.asyncio
+async def test_wait_for_raises_timeout_when_event_never_arrives() -> None:
+    client = StatsClient(reconnect=False)
+    with pytest.raises(asyncio.TimeoutError):
+        await client.wait_for("GoalScored", timeout=0.05)
+
+
+@pytest.mark.asyncio
+async def test_wait_for_cleans_up_handler_on_timeout() -> None:
+    client = StatsClient(reconnect=False)
+    with pytest.raises(asyncio.TimeoutError):
+        await client.wait_for("GoalScored", timeout=0.05)
+    assert len(client._handlers_by_event["GoalScored"]) == 0
+
+
+@pytest.mark.asyncio
+async def test_handler_timeout_cancels_slow_async_handler() -> None:
+    client = StatsClient(reconnect=False, handler_timeout=0.05)
+    finished = False
+
+    async def slow_handler(_: EventMessage) -> None:
+        nonlocal finished
+        await asyncio.sleep(10)
+        finished = True
+
+    client.on("GoalScored", slow_handler)
+    await client._dispatch(EventMessage(event="GoalScored", data={}))
+    assert not finished
+    assert client.metrics.handler_errors == 1
+
+
+def test_state_tracker_populates_players() -> None:
+    client = StatsClient(reconnect=False)
+    client._state_tracker.update(
+        EventMessage(
+            event="UpdateState",
+            data={
+                "Players": [
+                    {
+                        "Name": "Alice",
+                        "Shortcut": 1,
+                        "TeamNum": 0,
+                        "Score": 5,
+                        "Boost": 80,
+                    },
+                    {
+                        "Name": "Bob",
+                        "Shortcut": 2,
+                        "TeamNum": 1,
+                        "Score": 3,
+                        "Boost": 20,
+                    },
+                ],
+                "Game": {},
+            },
+        )
+    )
+
+    players = client.state.players
+    assert len(players) == 2
+    alice = next(p for p in players if p.name == "Alice")
+    assert isinstance(alice, PlayerSnapshot)
+    assert alice.team_num == 0
+    assert alice.score == 5
+    assert alice.boost == 80
+
+
+def test_state_tracker_resolves_target_player() -> None:
+    client = StatsClient(reconnect=False)
+    client._state_tracker.update(
+        EventMessage(
+            event="UpdateState",
+            data={
+                "Players": [
+                    {"Name": "Alice", "Shortcut": 1, "TeamNum": 0},
+                    {"Name": "Bob", "Shortcut": 2, "TeamNum": 1},
+                ],
+                "Game": {
+                    "bHasTarget": True,
+                    "Target": {"Name": "Bob", "Shortcut": 2, "TeamNum": 1},
+                },
+            },
+        )
+    )
+
+    assert client.state.target_player is not None
+    assert client.state.target_player.name == "Bob"
+    assert client.state.target_player.shortcut == 2
+
+
+def test_state_tracker_no_target_when_flag_false() -> None:
+    client = StatsClient(reconnect=False)
+    client._state_tracker.update(
+        EventMessage(
+            event="UpdateState",
+            data={
+                "Players": [{"Name": "Alice", "Shortcut": 1, "TeamNum": 0}],
+                "Game": {"bHasTarget": False},
+            },
+        )
+    )
+
+    assert client.state.target_player is None

{rlstatsapi-0.1.5 → rlstatsapi-0.1.6}/tests/test_config.py

@@ -1,4 +1,4 @@
-"""Tests for DefaultStatsAPI.ini helpers."""
+"""Tests for TAStatsAPI.ini helpers."""
 
 from __future__ import annotations
 
@@ -21,13 +21,13 @@ def _write_config(path: Path, text: str) -> None:
 
 
 def test_find_stats_api_config_explicit_path(tmp_path: Path) -> None:
-    config_path = tmp_path / "DefaultStatsAPI.ini"
+    config_path = tmp_path / "TAStatsAPI.ini"
     _write_config(config_path, "PacketSendRate=30\nPort=49123\n")
     assert find_stats_api_config(config_path) == config_path.resolve()
 
 
 def test_get_stats_api_status_reads_values(tmp_path: Path) -> None:
-    config_path = tmp_path / "DefaultStatsAPI.ini"
+    config_path = tmp_path / "TAStatsAPI.ini"
     _write_config(config_path, "PacketSendRate=30\nPort=5000\n")
 
     status = get_stats_api_status(config_path)
@@ -39,7 +39,7 @@ def test_get_stats_api_status_reads_values(tmp_path: Path) -> None:
 
 
 def test_get_stats_api_status_missing_keys(tmp_path: Path) -> None:
-    config_path = tmp_path / "DefaultStatsAPI.ini"
+    config_path = tmp_path / "TAStatsAPI.ini"
     _write_config(config_path, "[TAGame.MatchStatsExporter_TA]\n")
 
     status = get_stats_api_status(config_path)
@@ -51,7 +51,7 @@ def test_get_stats_api_status_missing_keys(tmp_path: Path) -> None:
 
 
 def test_set_stats_api_enabled_true_writes_positive_rate(tmp_path: Path) -> None:
-    config_path = tmp_path / "DefaultStatsAPI.ini"
+    config_path = tmp_path / "TAStatsAPI.ini"
     _write_config(config_path, "Port=49123\nPacketSendRate=0\n")
 
     status = set_stats_api_enabled(True, packet_send_rate=45, path=config_path)
@@ -62,7 +62,7 @@ def test_set_stats_api_enabled_true_writes_positive_rate(tmp_path: Path) -> None
 
 
 def test_set_stats_api_enabled_false_writes_zero(tmp_path: Path) -> None:
-    config_path = tmp_path / "DefaultStatsAPI.ini"
+    config_path = tmp_path / "TAStatsAPI.ini"
     _write_config(config_path, "PacketSendRate=30\nPort=49123\n")
 
     status = set_stats_api_enabled(False, path=config_path)
@@ -73,7 +73,7 @@ def test_set_stats_api_enabled_false_writes_zero(tmp_path: Path) -> None:
 
 
 def test_set_stats_api_port_preserves_other_content(tmp_path: Path) -> None:
-    config_path = tmp_path / "DefaultStatsAPI.ini"
+    config_path = tmp_path / "TAStatsAPI.ini"
     original = (
         "; comment\n"
         "[TAGame.MatchStatsExporter_TA]\n"
@@ -92,7 +92,7 @@ def test_set_stats_api_port_preserves_other_content(tmp_path: Path) -> None:
 
 
 def test_configure_stats_api_writes_both_keys(tmp_path: Path) -> None:
-    config_path = tmp_path / "DefaultStatsAPI.ini"
+    config_path = tmp_path / "TAStatsAPI.ini"
     _write_config(config_path, "PacketSendRate=0\n")
 
     status = configure_stats_api(
@@ -108,7 +108,7 @@ def test_configure_stats_api_writes_both_keys(tmp_path: Path) -> None:
 
 
 def test_invalid_packet_send_rate_raises(tmp_path: Path) -> None:
-    config_path = tmp_path / "DefaultStatsAPI.ini"
+    config_path = tmp_path / "TAStatsAPI.ini"
     _write_config(config_path, "PacketSendRate=0\nPort=49123\n")
 
     with pytest.raises(ValueError, match="packet_send_rate"):
@@ -116,7 +116,7 @@ def test_invalid_packet_send_rate_raises(tmp_path: Path) -> None:
 
 
 def test_invalid_port_raises(tmp_path: Path) -> None:
-    config_path = tmp_path / "DefaultStatsAPI.ini"
+    config_path = tmp_path / "TAStatsAPI.ini"
     _write_config(config_path, "PacketSendRate=30\nPort=49123\n")
 
     with pytest.raises(ValueError, match="port"):