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

python_mister_fpga-0.1.2/.github/workflows/docs.yml

@@ -0,0 +1,33 @@
+name: Docs
+on:
+  push:
+    branches: [main]
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+concurrency:
+  group: pages
+  cancel-in-progress: true
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[docs]"
+      - run: mkdocs build --strict
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

python_mister_fpga-0.1.2/.github/workflows/release.yml

@@ -0,0 +1,26 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  pypi-publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # required for PyPI Trusted Publishing (OIDC)
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build distributions
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

{python_mister_fpga-0.1.0 → python_mister_fpga-0.1.2}/.gitignore

@@ -8,3 +8,4 @@ build/
 .ruff_cache/
 .coverage
 .DS_Store
+site/

python_mister_fpga-0.1.2/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.2
+- Add online documentation (MkDocs Material) at https://hudsonbrendon.github.io/python-mister-fpga/ and enrich public-API docstrings.
+
+## 0.1.1
+- Export `DEFAULT_SSH_PORT`, `DEFAULT_SSH_USERNAME` and `SSH_PROBE_CMD` from the top-level package so consumers can reuse them without duplicating.
+
+## 0.1.0
+- Initial release: async REST client (`MisterClient`/`MisterStatus`/`MisterConnectionError`), WebSocket reducer + client (`apply_ws_message`/`MisterWebSocketClient`), and SSH telemetry (`parse_ssh_probe`/`MisterSSH`) for the MiSTer FPGA mrext Remote API.

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

@@ -1,8 +1,9 @@
 Metadata-Version: 2.4
 Name: python-mister-fpga
-Version: 0.1.0
+Version: 0.1.2
 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/
 Project-URL: Issues, https://github.com/hudsonbrendon/python-mister-fpga/issues
 Author-email: Hudson Brendon <contato.hudsonbrendon@gmail.com>
 License: MIT
@@ -18,6 +19,9 @@ Classifier: Topic :: Software Development :: Libraries
 Requires-Python: >=3.11
 Requires-Dist: aiohttp>=3.9
 Requires-Dist: asyncssh>=2.21
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.25; extra == 'docs'
 Provides-Extra: test
 Requires-Dist: aioresponses>=0.7; extra == 'test'
 Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
