python-mister-fpga 0.1.1__tar.gz → 0.1.3__tar.gz

python_mister_fpga-0.1.3/.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.1 → python_mister_fpga-0.1.3}/.gitignore

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

{python_mister_fpga-0.1.1 → python_mister_fpga-0.1.3}/CHANGELOG.md

@@ -1,5 +1,8 @@
 # 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.
 

{python_mister_fpga-0.1.1 → python_mister_fpga-0.1.3}/PKG-INFO

@@ -1,8 +1,9 @@
 Metadata-Version: 2.4
 Name: python-mister-fpga
-Version: 0.1.1
+Version: 0.1.3
 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.1 → python_mister_fpga-0.1.3}/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.3/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.3/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.3/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.3/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.3/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.1 → python_mister_fpga-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "python-mister-fpga"
-version = "0.1.1"
+version = "0.1.3"
 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.1 → python_mister_fpga-0.1.3}/src/mister_fpga/__init__.py

@@ -6,9 +6,14 @@ 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,
 )
+from .ra import MisterRA, MisterRAError, parse_ra_status
 from .ssh import MisterSSH, parse_ssh_probe
 from .websocket import MisterWebSocketClient, apply_ws_message
 
@@ -16,16 +21,23 @@ __all__ = [
     "MisterClient",
     "MisterStatus",
     "MisterConnectionError",
+    "MisterRA",
+    "MisterRAError",
+    "MisterRAStatus",
     "MisterWebSocketClient",
     "apply_ws_message",
     "MisterSSH",
+    "parse_ra_status",
     "parse_ssh_probe",
     "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.1"
+__version__ = "0.1.3"

{python_mister_fpga-0.1.1 → python_mister_fpga-0.1.3}/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}")