Merge remote-tracking branch 'origin/main' into refactor-tests

Author: JakubAndrysek

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.0.8 - 2025-08-20
+
+- feat: add `download()` and `download_file()` methods (#5)
+
+## 0.0.7 - 2025-08-20
+
+- feat: add `read_framebuffer_png_bytes()` and `save_framebuffer_png()` methods (#4)
+
 ## 0.0.6 - 2025-08-17
 
 - feat: add `set_control()`, `read_pin()`, `listen_pin()`, `serial_write()` methods (#1)

src/wokwi_client/client.py

@@ -2,21 +2,20 @@
 #
 # SPDX-License-Identifier: MIT
 
+import base64
 from pathlib import Path
 from typing import Any, Optional, Union
 
 from wokwi_client.framebuffer import (
-    compare_framebuffer_png,
-    framebuffer_png_bytes,
-    framebuffer_read,
+    read_framebuffer_png_bytes,
     save_framebuffer_png,
 )
 
 from .__version__ import get_version
 from .constants import DEFAULT_WS_URL
 from .control import set_control
 from .event_queue import EventQueue
-from .file_ops import download, download_file, upload, upload_file
+from .file_ops import download, upload, upload_file
 from .pins import gpio_list, pin_listen, pin_read
 from .protocol_types import EventMessage, ResponseMessage
 from .serial import monitor_lines, write_serial
@@ -93,17 +92,18 @@ async def upload_file(
         """
         return await upload_file(self._transport, filename, local_path)
 
-    async def download(self, name: str) -> ResponseMessage:
+    async def download(self, name: str) -> bytes:
         """
         Download a file from the simulator.
 
         Args:
             name: The name of the file to download.
 
         Returns:
-            The response message from the server.
+            The downloaded file content as bytes.
         """
-        return await download(self._transport, name)
+        result = await download(self._transport, name)
+        return base64.b64decode(result["result"]["binary"])
 
     async def download_file(self, name: str, local_path: Optional[Path] = None) -> None:
         """
@@ -113,7 +113,12 @@ async def download_file(self, name: str, local_path: Optional[Path] = None) -> N
             name: The name of the file to download.
             local_path: The local path to save the downloaded file. If not provided, uses the name as the path.
         """
-        await download_file(self._transport, name, local_path)
+        if local_path is None:
+            local_path = Path(name)
+
+        result = await self.download(name)
+        with open(local_path, "wb") as f:
+            f.write(result)
 
     async def start_simulation(
         self,
@@ -267,22 +272,10 @@ async def set_control(
         """
         return await set_control(self._transport, part=part, control=control, value=value)
 
-    async def framebuffer_read(self, id: str) -> ResponseMessage:
-        """Read the current framebuffer for the given device id."""
-        return await framebuffer_read(self._transport, id=id)
-
-    async def framebuffer_png_bytes(self, id: str) -> bytes:
+    async def read_framebuffer_png_bytes(self, id: str) -> bytes:
         """Return the current framebuffer as PNG bytes."""
-        return await framebuffer_png_bytes(self._transport, id=id)
+        return await read_framebuffer_png_bytes(self._transport, id=id)
 
     async def save_framebuffer_png(self, id: str, path: Path, overwrite: bool = True) -> Path:
         """Save the current framebuffer as a PNG file."""
         return await save_framebuffer_png(self._transport, id=id, path=path, overwrite=overwrite)
-
-    async def compare_framebuffer_png(
-        self, id: str, reference: Path, save_mismatch: Optional[Path] = None
-    ) -> bool:
-        """Compare the current framebuffer with a reference PNG file."""
-        return await compare_framebuffer_png(
-            self._transport, id=id, reference=reference, save_mismatch=save_mismatch
-        )

src/wokwi_client/file_ops.py

@@ -26,12 +26,3 @@ async def upload(transport: Transport, name: str, content: bytes) -> ResponseMes
 
 async def download(transport: Transport, name: str) -> ResponseMessage:
     return await transport.request("file:download", {"name": name})
-
-
-async def download_file(transport: Transport, name: str, local_path: Optional[Path] = None) -> None:
-    if local_path is None:
-        local_path = Path(name)
-
-    result = await download(transport, name)
-    with open(local_path, "wb") as f:
-        f.write(base64.b64decode(result["result"]["binary"]))

src/wokwi_client/framebuffer.py

@@ -24,14 +24,13 @@
 from .transport import Transport
 
 __all__ = [
-    "framebuffer_read",
-    "framebuffer_png_bytes",
+    "read_framebuffer",
+    "read_framebuffer_png_bytes",
     "save_framebuffer_png",
-    "compare_framebuffer_png",
 ]
 
 
-async def framebuffer_read(transport: Transport, *, id: str) -> ResponseMessage:
+async def read_framebuffer(transport: Transport, *, id: str) -> ResponseMessage:
     """Issue `framebuffer:read` for the given device id and return raw response."""
     return await transport.request("framebuffer:read", {"id": id})
 
@@ -44,9 +43,9 @@ def _extract_png_b64(resp: ResponseMessage) -> str:
     return png_b64
 
 
-async def framebuffer_png_bytes(transport: Transport, *, id: str) -> bytes:
+async def read_framebuffer_png_bytes(transport: Transport, *, id: str) -> bytes:
     """Return decoded PNG bytes for the framebuffer of device `id`."""
-    resp = await framebuffer_read(transport, id=id)
+    resp = await read_framebuffer(transport, id=id)
     return base64.b64decode(_extract_png_b64(resp))
 
 
@@ -64,30 +63,8 @@ async def save_framebuffer_png(
     """
     if path.exists() and not overwrite:
         raise WokwiError(f"File already exists and overwrite=False: {path}")
-    data = await framebuffer_png_bytes(transport, id=id)
+    data = await read_framebuffer_png_bytes(transport, id=id)
     path.parent.mkdir(parents=True, exist_ok=True)
     with open(path, "wb") as f:
         f.write(data)
     return path
-
-
-async def compare_framebuffer_png(
-    transport: Transport, *, id: str, reference: Path, save_mismatch: Path | None = None
-) -> bool:
-    """Compare the current framebuffer PNG with a reference file.
-
-    Performs a byte-for-byte comparison. If different and `save_mismatch` is
-    provided, writes the current framebuffer PNG there.
-
-    Returns True if identical, False otherwise.
-    """
-    if not reference.exists():
-        raise WokwiError(f"Reference image does not exist: {reference}")
-    current = await framebuffer_png_bytes(transport, id=id)
-    ref_bytes = reference.read_bytes()
-    if current == ref_bytes:
-        return True
-    if save_mismatch:
-        save_mismatch.parent.mkdir(parents=True, exist_ok=True)
-        save_mismatch.write_bytes(current)
-    return False