python-mister-fpga 0.1.2__tar.gz → 0.2.0__tar.gz

{python_mister_fpga-0.1.2 → python_mister_fpga-0.2.0}/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.2.0
+- Add `MisterRAWeb` — async client for the [RetroAchievements.org Web API](https://api.docs.retroachievements.org/) to pull cloud player stats (points, rank, recently-played games, latest unlocked achievement) without SSH.
+- New dataclasses `MisterRAWebStats`, `RAGameProgress`, `RAAchievement` for aggregated cloud-stats snapshots.
+- New exception `MisterRAWebError` raised on network, HTTP, or API-level failures (including bad credentials).
+
 ## 0.1.2
 - Add online documentation (MkDocs Material) at https://hudsonbrendon.github.io/python-mister-fpga/ and enrich public-API docstrings.
 

{python_mister_fpga-0.1.2 → python_mister_fpga-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-mister-fpga
-Version: 0.1.2
+Version: 0.2.0
 Summary: Async Python client for the MiSTer FPGA mrext Remote API (REST + WebSocket) and SSH telemetry
 Project-URL: Homepage, https://github.com/hudsonbrendon/python-mister-fpga
 Project-URL: Documentation, https://hudsonbrendon.github.io/python-mister-fpga/
@@ -23,6 +23,7 @@ Provides-Extra: docs
 Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
 Requires-Dist: mkdocstrings[python]>=0.25; extra == 'docs'
 Provides-Extra: test
+Requires-Dist: aiohttp<3.10; extra == 'test'
 Requires-Dist: aioresponses>=0.7; extra == 'test'
 Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
 Requires-Dist: pytest>=8; extra == 'test'
@@ -107,6 +108,74 @@ async def main():
 asyncio.run(main())
 ```
 
+## RetroAchievements cloud stats
+
+`MisterRAWeb` queries the public [RetroAchievements.org Web API](https://api.docs.retroachievements.org/) to pull a player's points, rank, recently-played games, and latest unlocked achievement — no SSH required.  You need a **Web API key** from [retroachievements.org/settings](https://retroachievements.org/settings).
+
+```python
+import asyncio
+from mister_fpga import MisterRAWeb
+
+async def main():
+    web = MisterRAWeb("myuser", "my_api_key")
+    stats = await web.async_fetch_stats()
+    print(stats.hardcore_points, stats.rank, stats.current_game)
+    await web.async_close()
+
+asyncio.run(main())
+```
+
+### `MisterRAWeb(username, api_key, *, session=None, timeout=15)`
+
+Async HTTPS client for the RA Web API.  When `session` is `None` the client creates its own `aiohttp.ClientSession`; call `await web.async_close()` to release it.  Pass a shared session to manage its lifetime yourself.
+
+| Method | Description |
+|---|---|
+| `await async_fetch_stats() -> MisterRAWebStats` | Fire all three API calls concurrently and return an aggregated stats snapshot. |
+| `await async_validate()` | Lightweight credential check — raises `MisterRAWebError` if the username or API key is wrong. |
+| `await async_get_badge_image(url) -> bytes` | Fetch a badge or icon image by absolute URL (e.g. `stats.last_achievement.badge_url`). |
+| `await async_close()` | Close the session if this client created it. |
+
+### Dataclasses
+
+**`MisterRAWebStats`** — aggregated snapshot returned by `async_fetch_stats()`:
+
+| Field | Type | Description |
+|---|---|---|
+| `hardcore_points` | `int` | Total hardcore score. |
+| `softcore_points` | `int` | Total softcore score. |
+| `rank` | `int \| None` | Global hardcore rank (None if unranked). |
+| `total_ranked` | `int \| None` | Total number of ranked players. |
+| `current_game` | `RAGameProgress \| None` | Most recently played game (first entry in the recent-games list). |
+| `recent_games` | `list[RAGameProgress]` | Up to 10 recently played games, most-recent first. |
+| `last_achievement` | `RAAchievement \| None` | Most recently unlocked achievement (within the last 7 days). |
+
+**`RAGameProgress`** — per-game achievement progress:
+
+| Field | Type | Description |
+|---|---|---|
+| `game_id` | `int` | RA game ID. |
+| `title` | `str` | Game title. |
+| `console` | `str` | Console name (e.g. `"SNES"`). |
+| `num_achieved` | `int` | Achievements unlocked by the player. |
+| `num_possible` | `int` | Total achievements in the set. |
+| `percent` | `float` | Completion percentage (0–100). |
+| `last_played` | `str \| None` | ISO-ish timestamp of last session. |
+| `icon_url` | `str \| None` | Absolute URL of the game icon. |
+
+**`RAAchievement`** — a single unlocked achievement:
+
+| Field | Type | Description |
+|---|---|---|
+| `title` | `str` | Achievement title. |
+| `description` | `str` | Achievement description. |
+| `points` | `int` | Point value. |
+| `game_title` | `str` | Title of the game it belongs to. |
+| `date` | `str \| None` | Unlock timestamp. |
+| `badge_url` | `str \| None` | Absolute URL of the badge image. |
+
+**`MisterRAWebError`** — raised by `MisterRAWeb` on network failures, HTTP errors, or API-level errors (including bad credentials).
+
 ## API
 
 - **`MisterClient(host, port=8182, *, session=None, timeout=10)`** — async REST client; call `await client.async_close()` when done, or inject your own `aiohttp.ClientSession`.
@@ -116,6 +185,9 @@ asyncio.run(main())
 - **`apply_ws_message(message, status, menu_path, index_state)`** — pure reducer; apply a single WS text frame and return updated `(status, menu_path, index_state)`.
 - **`MisterSSH(host, port, username, password)`** — persistent asyncssh connection; `await ssh.async_probe()` returns telemetry dict.
 - **`parse_ssh_probe(raw)`** — parse the raw batched SSH output into a telemetry dict.
+- **`MisterRAWeb(username, api_key, *, session=None, timeout=15)`** — async RA Web API client; `await web.async_fetch_stats()` returns `MisterRAWebStats`.
+- **`MisterRAWebStats`**, **`RAGameProgress`**, **`RAAchievement`** — cloud-stats dataclasses (see section above).
+- **`MisterRAWebError`** — raised on RA Web API failures.
 - **`KEYBOARD_NAMES`**, **`INI_VIDEO_KEYS`**, **`WS_PATH`**, **`DEFAULT_PORT`** — protocol constants.
 
 ## Documentation

{python_mister_fpga-0.1.2 → python_mister_fpga-0.2.0}/README.md

@@ -76,6 +76,74 @@ async def main():
 asyncio.run(main())
 ```
 
+## RetroAchievements cloud stats
+
+`MisterRAWeb` queries the public [RetroAchievements.org Web API](https://api.docs.retroachievements.org/) to pull a player's points, rank, recently-played games, and latest unlocked achievement — no SSH required.  You need a **Web API key** from [retroachievements.org/settings](https://retroachievements.org/settings).
+
+```python
+import asyncio
+from mister_fpga import MisterRAWeb
+
+async def main():
+    web = MisterRAWeb("myuser", "my_api_key")
+    stats = await web.async_fetch_stats()
+    print(stats.hardcore_points, stats.rank, stats.current_game)
+    await web.async_close()
+
+asyncio.run(main())
+```
+
+### `MisterRAWeb(username, api_key, *, session=None, timeout=15)`
+
+Async HTTPS client for the RA Web API.  When `session` is `None` the client creates its own `aiohttp.ClientSession`; call `await web.async_close()` to release it.  Pass a shared session to manage its lifetime yourself.
+
+| Method | Description |
+|---|---|
+| `await async_fetch_stats() -> MisterRAWebStats` | Fire all three API calls concurrently and return an aggregated stats snapshot. |
+| `await async_validate()` | Lightweight credential check — raises `MisterRAWebError` if the username or API key is wrong. |
+| `await async_get_badge_image(url) -> bytes` | Fetch a badge or icon image by absolute URL (e.g. `stats.last_achievement.badge_url`). |
+| `await async_close()` | Close the session if this client created it. |
+
+### Dataclasses
+
+**`MisterRAWebStats`** — aggregated snapshot returned by `async_fetch_stats()`:
+
+| Field | Type | Description |
+|---|---|---|
+| `hardcore_points` | `int` | Total hardcore score. |
+| `softcore_points` | `int` | Total softcore score. |
+| `rank` | `int \| None` | Global hardcore rank (None if unranked). |
+| `total_ranked` | `int \| None` | Total number of ranked players. |
+| `current_game` | `RAGameProgress \| None` | Most recently played game (first entry in the recent-games list). |
+| `recent_games` | `list[RAGameProgress]` | Up to 10 recently played games, most-recent first. |
+| `last_achievement` | `RAAchievement \| None` | Most recently unlocked achievement (within the last 7 days). |
+
+**`RAGameProgress`** — per-game achievement progress:
+
+| Field | Type | Description |
+|---|---|---|
+| `game_id` | `int` | RA game ID. |
+| `title` | `str` | Game title. |
+| `console` | `str` | Console name (e.g. `"SNES"`). |
+| `num_achieved` | `int` | Achievements unlocked by the player. |
+| `num_possible` | `int` | Total achievements in the set. |
+| `percent` | `float` | Completion percentage (0–100). |
+| `last_played` | `str \| None` | ISO-ish timestamp of last session. |
+| `icon_url` | `str \| None` | Absolute URL of the game icon. |
+
+**`RAAchievement`** — a single unlocked achievement:
+
+| Field | Type | Description |
+|---|---|---|
+| `title` | `str` | Achievement title. |
+| `description` | `str` | Achievement description. |
+| `points` | `int` | Point value. |
+| `game_title` | `str` | Title of the game it belongs to. |
+| `date` | `str \| None` | Unlock timestamp. |
+| `badge_url` | `str \| None` | Absolute URL of the badge image. |
+
+**`MisterRAWebError`** — raised by `MisterRAWeb` on network failures, HTTP errors, or API-level errors (including bad credentials).
+
 ## API
 
 - **`MisterClient(host, port=8182, *, session=None, timeout=10)`** — async REST client; call `await client.async_close()` when done, or inject your own `aiohttp.ClientSession`.
@@ -85,6 +153,9 @@ asyncio.run(main())
 - **`apply_ws_message(message, status, menu_path, index_state)`** — pure reducer; apply a single WS text frame and return updated `(status, menu_path, index_state)`.
 - **`MisterSSH(host, port, username, password)`** — persistent asyncssh connection; `await ssh.async_probe()` returns telemetry dict.
 - **`parse_ssh_probe(raw)`** — parse the raw batched SSH output into a telemetry dict.
+- **`MisterRAWeb(username, api_key, *, session=None, timeout=15)`** — async RA Web API client; `await web.async_fetch_stats()` returns `MisterRAWebStats`.
+- **`MisterRAWebStats`**, **`RAGameProgress`**, **`RAAchievement`** — cloud-stats dataclasses (see section above).
+- **`MisterRAWebError`** — raised on RA Web API failures.
 - **`KEYBOARD_NAMES`**, **`INI_VIDEO_KEYS`**, **`WS_PATH`**, **`DEFAULT_PORT`** — protocol constants.
 
 ## Documentation

{python_mister_fpga-0.1.2 → python_mister_fpga-0.2.0}/docs/api.md

@@ -13,3 +13,13 @@
 ::: mister_fpga.parse_ssh_probe
 
 ::: mister_fpga.MisterConnectionError
+
+::: mister_fpga.MisterRAWeb
+
+::: mister_fpga.MisterRAWebStats
+
+::: mister_fpga.RAGameProgress
+
+::: mister_fpga.RAAchievement
+
+::: mister_fpga.MisterRAWebError

{python_mister_fpga-0.1.2 → python_mister_fpga-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "python-mister-fpga"
-version = "0.1.2"
+version = "0.2.0"
 description = "Async Python client for the MiSTer FPGA mrext Remote API (REST + WebSocket) and SSH telemetry"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -28,7 +28,14 @@ Documentation = "https://hudsonbrendon.github.io/python-mister-fpga/"
 Issues = "https://github.com/hudsonbrendon/python-mister-fpga/issues"
 
 [project.optional-dependencies]
-test = ["pytest>=8", "pytest-asyncio>=0.23", "aioresponses>=0.7", "ruff"]
+test = [
+  "pytest>=8",
+  "pytest-asyncio>=0.23",
+  "aioresponses>=0.7",
+  # aiohttp<3.10: aioresponses 0.7.8 uses the removed loop= param in StreamReader
+  "aiohttp<3.10",
+  "ruff",
+]
 docs = ["mkdocs-material>=9.5", "mkdocstrings[python]>=0.25"]
 
 [tool.hatch.build.targets.wheel]

{python_mister_fpga-0.1.2 → python_mister_fpga-0.2.0}/src/mister_fpga/__init__.py

@@ -6,9 +6,18 @@ from .const import (
     DEFAULT_SSH_USERNAME,
     INI_VIDEO_KEYS,
     KEYBOARD_NAMES,
+    RA_STATUS_CMD,
+    RA_SUPPORTED_SYSTEMS,
+    RA_USERNAME_PLACEHOLDER,
     SSH_PROBE_CMD,
     WS_PATH,
+    MisterRAStatus,
+    MisterRAWebStats,
+    RAAchievement,
+    RAGameProgress,
 )
+from .ra import MisterRA, MisterRAError, parse_ra_status
+from .ra_web import MisterRAWeb, MisterRAWebError
 from .ssh import MisterSSH, parse_ssh_probe
 from .websocket import MisterWebSocketClient, apply_ws_message
 
@@ -16,16 +25,28 @@ __all__ = [
     "MisterClient",
     "MisterStatus",
     "MisterConnectionError",
+    "MisterRA",
+    "MisterRAError",
+    "MisterRAStatus",
+    "MisterRAWeb",
+    "MisterRAWebError",
+    "MisterRAWebStats",
     "MisterWebSocketClient",
     "apply_ws_message",
     "MisterSSH",
+    "parse_ra_status",
     "parse_ssh_probe",
+    "RAAchievement",
+    "RAGameProgress",
     "KEYBOARD_NAMES",
     "INI_VIDEO_KEYS",
+    "RA_STATUS_CMD",
+    "RA_SUPPORTED_SYSTEMS",
+    "RA_USERNAME_PLACEHOLDER",
     "WS_PATH",
     "DEFAULT_PORT",
     "DEFAULT_SSH_PORT",
     "DEFAULT_SSH_USERNAME",
     "SSH_PROBE_CMD",
 ]
-__version__ = "0.1.2"
+__version__ = "0.2.0"

python_mister_fpga-0.2.0/src/mister_fpga/const.py

@@ -0,0 +1,145 @@
+"""Protocol constants for the MiSTer FPGA mrext Remote API."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+DEFAULT_PORT = 8182
+HTTP_TIMEOUT = 10
+
+# mrext Remote API paths (relative to base_url = http://host:port/api)
+PATH_PLAYING = "/games/playing"
+PATH_SYSINFO = "/sysinfo"
+PATH_SYSTEMS = "/systems"
+PATH_GAMES_LAUNCH = "/games/launch"
+PATH_GAMES_SEARCH = "/games/search"
+PATH_GAMES_INDEX = "/games/index"
+PATH_LAUNCH_MENU = "/launch/menu"
+PATH_KEYBOARD = "/controls/keyboard"
+PATH_REBOOT = "/settings/system/reboot"
+PATH_RESTART_REMOTE = "/settings/remote/restart"
+PATH_SCREENSHOTS = "/screenshots"
+PATH_MUSIC_STATUS = "/music/status"
+PATH_MUSIC_PLAY = "/music/play"
+PATH_MUSIC_STOP = "/music/stop"
+PATH_MUSIC_NEXT = "/music/next"
+PATH_MUSIC_PLAYLIST = "/music/playlist"
+PATH_MUSIC_PLAYBACK = "/music/playback"
+PATH_WALLPAPERS = "/wallpapers"
+PATH_INIS = "/settings/inis"
+PATH_CORE_MENU = "/settings/core/menu"
+PATH_SCRIPTS_LIST = "/scripts/list"
+PATH_SCRIPTS_LAUNCH = "/scripts/launch"
+PATH_SCRIPTS_CONSOLE = "/scripts/console"
+PATH_SCRIPTS_KILL = "/scripts/kill"
+PATH_PEERS = "/settings/remote/peers"
+PATH_LAUNCH = "/launch"
+PATH_LAUNCH_TOKEN = "/l"
+PATH_LAUNCH_NEW = "/launch/new"
+PATH_KEYBOARD_RAW = "/controls/keyboard-raw"
+
+# WebSocket endpoint (mounted under /api on Remote v0.4)
+WS_PATH = "/api/ws"
+
+# MiSTer.ini keys exposed as Number entities (value range 0-100)
+INI_VIDEO_KEYS = ("video_brightness", "video_contrast", "video_saturation")
+
+# SSH defaults and probe command
+DEFAULT_SSH_PORT = 22
+DEFAULT_SSH_USERNAME = "root"
+
+SSH_PROBE_CMD = (
+    "cat /tmp/CORENAME 2>/dev/null; echo '|||'; "
+    "cat /proc/uptime 2>/dev/null; echo '|||'; "
+    "cat /proc/loadavg 2>/dev/null; echo '|||'; "
+    "awk '/MemTotal|MemAvailable/{print $2}' /proc/meminfo 2>/dev/null; echo '|||'; "
+    "stat -c %Y /media/fat/MiSTer 2>/dev/null"
+)
+
+# Keyboard control names accepted by POST /controls/keyboard/{name}
+KEYBOARD_NAMES = (
+    "up", "down", "left", "right", "confirm", "back", "cancel", "menu",
+    "osd", "core_select", "user", "volume_up", "volume_down", "volume_mute",
+    "reset", "screenshot", "raw_screenshot", "console", "exit_console",
+    "computer_osd", "change_background", "pair_bluetooth", "toggle_core_dates",
+)
+
+# RetroAchievements (local, via SSH helper scripts) ------------------------
+
+# mrext system keys for cores with odelot RA-modified builds.
+RA_SUPPORTED_SYSTEMS = (
+    "NES", "FDS", "SNES", "MegaDrive", "SMS", "Gameboy", "N64", "PSX",
+    "GBA", "MegaCD", "NeoGeo", "TurboGrafx16", "Atari2600", "Atari7800", "S32X",
+)
+
+# Placeholder written by the RA installer before the user fills credentials.
+RA_USERNAME_PLACEHOLDER = "YOUR_RA_USERNAME"
+
+# One-shot SSH command emitting parseable RA state. Combines an install probe,
+# the username from the cfg, and ra_status.sh output.
+RA_STATUS_CMD = (
+    "if [ -d /media/fat/_RA_Cores ]; then echo installed=1; "
+    "else echo installed=0; fi; "
+    "echo \"username=$(sed -n 's/^username=//p' "
+    "/media/fat/retroachievements.cfg 2>/dev/null | head -1)\"; "
+    "bash /media/fat/Scripts/.ra/ra_status.sh 2>/dev/null"
+)
+
+
+@dataclass
+class MisterRAStatus:
+    """Parsed RetroAchievements local state."""
+
+    installed: bool = False
+    cores_on: bool = False
+    binary_ra: bool = False
+    hardcore: bool = False
+    username: str | None = None
+    cores_active: int = 0
+    cores_total: int = 0
+
+
+# RetroAchievements Web API (cloud player stats) ------------------------------
+
+RA_WEB_API_BASE = "https://retroachievements.org/API/"
+RA_WEB_IMAGE_BASE = "https://media.retroachievements.org"
+RA_WEB_DEFAULT_RECENT_COUNT = 10
+RA_WEB_DEFAULT_ACHIEVEMENT_MINUTES = 10080  # 7 days, in minutes
+
+
+@dataclass
+class RAGameProgress:
+    """Per-game achievement progress from the RA Web API."""
+
+    game_id: int
+    title: str
+    console: str
+    num_achieved: int = 0
+    num_possible: int = 0
+    percent: float = 0.0
+    last_played: str | None = None
+    icon_url: str | None = None
+
+
+@dataclass
+class RAAchievement:
+    """A single unlocked achievement from the RA Web API."""
+
+    title: str
+    description: str
+    points: int
+    game_title: str
+    date: str | None = None
+    badge_url: str | None = None
+
+
+@dataclass
+class MisterRAWebStats:
+    """Aggregated RetroAchievements cloud player stats."""
+
+    hardcore_points: int = 0
+    softcore_points: int = 0
+    rank: int | None = None
+    total_ranked: int | None = None
+    current_game: RAGameProgress | None = None
+    recent_games: list[RAGameProgress] = field(default_factory=list)
+    last_achievement: RAAchievement | None = None

python_mister_fpga-0.2.0/src/mister_fpga/ra.py

@@ -0,0 +1,82 @@
+"""RetroAchievements local control over SSH (best-effort)."""
+from __future__ import annotations
+
+import logging
+import re
+
+from .const import RA_STATUS_CMD, RA_USERNAME_PLACEHOLDER, MisterRAStatus
+
+_LOGGER = logging.getLogger(__name__)
+
+# Matches a per-core table row: "NES   RA  -> ..." or "PSX   STOCK  ...".
+_CORE_ROW = re.compile(r"^\S+\s+(RA|STOCK)\b")
+
+
+def parse_ra_status(raw: str) -> MisterRAStatus:
+    """Parse RA_STATUS_CMD output into a MisterRAStatus.
+
+    Tolerant of format drift: matches stable prefixes, ignores unknown lines,
+    and never raises.
+    """
+    status = MisterRAStatus()
+    total = 0
+    active = 0
+    for line in raw.splitlines():
+        stripped = line.strip()
+        if stripped.startswith("installed="):
+            status.installed = stripped.split("=", 1)[1].strip() == "1"
+        elif stripped.startswith("username="):
+            value = stripped.split("=", 1)[1].strip()
+            status.username = (
+                value if value and value != RA_USERNAME_PLACEHOLDER else None
+            )
+        elif stripped.startswith("Mode flag:"):
+            status.cores_on = "ON" in stripped.split(":", 1)[1]
+        elif stripped.startswith("Hardcore"):
+            status.hardcore = "ON" in stripped.split(":", 1)[1]
+        elif stripped.startswith("/media/fat/MiSTer"):
+            status.binary_ra = "RA" in stripped.split(":", 1)[1]
+        else:
+            match = _CORE_ROW.match(line)
+            if match:
+                total += 1
+                if match.group(1) == "RA":
+                    active += 1
+    status.cores_total = total
+    status.cores_active = active
+    return status
+
+
+class MisterRAError(Exception):
+    """A RetroAchievements control command failed."""
+
+
+class MisterRA:
+    """RetroAchievements local control sharing a MisterSSH connection."""
+
+    def __init__(self, ssh) -> None:
+        self._ssh = ssh
+
+    async def async_status(self) -> MisterRAStatus | None:
+        """Probe RA state. Returns None only on SSH failure (best-effort)."""
+        try:
+            _rc, out = await self._ssh.async_run(RA_STATUS_CMD, timeout=15)
+        except Exception as err:  # noqa: BLE001 - best-effort; never break the integration
+            _LOGGER.debug("RA status probe failed: %s", err)
+            return None
+        return parse_ra_status(out)
+
+    async def async_cores_on(self) -> None:
+        await self._run_checked("bash /media/fat/Scripts/.ra/ra_on.sh")
+
+    async def async_cores_off(self) -> None:
+        await self._run_checked("bash /media/fat/Scripts/.ra/ra_off.sh")
+
+    async def async_set_hardcore(self, enabled: bool) -> None:
+        arg = "on" if enabled else "off"
+        await self._run_checked(f"bash /media/fat/Scripts/.ra/ra_hardcore.sh {arg}")
+
+    async def _run_checked(self, command: str) -> None:
+        rc, out = await self._ssh.async_run(command, timeout=30)
+        if rc != 0:
+            raise MisterRAError(f"command failed (rc={rc}): {command}\n{out}")