rlstatsapi 0.1.3__tar.gz → 0.1.6__tar.gz

{rlstatsapi-0.1.3 → rlstatsapi-0.1.6}/LICENSE

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

rlstatsapi-0.1.6/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: rlstatsapi
+Version: 0.1.6
+Summary: Rocket League Stats API client
+Author: Manuel Cabral
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/manucabral/RocketLeagueStatsAPI
+Project-URL: Repository, https://github.com/manucabral/RocketLeagueStatsAPI
+Project-URL: Bug Tracker, https://github.com/manucabral/RocketLeagueStatsAPI/issues
+Keywords: rocket-league,stats,socket,asyncio
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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
+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" />
+
+# Rocket League Stats API
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) [![PyPI version](https://img.shields.io/pypi/v/rlstatsapi.svg)](https://pypi.org/project/rlstatsapi/) [![Pylint](https://github.com/manucabral/RocketLeagueStatsAPI/actions/workflows/pylint.yml/badge.svg)](https://github.com/manucabral/RocketLeagueStatsAPI/actions/workflows/pylint.yml)
+![Downloads](https://img.shields.io/pypi/dm/rlstatsapi)
+
+`rlstatsapi` is a small Python client for reading live Rocket League Stats API events over a local TCP socket.
+
+- Full docs: [manucabral.github.io/RocketLeagueStatsAPI](https://manucabral.github.io/RocketLeagueStatsAPI/)
+- Release history: [CHANGELOG.md](CHANGELOG.md)
+
+## Install
+
+From [PyPI](https://pypi.org/project/rlstatsapi/):
+
+```bash
+pip install rlstatsapi
+```
+
+From GitHub:
+
+```bash
+pip install git+https://github.com/manucabral/RocketLeagueStatsAPI.git
+```
+
+## Rocket League setup
+
+Automatic setup from Python:
+
+```python
+from rlstatsapi import configure_stats_api
+
+configure_stats_api(enabled=True, port=49123, packet_send_rate=30)
+```
+
+Manual setup:
+
+`Documents\My Games\Rocket League\TAGame\Config\TAStatsAPI.ini`
+
+```ini
+[TAGame.MatchStatsExporter_TA]
+Port=49123
+PacketSendRate=30
+```
+
+In both cases, restart Rocket League after changing the config file.
+
+Config discovery is currently Windows-first and targets common user config locations.
+
+## Quick start
+
+```python
+import asyncio
+from rlstatsapi import StatsClient
+
+
+async def main() -> None:
+    async with StatsClient() as client:
+        client.on_any(lambda msg: print(msg.event, msg.data))
+        await asyncio.Event().wait()
+
+
+asyncio.run(main())
+```
+
+## Demos
+
+### All events
+
+![All events demo](docs/videos/allevents.gif)
+
+### UI
+
+![UI demo](docs/videos/ui.gif)
+
+## CLI
+
+```bash
+rlstatsapi status
+rlstatsapi enable --port 49123 --rate 30
+rlstatsapi listen --event GoalScored
+```
+
+You can also listen to multiple events:
+
+```bash
+rlstatsapi listen --event GoalScored --event MatchEnded --event MatchCreated
+```
+
+## Typing
+
+For the best editor experience, use `cast_event_data(...)` or `msg.as_type(...)`.
+
+```python
+from rlstatsapi.models import EventMessage
+from rlstatsapi.types import GoalScoredPayload, cast_event_data
+
+
+def on_goal(msg: EventMessage) -> None:
+    data: GoalScoredPayload = cast_event_data("GoalScored", msg.data)
+    print(data.get("Scorer", {}).get("Name"))
+```
+
+## More
+
+- Full docs: [manucabral.github.io/RocketLeagueStatsAPI](https://manucabral.github.io/RocketLeagueStatsAPI/)
+- Examples: [examples/](examples)
+- Release history: [CHANGELOG.md](CHANGELOG.md)
+
+## Notes
+
+- In current Rocket League builds this endpoint behaves like a TCP JSON stream in practice.
+- Some fields, such as `MatchGuid`, are only present in online/LAN contexts.
+
+## Disclaimer
+
+This project is an independent, community-made library and is **not affiliated with, endorsed by, or sponsored by Psyonix or Epic Games**.
+
+Rocket League and related trademarks are the property of their respective owners.  
+Use this library at your own risk and in compliance with Rocket League’s terms and policies.
+
+## Contributors
+
+<a href="https://github.com/manucabral/RocketLeagueStatsAPI/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=manucabral/RocketLeagueStatsAPI" alt="Contributors" />
+</a>

rlstatsapi-0.1.6/README.md

@@ -0,0 +1,126 @@
+<img width="600" alt="rlstatsapi-logo" src="https://github.com/manucabral/RocketLeagueStatsAPI/blob/main/docs/assets/social-preview.png" />
+
+# Rocket League Stats API
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) [![PyPI version](https://img.shields.io/pypi/v/rlstatsapi.svg)](https://pypi.org/project/rlstatsapi/) [![Pylint](https://github.com/manucabral/RocketLeagueStatsAPI/actions/workflows/pylint.yml/badge.svg)](https://github.com/manucabral/RocketLeagueStatsAPI/actions/workflows/pylint.yml)
+![Downloads](https://img.shields.io/pypi/dm/rlstatsapi)
+
+`rlstatsapi` is a small Python client for reading live Rocket League Stats API events over a local TCP socket.
+
+- Full docs: [manucabral.github.io/RocketLeagueStatsAPI](https://manucabral.github.io/RocketLeagueStatsAPI/)
+- Release history: [CHANGELOG.md](CHANGELOG.md)
+
+## Install
+
+From [PyPI](https://pypi.org/project/rlstatsapi/):
+
+```bash
+pip install rlstatsapi
+```
+
+From GitHub:
+
+```bash
+pip install git+https://github.com/manucabral/RocketLeagueStatsAPI.git
+```
+
+## Rocket League setup
+
+Automatic setup from Python:
+
+```python
+from rlstatsapi import configure_stats_api
+
+configure_stats_api(enabled=True, port=49123, packet_send_rate=30)
+```
+
+Manual setup:
+
+`Documents\My Games\Rocket League\TAGame\Config\TAStatsAPI.ini`
+
+```ini
+[TAGame.MatchStatsExporter_TA]
+Port=49123
+PacketSendRate=30
+```
+
+In both cases, restart Rocket League after changing the config file.
+
+Config discovery is currently Windows-first and targets common user config locations.
+
+## Quick start
+
+```python
+import asyncio
+from rlstatsapi import StatsClient
+
+
+async def main() -> None:
+    async with StatsClient() as client:
+        client.on_any(lambda msg: print(msg.event, msg.data))
+        await asyncio.Event().wait()
+
+
+asyncio.run(main())
+```
+
+## Demos
+
+### All events
+
+![All events demo](docs/videos/allevents.gif)
+
+### UI
+
+![UI demo](docs/videos/ui.gif)
+
+## CLI
+
+```bash
+rlstatsapi status
+rlstatsapi enable --port 49123 --rate 30
+rlstatsapi listen --event GoalScored
+```
+
+You can also listen to multiple events:
+
+```bash
+rlstatsapi listen --event GoalScored --event MatchEnded --event MatchCreated
+```
+
+## Typing
+
+For the best editor experience, use `cast_event_data(...)` or `msg.as_type(...)`.
+
+```python
+from rlstatsapi.models import EventMessage
+from rlstatsapi.types import GoalScoredPayload, cast_event_data
+
+
+def on_goal(msg: EventMessage) -> None:
+    data: GoalScoredPayload = cast_event_data("GoalScored", msg.data)
+    print(data.get("Scorer", {}).get("Name"))
+```
+
+## More
+
+- Full docs: [manucabral.github.io/RocketLeagueStatsAPI](https://manucabral.github.io/RocketLeagueStatsAPI/)
+- Examples: [examples/](examples)
+- Release history: [CHANGELOG.md](CHANGELOG.md)
+
+## Notes
+
+- In current Rocket League builds this endpoint behaves like a TCP JSON stream in practice.
+- Some fields, such as `MatchGuid`, are only present in online/LAN contexts.
+
+## Disclaimer
+
+This project is an independent, community-made library and is **not affiliated with, endorsed by, or sponsored by Psyonix or Epic Games**.
+
+Rocket League and related trademarks are the property of their respective owners.  
+Use this library at your own risk and in compliance with Rocket League’s terms and policies.
+
+## Contributors
+
+<a href="https://github.com/manucabral/RocketLeagueStatsAPI/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=manucabral/RocketLeagueStatsAPI" alt="Contributors" />
+</a>

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

@@ -1,42 +1,47 @@
-[build-system]
-requires = ["setuptools>=69", "wheel"]
-build-backend = "setuptools.build_meta"
-
-[project]
-name = "rlstatsapi"
-version = "0.1.3"
-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"
-Repository = "https://github.com/manucabral/RocketLeagueStatsAPI"
-"Bug Tracker" = "https://github.com/manucabral/RocketLeagueStatsAPI/issues"
-
-[project.optional-dependencies]
-dev = ["pytest>=8", "pytest-asyncio>=0.23"]
-
-[tool.pytest.ini_options]
-asyncio_mode = "auto"
-testpaths = ["tests"]
-
-[tool.setuptools]
-package-dir = {"" = "src"}
-
-[tool.setuptools.packages.find]
-where = ["src"]
-
-[tool.setuptools.package-data]
-rlstatsapi = ["py.typed"]
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "rlstatsapi"
+version = "0.1.6"
+description = "Rocket League Stats API client"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "Manuel Cabral" }]
+keywords = ["rocket-league", "stats", "socket", "asyncio"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Operating System :: OS Independent",
+  "Topic :: Games/Entertainment",
+  "Topic :: Software Development :: Libraries",
+]
+
+[project.urls]
+Homepage = "https://github.com/manucabral/RocketLeagueStatsAPI"
+Repository = "https://github.com/manucabral/RocketLeagueStatsAPI"
+"Bug Tracker" = "https://github.com/manucabral/RocketLeagueStatsAPI/issues"
+
+[project.scripts]
+rlstatsapi = "rlstatsapi.__main__:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-asyncio>=0.23", "black"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+markers = [
+  "integration: requires a live Rocket League exporter to be running",
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+rlstatsapi = ["py.typed"]

{rlstatsapi-0.1.3 → rlstatsapi-0.1.6}/setup.cfg

@@ -1,4 +1,4 @@
-[egg_info]
-tag_build = 
-tag_date = 0
-
+[egg_info]
+tag_build = 
+tag_date = 0
+

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

@@ -1,11 +1,29 @@
-"""rlstatsapi public API."""
+"""
+Public package surface for rlstatsapi.
+
+Re-exports the client, envelope model, known event constants, and typed payload
+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,
+    DEFAULT_STATS_API_PORT,
+    StatsAPIConfigStatus,
+    candidate_stats_api_paths,
+    configure_stats_api,
+    find_stats_api_config,
+    get_stats_api_status,
+    set_stats_api_enabled,
+    set_stats_api_port,
+)
 from .events import KNOWN_EVENTS
-from .models import EventMessage
+from .models import ClientMetrics, EventMessage, MatchStateSnapshot, PlayerSnapshot
+from .state import MatchStateTracker
 from .types import (
     BallHitPayload,
     ClockUpdatedSecondsPayload,
@@ -40,8 +58,23 @@ except PackageNotFoundError:
 __all__ = [
     "__version__",
     "StatsClient",
+    "ConnectionState",
+    "StatsAPIConfigStatus",
     "EventMessage",
+    "ClientMetrics",
+    "MatchStateSnapshot",
+    "PlayerSnapshot",
+    "MatchStateTracker",
     "KNOWN_EVENTS",
+    "DEFAULT_PACKET_SEND_RATE",
+    "DEFAULT_STATS_API_FILENAME",
+    "DEFAULT_STATS_API_PORT",
+    "candidate_stats_api_paths",
+    "find_stats_api_config",
+    "get_stats_api_status",
+    "set_stats_api_enabled",
+    "set_stats_api_port",
+    "configure_stats_api",
     "EventName",
     "TypedEventMessage",
     "KnownEventMessage",

rlstatsapi-0.1.6/src/rlstatsapi/__main__.py

@@ -0,0 +1,148 @@
+"""Command-line entrypoint for common rlstatsapi setup and debugging tasks."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+from dataclasses import asdict
+from pathlib import Path
+from typing import Sequence
+
+from .client import StatsClient
+from .config import (
+    DEFAULT_PACKET_SEND_RATE,
+    DEFAULT_STATS_API_PORT,
+    configure_stats_api,
+    get_stats_api_status,
+)
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Parse CLI args and dispatch the requested command."""
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+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)
+
+    status_parser = subparsers.add_parser(
+        "status",
+        help="Show the current TAStatsAPI.ini status.",
+    )
+    status_parser.add_argument(
+        "--path", type=Path, help="Explicit TAStatsAPI.ini path."
+    )
+    status_parser.set_defaults(func=_run_status)
+
+    enable_parser = subparsers.add_parser(
+        "enable",
+        help="Enable the Rocket League Stats API in TAStatsAPI.ini.",
+    )
+    enable_parser.add_argument(
+        "--path", type=Path, help="Explicit TAStatsAPI.ini path."
+    )
+    enable_parser.add_argument("--port", type=int, default=DEFAULT_STATS_API_PORT)
+    enable_parser.add_argument(
+        "--rate",
+        type=int,
+        default=DEFAULT_PACKET_SEND_RATE,
+        help="PacketSendRate to write when enabling the exporter.",
+    )
+    enable_parser.set_defaults(func=_run_enable)
+
+    disable_parser = subparsers.add_parser(
+        "disable",
+        help="Disable the Rocket League Stats API in TAStatsAPI.ini.",
+    )
+    disable_parser.add_argument(
+        "--path", type=Path, help="Explicit TAStatsAPI.ini path."
+    )
+    disable_parser.add_argument("--port", type=int, default=DEFAULT_STATS_API_PORT)
+    disable_parser.set_defaults(func=_run_disable)
+
+    listen_parser = subparsers.add_parser(
+        "listen",
+        help="Connect to the local exporter and print live events.",
+    )
+    listen_parser.add_argument("--host", default="127.0.0.1")
+    listen_parser.add_argument("--port", type=int, default=DEFAULT_STATS_API_PORT)
+    listen_parser.add_argument(
+        "--event",
+        action="append",
+        default=[],
+        help="Filter to one or more event names. Repeat the flag to add more.",
+    )
+    listen_parser.add_argument(
+        "--raw",
+        action="store_true",
+        help="Include the raw transport JSON when available.",
+    )
+    listen_parser.set_defaults(func=_run_listen)
+
+    return parser
+
+
+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,
+        packet_send_rate=args.rate,
+        path=args.path,
+    )
+    print(json.dumps(asdict(status), indent=2))
+    print("Restart Rocket League after changing the config file.")
+    return 0
+
+
+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,
+        packet_send_rate=DEFAULT_PACKET_SEND_RATE,
+        path=args.path,
+    )
+    print(json.dumps(asdict(status), indent=2))
+    print("Restart Rocket League after changing the config file.")
+    return 0
+
+
+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,
+        include_raw=args.raw,
+    ) as client:
+        print("Listening for Rocket League events. Press Ctrl+C to stop.")
+        async for message in client.events(*args.event):
+            payload = {
+                "event": message.event,
+                "data": message.data,
+            }
+            if args.raw:
+                payload["raw"] = message.raw
+            print(json.dumps(payload, indent=2, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())