@@ -38,6 +42,7 @@ Description-Content-Type: text/markdown
 [![PyPI version](https://img.shields.io/pypi/v/python-mister-fpga)](https://pypi.org/project/python-mister-fpga/)
 [![Python versions](https://img.shields.io/pypi/pyversions/python-mister-fpga)](https://pypi.org/project/python-mister-fpga/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-mkdocs--material-blue)](https://hudsonbrendon.github.io/python-mister-fpga/)
 
 Async Python client for the [mrext Remote API](https://github.com/wizzomafizzo/mrext) (REST + WebSocket) and optional SSH telemetry for the MiSTer FPGA. Zero Home Assistant dependency — use it in any Python project.
 
@@ -113,6 +118,10 @@ asyncio.run(main())
 - **`parse_ssh_probe(raw)`** — parse the raw batched SSH output into a telemetry dict.
 - **`KEYBOARD_NAMES`**, **`INI_VIDEO_KEYS`**, **`WS_PATH`**, **`DEFAULT_PORT`** — protocol constants.
 
+## Documentation
+
+Full documentation is available at **https://hudsonbrendon.github.io/python-mister-fpga/** — usage guide, runnable examples, and auto-generated API reference.
+
 ## Credits
 
 REST/WebSocket API by [wizzomafizzo/mrext](https://github.com/wizzomafizzo/mrext). MiSTer-kun logo by the MiSTer-devel project. Author [@hudsonbrendon](https://github.com/hudsonbrendon).

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

@@ -11,6 +11,7 @@
 [![PyPI version](https://img.shields.io/pypi/v/python-mister-fpga)](https://pypi.org/project/python-mister-fpga/)
 [![Python versions](https://img.shields.io/pypi/pyversions/python-mister-fpga)](https://pypi.org/project/python-mister-fpga/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-mkdocs--material-blue)](https://hudsonbrendon.github.io/python-mister-fpga/)
 
 Async Python client for the [mrext Remote API](https://github.com/wizzomafizzo/mrext) (REST + WebSocket) and optional SSH telemetry for the MiSTer FPGA. Zero Home Assistant dependency — use it in any Python project.
 
@@ -86,6 +87,10 @@ asyncio.run(main())
 - **`parse_ssh_probe(raw)`** — parse the raw batched SSH output into a telemetry dict.
 - **`KEYBOARD_NAMES`**, **`INI_VIDEO_KEYS`**, **`WS_PATH`**, **`DEFAULT_PORT`** — protocol constants.
 
+## Documentation
+
+Full documentation is available at **https://hudsonbrendon.github.io/python-mister-fpga/** — usage guide, runnable examples, and auto-generated API reference.
+
 ## Credits
 
 REST/WebSocket API by [wizzomafizzo/mrext](https://github.com/wizzomafizzo/mrext). MiSTer-kun logo by the MiSTer-devel project. Author [@hudsonbrendon](https://github.com/hudsonbrendon).

python_mister_fpga-0.1.2/docs/api.md

@@ -0,0 +1,15 @@
+# API reference
+
+::: mister_fpga.MisterClient
+
+::: mister_fpga.MisterStatus
+
+::: mister_fpga.MisterWebSocketClient
+
+::: mister_fpga.apply_ws_message
+
+::: mister_fpga.MisterSSH
+
+::: mister_fpga.parse_ssh_probe
+
+::: mister_fpga.MisterConnectionError

python_mister_fpga-0.1.2/docs/changelog.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.2
+
+- Add online documentation (MkDocs Material) at <https://hudsonbrendon.github.io/python-mister-fpga/> and enrich public-API docstrings.
+
+## 0.1.1
+
+- Export `DEFAULT_SSH_PORT`, `DEFAULT_SSH_USERNAME` and `SSH_PROBE_CMD` from the top-level package so consumers can reuse them without duplicating.
+
+## 0.1.0
+
+- Initial release: async REST client (`MisterClient`/`MisterStatus`/`MisterConnectionError`), WebSocket reducer + client (`apply_ws_message`/`MisterWebSocketClient`), and SSH telemetry (`parse_ssh_probe`/`MisterSSH`) for the MiSTer FPGA mrext Remote API.

python_mister_fpga-0.1.2/docs/index.md

@@ -0,0 +1,37 @@
+<p align="center"><img src="assets/logo.png" width="380" alt="python-mister-fpga"></p>
+
+# python-mister-fpga
+
+**python-mister-fpga** is an async Python library for controlling and monitoring a
+[MiSTer FPGA](https://github.com/MiSTer-devel/Main_MiSTer/wiki) device through the
+[mrext Remote API](https://github.com/wizzomafizzo/mrext).  It covers the full
+REST surface (launch cores/games, screenshots, music, wallpapers, INI files,
+scripts, and more), a reconnecting WebSocket client for real-time state updates,
+and optional SSH telemetry — all with no Home Assistant dependency.
+
+## Install
+
+```bash
+pip install python-mister-fpga
+```
+
+## Quickstart
+
+```python
+import asyncio
+from mister_fpga import MisterClient
+
+async def main():
+    client = MisterClient("192.168.1.50")
+    status = await client.async_get_status()
+    print(status.core, status.game)
+    await client.async_close()
+
+asyncio.run(main())
+```
+
+## Next steps
+
+- [Usage guide](usage.md) — full runnable examples for REST, WebSocket, and SSH.
+- [API reference](api.md) — auto-generated from docstrings.
+- [Changelog](changelog.md) — version history.

python_mister_fpga-0.1.2/docs/usage.md

@@ -0,0 +1,92 @@
+# Usage
+
+## REST client
+
+Use `MisterClient` to call the mrext Remote REST API.  All methods are `async`;
+call `async_close()` when done (or inject your own `aiohttp.ClientSession` and
+manage its lifetime yourself).
+
+```python
+import asyncio
+from mister_fpga import MisterClient
+
+async def main():
+    client = MisterClient("192.168.1.50")
+    try:
+        # Fetch combined sysinfo + playing snapshot
+        status = await client.async_get_status()
+        print("Core :", status.core)
+        print("Game :", status.game_name)
+        print("Online:", status.online)
+
+        # Launch a game by its absolute SD-card path
+        await client.async_launch_game("/media/fat/games/SNES/Chrono Trigger.sfc")
+
+        # Search the game index
+        results = await client.async_search_games("Chrono", system="snes")
+        print(results)
+
+        # Return to the main menu
+        await client.async_launch_menu()
+    finally:
+        await client.async_close()
+
+asyncio.run(main())
+```
+
+## WebSocket (real-time updates)
+
+`MisterWebSocketClient` connects to the mrext WebSocket endpoint and calls your
+callback for every TEXT frame.  Pair it with `apply_ws_message` — a pure
+reducer — to keep a local `MisterStatus` in sync without polling.
+
+```python
+import asyncio
+from mister_fpga import MisterWebSocketClient, MisterStatus, apply_ws_message
+
+state = MisterStatus(online=True)
+menu_path = None
+index_state = (False, False)
+
+def on_message(text: str) -> None:
+    global state, menu_path, index_state
+    state, menu_path, index_state = apply_ws_message(
+        text, state, menu_path, index_state
+    )
+    print(f"core={state.core}  game={state.game_name}")
+
+async def main():
+    ws = MisterWebSocketClient("192.168.1.50")
+    # listen() blocks and reconnects automatically; cancel the task to stop.
+    await ws.listen(on_message)
+
+asyncio.run(main())
+```
+
+To stop the loop from outside (e.g. on a signal), call `ws.stop()`.
+
+## SSH telemetry
+
+`MisterSSH` opens a persistent asyncssh connection and runs a batched probe
+command that collects active core, uptime, CPU load, memory usage, and firmware
+timestamp in a single round-trip.  The probe is best-effort: it returns `{}`
+instead of raising on any SSH failure.
+
+```python
+import asyncio
+from mister_fpga import MisterSSH
+
+async def main():
+    ssh = MisterSSH("192.168.1.50", port=22, username="root", password="1")
+    try:
+        data = await ssh.async_probe()
+        print("Active core      :", data.get("active_core"))
+        print("Uptime (seconds) :", data.get("uptime_seconds"))
+        print("CPU load (1m)    :", data.get("cpu_load_1m"))
+        print("Memory used %    :", data.get("memory_used_percent"))
+        print("Firmware mtime   :", data.get("firmware_timestamp"))
+    finally:
+        await ssh.async_close()
+
+asyncio.run(main())
+```

python_mister_fpga-0.1.2/mkdocs.yml

@@ -0,0 +1,49 @@
+site_name: python-mister-fpga
+site_description: Async Python client for the MiSTer FPGA mrext Remote API (REST + WebSocket) and SSH telemetry
+site_url: https://hudsonbrendon.github.io/python-mister-fpga/
+repo_url: https://github.com/hudsonbrendon/python-mister-fpga
+repo_name: hudsonbrendon/python-mister-fpga
+docs_dir: docs
+theme:
+  name: material
+  logo: assets/icon.png
+  favicon: assets/icon.png
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      toggle: {icon: material/weather-night, name: Switch to dark mode}
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      toggle: {icon: material/weather-sunny, name: Switch to light mode}
+  features:
+    - navigation.sections
+    - navigation.top
+    - content.code.copy
+    - search.suggest
+    - search.highlight
+plugins:
+  - search
+  - mkdocstrings:
+      handlers:
+        python:
+          paths: [src]
+          options:
+            docstring_style: google
+            show_source: true
+            show_root_heading: true
+            heading_level: 2
+            members_order: source
+            separate_signature: true
+            show_signature_annotations: true
+markdown_extensions:
+  - admonition
+  - pymdownx.highlight
+  - pymdownx.superfences
+  - pymdownx.snippets
+  - toc:
+      permalink: true
+nav:
+  - Home: index.md
+  - Usage: usage.md
+  - API reference: api.md
+  - Changelog: changelog.md

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "python-mister-fpga"
-version = "0.1.0"
+version = "0.1.2"
 description = "Async Python client for the MiSTer FPGA mrext Remote API (REST + WebSocket) and SSH telemetry"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -24,10 +24,12 @@ dependencies = ["aiohttp>=3.9", "asyncssh>=2.21"]
 
 [project.urls]
 Homepage = "https://github.com/hudsonbrendon/python-mister-fpga"
+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"]
+docs = ["mkdocs-material>=9.5", "mkdocstrings[python]>=0.25"]
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/mister_fpga"]

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

@@ -1,6 +1,14 @@
 """Async Python client for the MiSTer FPGA mrext Remote API."""
 from .client import MisterClient, MisterConnectionError, MisterStatus
-from .const import DEFAULT_PORT, INI_VIDEO_KEYS, KEYBOARD_NAMES, WS_PATH
+from .const import (
+    DEFAULT_PORT,
+    DEFAULT_SSH_PORT,
+    DEFAULT_SSH_USERNAME,
+    INI_VIDEO_KEYS,
+    KEYBOARD_NAMES,
+    SSH_PROBE_CMD,
+    WS_PATH,
+)
 from .ssh import MisterSSH, parse_ssh_probe
 from .websocket import MisterWebSocketClient, apply_ws_message
 
@@ -16,5 +24,8 @@ __all__ = [
     "INI_VIDEO_KEYS",
     "WS_PATH",
     "DEFAULT_PORT",
+    "DEFAULT_SSH_PORT",
+    "DEFAULT_SSH_USERNAME",
+    "SSH_PROBE_CMD",
 ]
-__version__ = "0.1.0"
+__version__ = "0.1.2"

{python_mister_fpga-0.1.0 → python_mister_fpga-0.1.2}/src/mister_fpga/client.py

@@ -44,12 +44,38 @@ _LOGGER = logging.getLogger(__name__)
 
 
 class MisterConnectionError(Exception):
-    """Raised when the MiSTer Remote API is unreachable or returns an error."""
+    """Raised when the MiSTer Remote API is unreachable or returns an error.
+
+    This exception wraps ``aiohttp.ClientError``, ``TimeoutError``, and
+    invalid-JSON responses so callers have a single exception type to catch.
+    """
 
 
 @dataclass
 class MisterStatus:
-    """Snapshot of the MiSTer device state."""
+    """Snapshot of the MiSTer device state at a point in time.
+
+    Returned by :meth:`MisterClient.async_get_status` and mutated in-place by
+    :func:`~mister_fpga.apply_ws_message`.
+
+    Attributes:
+        online: ``True`` when the API responded successfully.
+        core: Short core identifier (e.g. ``"SNES"``), or ``None`` when the
+            menu is active.
+        system: System slug used by mrext (e.g. ``"snes"``).
+        system_name: Human-readable system name (e.g. ``"Super Nintendo"``).
+        game: Full path of the running game ROM, or ``None``.
+        game_name: Basename of the game without extension, or ``None``.
+        hostname: MiSTer hostname as reported by the Remote API.
+        version: mrext Remote version string.
+        ip: Primary IP address of the MiSTer device.
+        ips: All IP addresses reported by the device.
+        updated: ISO-8601 timestamp of the last sysinfo update.
+        dns: DNS server address reported by the device.
+        disk_total: Total SD-card space in bytes (first disk).
+        disk_used: Used SD-card space in bytes (first disk).
+        disk_free: Free SD-card space in bytes (first disk).
+    """
 
     online: bool = False
     core: str | None = None
@@ -77,7 +103,20 @@ class MisterStatus:
 
 
 class MisterClient:
-    """Thin async wrapper around the mrext Remote REST API."""
+    """Async REST client for the MiSTer FPGA mrext Remote API.
+
+    Wraps every endpoint exposed by the mrext Remote service under
+    ``http://host:port/api``.  All network I/O is non-blocking; methods raise
+    :class:`MisterConnectionError` on any network or HTTP error.
+
+    Args:
+        host: IP address or hostname of the MiSTer device.
+        port: mrext Remote port (default ``8182``).
+        session: Optional shared ``aiohttp.ClientSession``.  When ``None`` the
+            client creates and owns its own session; call
+            :meth:`async_close` to release it.
+        timeout: Per-request timeout in seconds (default ``10``).
+    """
 
     def __init__(
         self,
@@ -100,7 +139,7 @@ class MisterClient:
         return self._session
 
     async def async_close(self) -> None:
-        """Close the session only if this client created it."""
+        """Close the underlying HTTP session if this client created it."""
         if self._owns_session and self._session is not None:
             await self._session.close()
             self._session = None
@@ -139,6 +178,14 @@ class MisterClient:
             raise MisterConnectionError(f"{method} {url} failed: {err}") from err
 
     async def async_get_status(self) -> MisterStatus:
+        """Fetch a combined sysinfo + playing snapshot.
+
+        Returns:
+            A :class:`MisterStatus` with ``online=True`` on success.
+
+        Raises:
+            MisterConnectionError: If either underlying request fails.
+        """
         sysinfo = await self._request("GET", PATH_SYSINFO) or {}
         playing = await self._request("GET", PATH_PLAYING) or {}
         ips = sysinfo.get("ips") or []
@@ -163,18 +210,31 @@ class MisterClient:
         )
 
     async def async_get_systems(self) -> list[dict]:
+        """Return the list of systems known to mrext."""
         return await self._request("GET", PATH_SYSTEMS) or []
 
     async def async_launch_system(self, system_id: str) -> None:
+        """Launch the default game/core for *system_id*."""
         await self._request("POST", f"{PATH_SYSTEMS}/{system_id}")
 
     async def async_launch_game(self, path: str) -> None:
+        """Launch a game by its absolute path on the MiSTer SD card."""
         await self._request("POST", PATH_GAMES_LAUNCH, payload={"path": path})
 
     async def async_launch_menu(self) -> None:
+        """Return to the MiSTer main menu."""
         await self._request("POST", PATH_LAUNCH_MENU)
 
     async def async_search_games(self, query: str, system: str = "all") -> dict:
+        """Search the game index.
+
+        Args:
+            query: Free-text search string.
+            system: Limit results to a system slug, or ``"all"`` (default).
+
+        Returns:
+            A dict with a ``results`` key containing matching game entries.
+        """
         return (
             await self._request(
                 "POST", PATH_GAMES_SEARCH, payload={"data": query, "system": system}
@@ -183,104 +243,154 @@ class MisterClient:
         )
 
     async def async_index_games(self) -> None:
+        """Trigger a background re-index of the game library."""
         await self._request("POST", PATH_GAMES_INDEX)
 
     async def async_send_keyboard(self, name: str) -> None:
+        """Send a named virtual-keyboard event (see ``KEYBOARD_NAMES``)."""
         await self._request("POST", f"{PATH_KEYBOARD}/{name}")
 
     async def async_reboot(self) -> None:
+        """Reboot the MiSTer device."""
         await self._request("POST", PATH_REBOOT)
 
     async def async_restart_remote(self) -> None:
+        """Restart the mrext Remote service on the MiSTer."""
         await self._request("POST", PATH_RESTART_REMOTE)
 
     async def async_take_screenshot(self) -> None:
+        """Capture a screenshot on the MiSTer and save it server-side."""
         await self._request("POST", PATH_SCREENSHOTS)
 
     async def async_get_screenshots(self) -> list[dict]:
+        """Return metadata for all saved screenshots."""
         return await self._request("GET", PATH_SCREENSHOTS) or []
 
     async def async_get_screenshot_image(self, core: str, filename: str) -> bytes:
+        """Download a screenshot image as raw bytes.
+
+        Args:
+            core: Core name sub-directory (e.g. ``"SNES"``).
+            filename: Screenshot filename within that sub-directory.
+
+        Returns:
+            Raw image bytes (typically PNG).
+
+        Raises:
+            MisterConnectionError: If the image cannot be retrieved.
+        """
         return await self._request(
             "GET", f"{PATH_SCREENSHOTS}/{core}/{filename}", parse_json=False
         )
 
     async def async_get_music_status(self) -> dict:
+        """Return the current music-player status dict."""
         return await self._request("GET", PATH_MUSIC_STATUS) or {}
 
     async def async_music_play(self) -> None:
+        """Start or resume music playback."""
         await self._request("POST", PATH_MUSIC_PLAY)
 
     async def async_music_stop(self) -> None:
+        """Stop music playback."""
         await self._request("POST", PATH_MUSIC_STOP)
 
     async def async_music_next(self) -> None:
+        """Skip to the next track."""
         await self._request("POST", PATH_MUSIC_NEXT)
 
     # --- Wallpapers ---
     async def async_get_wallpapers(self) -> dict:
+        """Return available wallpapers and the currently active one."""
         return await self._request("GET", PATH_WALLPAPERS) or {}
 
     async def async_set_wallpaper(self, filename: str) -> None:
+        """Set the active wallpaper by filename."""
         await self._request("POST", f"{PATH_WALLPAPERS}/{filename}")
 
     async def async_clear_wallpaper(self) -> None:
+        """Remove the active wallpaper (revert to default)."""
         await self._request("DELETE", PATH_WALLPAPERS)
 
     # --- INI files ---
     async def async_get_inis(self) -> dict:
+        """Return a list of MiSTer.ini profiles and the active index."""
         return await self._request("GET", PATH_INIS) or {}
 
     async def async_get_ini_values(self, ini_id: int) -> dict:
+        """Return all key/value pairs for INI profile *ini_id*."""
         return await self._request("GET", f"{PATH_INIS}/{ini_id}") or {}
 
     async def async_set_active_ini(self, ini_id: int) -> None:
+        """Switch the active MiSTer.ini profile to *ini_id*."""
         await self._request("PUT", PATH_INIS, payload={"ini": ini_id})
 
     async def async_set_ini_values(self, ini_id: int, values: dict) -> None:
+        """Update key/value pairs in INI profile *ini_id*."""
         await self._request("PUT", f"{PATH_INIS}/{ini_id}", payload=values)
 
     async def async_set_background_mode(self, mode: int) -> None:
+        """Set the core/menu background display mode (0 = off, 1 = wallpaper, …)."""
         await self._request("PUT", PATH_CORE_MENU, payload={"mode": mode})
 
     # --- Music (extended) ---
     async def async_get_music_playlists(self) -> list[str]:
+        """Return the list of available music playlist names."""
         return await self._request("GET", PATH_MUSIC_PLAYLIST) or []
 
     async def async_set_music_playlist(self, name: str) -> None:
+        """Activate the music playlist identified by *name*."""
         await self._request("POST", f"{PATH_MUSIC_PLAYLIST}/{name}")
 
     async def async_set_music_playback(self, mode: str) -> None:
+        """Set playback mode (e.g. ``"random"``, ``"loop"``)."""
         await self._request("POST", f"{PATH_MUSIC_PLAYBACK}/{mode}")
 
     # --- Scripts ---
     async def async_get_scripts(self) -> dict:
+        """Return the list of user scripts available on the MiSTer."""
         return await self._request("GET", PATH_SCRIPTS_LIST) or {}
 
     async def async_launch_script(self, filename: str) -> None:
+        """Launch a user script by its filename."""
         await self._request("POST", f"{PATH_SCRIPTS_LAUNCH}/{filename}")
 
     async def async_open_console(self) -> None:
+        """Open the MiSTer console (script terminal)."""
         await self._request("POST", PATH_SCRIPTS_CONSOLE)
 
     async def async_kill_script(self) -> None:
+        """Kill the currently running user script."""
         await self._request("POST", PATH_SCRIPTS_KILL)
 
     # --- Peers ---
     async def async_get_peers(self) -> list[dict]:
+        """Return the list of mrext Remote peers on the local network."""
         data = await self._request("GET", PATH_PEERS) or {}
         return data.get("peers", [])
 
     # --- Launchers ---
     async def async_launch_path(self, path: str) -> None:
+        """Launch a file (ROM, core, script) by its absolute SD-card path."""
         await self._request("POST", PATH_LAUNCH, payload={"path": path})
 
     async def async_launch_token(self, data: str) -> None:
+        """Launch using a short-link token (mrext ``/l/<data>`` endpoint)."""
         await self._request("GET", f"{PATH_LAUNCH_TOKEN}/{data}")
 
     async def async_create_shortcut(
         self, game_path: str, folder: str, name: str
     ) -> dict:
+        """Create a game shortcut in the Favourites/Recents folder.
+
+        Args:
+            game_path: Absolute path to the game ROM on the SD card.
+            folder: Target folder name (e.g. ``"_Favorites"``).
+            name: Display name for the shortcut.
+
+        Returns:
+            A dict describing the created shortcut entry.
+        """
         return await self._request(
             "POST",
             PATH_LAUNCH_NEW,
@@ -289,4 +399,5 @@ class MisterClient:
 
     # --- Raw keyboard ---
     async def async_send_keyboard_raw(self, code: int) -> None:
+        """Send a raw HID keyboard scan-code integer."""
         await self._request("POST", f"{PATH_KEYBOARD_RAW}/{code}")

{python_mister_fpga-0.1.0 → python_mister_fpga-0.1.2}/src/mister_fpga/ssh.py

@@ -11,7 +11,25 @@ _SEP = "|||"
 
 
 def parse_ssh_probe(raw: str) -> dict:
-    """Parse the batched SSH probe output into a telemetry dict. Tolerant of blanks."""
+    """Parse the batched SSH probe output into a telemetry dict.
+
+    The probe command (``SSH_PROBE_CMD``) concatenates five fields separated by
+    ``|||``: active core name, uptime, load average, memory info, and firmware
+    timestamp.  Any missing or malformed field is silently coerced to ``None``.
+
+    Args:
+        raw: Raw stdout string returned by running ``SSH_PROBE_CMD`` on the
+            MiSTer over SSH.
+
+    Returns:
+        A dict with the following keys:
+
+        * ``active_core`` (``str | None``) — name from ``/tmp/CORENAME``.
+        * ``uptime_seconds`` (``int | None``) — seconds since last boot.
+        * ``cpu_load_1m`` (``float | None``) — 1-minute load average.
+        * ``memory_used_percent`` (``float | None``) — RAM usage 0–100.
+        * ``firmware_timestamp`` (``int | None``) — mtime of the MiSTer binary.
+    """
     parts = [p.strip() for p in raw.split(_SEP)]
     while len(parts) < 5:
         parts.append("")
@@ -49,7 +67,18 @@ def parse_ssh_probe(raw: str) -> dict:
 
 
 class MisterSSH:
-    """Maintains a persistent asyncssh connection and runs the probe."""
+    """Persistent asyncssh connection for MiSTer telemetry probes.
+
+    Maintains a single SSH connection that is re-established transparently on
+    failure.  SSH telemetry is strictly best-effort: :meth:`async_probe`
+    always returns a dict (possibly empty) and never raises.
+
+    Args:
+        host: IP address or hostname of the MiSTer device.
+        port: SSH port (default ``22``).
+        username: SSH username (default ``"root"``).
+        password: SSH password (often ``"1"`` on stock MiSTer).
+    """
 
     def __init__(self, host: str, port: int, username: str, password: str) -> None:
         self.host = host
@@ -72,7 +101,12 @@ class MisterSSH:
         )
 
     async def async_probe(self) -> dict:
-        """Run the probe; returns {} on any failure (SSH is best-effort)."""
+        """Run the SSH probe command and return parsed telemetry.
+
+        Returns:
+            Telemetry dict as returned by :func:`parse_ssh_probe`, or ``{}``
+            if the SSH connection or command fails.
+        """
         try:
             await self._ensure()
             result = await self._conn.run(SSH_PROBE_CMD, check=False, timeout=10)
@@ -83,6 +117,7 @@ class MisterSSH:
             return {}
 
     async def async_close(self) -> None:
+        """Close the underlying SSH connection if open."""
         if self._conn is not None:
             self._conn.close()
             self._conn = None

{python_mister_fpga-0.1.0 → python_mister_fpga-0.1.2}/src/mister_fpga/websocket.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 
 import asyncio
 import logging
+from collections.abc import Awaitable, Callable
 from dataclasses import replace
 
 import aiohttp
@@ -19,7 +20,32 @@ def apply_ws_message(
     menu_path: str | None,
     index_state: tuple[bool, bool],
 ) -> tuple[MisterStatus, str | None, tuple[bool, bool]]:
-    """Pure reducer: apply one WS text frame to (status, menu_path, index_state)."""
+    """Apply one WebSocket text frame to the current state triple.
+
+    This is a *pure* reducer — it never mutates its arguments.  Pass it every
+    raw text frame received from :class:`MisterWebSocketClient` to keep a
+    local :class:`~mister_fpga.MisterStatus` in sync without polling the REST
+    API.
+
+    Understood prefixes (``prefix:rest``):
+
+    * ``coreRunning`` — updates :attr:`~mister_fpga.MisterStatus.core`.
+    * ``gameRunning`` — updates :attr:`~mister_fpga.MisterStatus.game` and
+      :attr:`~mister_fpga.MisterStatus.game_name`.
+    * ``menuNavigation`` — updates *menu_path*.
+    * ``indexStatus`` — updates *index_state* ``(exists, in_progress)``.
+
+    Args:
+        message: Raw text frame received from the WebSocket.
+        status: Current device-state snapshot.
+        menu_path: Current menu navigation path, or ``None``.
+        index_state: Tuple ``(index_exists, index_in_progress)``.
+
+    Returns:
+        A new ``(status, menu_path, index_state)`` triple reflecting the
+        change encoded in *message*.  Unrecognised prefixes are passed through
+        unchanged.
+    """
     prefix, _, rest = message.partition(":")
     if prefix == "coreRunning":
         core = rest.strip() or None
@@ -48,14 +74,27 @@ def apply_ws_message(
 
 
 class MisterWebSocketClient:
-    """Connects to the mrext Remote WebSocket and invokes a callback per text frame."""
+    """Reconnecting WebSocket client for real-time MiSTer Remote events.
+
+    Connects to the mrext Remote WebSocket endpoint and invokes a callback for
+    every TEXT frame received.  If the connection drops the client waits
+    *reconnect_delay* seconds and reconnects automatically.
+
+    Args:
+        host: IP address or hostname of the MiSTer device.
+        port: mrext Remote port (default ``8182``).
+        session: Optional shared ``aiohttp.ClientSession``.  When ``None`` the
+            client creates and owns its own session.
+        reconnect_delay: Seconds to wait before reconnecting after a
+            connection loss (default ``5``).
+    """
 
     def __init__(
         self,
         host: str,
         port: int = 8182,
         *,
-        session=None,
+        session: aiohttp.ClientSession | None = None,
         reconnect_delay: int = 5,
     ) -> None:
         self.host = host
@@ -67,12 +106,20 @@ class MisterWebSocketClient:
 
     @property
     def url(self) -> str:
+        """Full WebSocket URL derived from *host* and *port*."""
         return f"ws://{self.host}:{self.port}{WS_PATH}"
 
-    async def listen(self, on_message) -> None:
-        """Run the reconnect loop, calling on_message(text) for each TEXT frame.
+    async def listen(
+        self,
+        on_message: Callable[[str], None | Awaitable[None]],
+    ) -> None:
+        """Run the reconnect loop, calling *on_message* for each TEXT frame.
+
+        Blocks until :meth:`stop` is called or the task is cancelled.
+        *on_message* may be a plain function or a coroutine function.
 
-        on_message may be sync or async. Runs until stop() or cancellation.
+        Args:
+            on_message: Callable ``(text: str) -> None | Awaitable``.
         """
         owns = self._session is None
         session = self._session or aiohttp.ClientSession()
@@ -100,4 +147,5 @@ class MisterWebSocketClient:
                 await session.close()
 
     def stop(self) -> None:
+        """Signal the :meth:`listen` loop to exit after the current iteration."""
         self._stop = True

{python_mister_fpga-0.1.0 → python_mister_fpga-0.1.2}/tests/test_client.py

@@ -341,3 +341,10 @@ async def test_send_keyboard_raw(client):
     with aioresponses() as m:
         m.post(f"{BASE}/controls/keyboard-raw/16", status=200)
         await client.async_send_keyboard_raw(16)
+
+
+def test_ssh_defaults_exported():
+    from mister_fpga import DEFAULT_SSH_PORT, DEFAULT_SSH_USERNAME, SSH_PROBE_CMD
+    assert DEFAULT_SSH_PORT == 22
+    assert DEFAULT_SSH_USERNAME == "root"
+    assert "CORENAME" in SSH_PROBE_CMD