mini-arcade-core 1.2.0__tar.gz → 1.2.1__tar.gz

{mini_arcade_core-1.2.0 → mini_arcade_core-1.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mini-arcade-core
-Version: 1.2.0
+Version: 1.2.1
 Summary: Tiny scene-based game loop core for small arcade games.
 License: Copyright (c) 2025 Santiago Rincón
            

{mini_arcade_core-1.2.0 → mini_arcade_core-1.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [project]
 name = "mini-arcade-core"
-version = "1.2.0"
+version = "1.2.1"
 description = "Tiny scene-based game loop core for small arcade games."
 authors = [
     { name = "Santiago Rincon", email = "rincores@gmail.com" },

{mini_arcade_core-1.2.0 → mini_arcade_core-1.2.1}/src/mini_arcade_core/runtime/capture/capture_adapter.py

@@ -8,11 +8,16 @@ from dataclasses import dataclass
 from datetime import datetime
 from pathlib import Path
 from typing import Optional
+from uuid import uuid4
 
 from PIL import Image
 
 from mini_arcade_core.backend import Backend
 from mini_arcade_core.runtime.capture.capture_port import CapturePort
+from mini_arcade_core.runtime.capture.capture_worker import (
+    CaptureJob,
+    CaptureWorker,
+)
 from mini_arcade_core.utils import logger
 
 
@@ -87,9 +92,12 @@ class CaptureAdapter(CapturePort):
         self,
         backend: Backend,
         path_builder: Optional[CapturePathBuilder] = None,
+        worker: Optional[CaptureWorker] = None,
     ):
         self.backend = backend
         self.path_builder = path_builder or CapturePathBuilder()
+        self.worker = worker or CaptureWorker()
+        self.worker.start()
 
     def _bmp_to_image(self, bmp_path: str, out_path: str):
         img = Image.open(bmp_path)
@@ -98,23 +106,27 @@ class CaptureAdapter(CapturePort):
     def screenshot(self, label: str | None = None) -> str:
         label = label or "shot"
         out_path = self.path_builder.build(label)
-        out_path.parent.mkdir(parents=True, exist_ok=True)
+        logger.critical(f"Capturing screenshot to: {out_path}")
 
-        # If backend only saves BMP, capture to a temp bmp next to output
-        bmp_path = out_path.with_suffix(".bmp")
+        # temp BMP next to output (unique)
+        bmp_path = out_path.with_suffix(f".{uuid4().hex}.bmp")
+        bmp_path.parent.mkdir(parents=True, exist_ok=True)
 
-        self.backend.capture.bmp(str(bmp_path))
-        if not bmp_path.exists():
-            raise RuntimeError("Backend capture.bmp did not create BMP file")
+        ok_native = self.backend.capture.bmp(str(bmp_path))  # returns bool
+        if not ok_native or not bmp_path.exists():
+            raise RuntimeError("Backend capture.bmp failed to create BMP file")
 
-        self._bmp_to_image(str(bmp_path), str(out_path))
-        try:
-            bmp_path.unlink(missing_ok=True)
-        # Justification: Various exceptions can occur on file deletion
-        # pylint: disable=broad-exception-caught
-        except Exception:
-            logger.warning(f"Failed to delete temporary BMP file: {bmp_path}")
-        # pylint: enable=broad-exception-caught
+        job_id = uuid4().hex
+        ok = self.worker.enqueue(
+            CaptureJob(job_id=job_id, out_path=out_path, bmp_path=bmp_path)
+        )
+        if not ok:
+            logger.warning("Screenshot dropped: capture queue full")
+            # optional: cleanup temp bmp since we won't process it
+            try:
+                bmp_path.unlink(missing_ok=True)
+            except Exception:  # pylint: disable=broad-exception-caught
+                pass
 
         return str(out_path)
 
@@ -127,24 +139,27 @@ class CaptureAdapter(CapturePort):
     def screenshot_sim(
         self, run_id: str, frame_index: int, label: str = "frame"
     ) -> str:
-        """Screenshot for simulation frames."""
         out_path = self.path_builder.build_sim(run_id, frame_index, label)
-        out_path.parent.mkdir(parents=True, exist_ok=True)
-
-        bmp_path = out_path.with_suffix(".bmp")
-        self.backend.capture.bmp(str(bmp_path))
 
-        if not bmp_path.exists():
-            raise RuntimeError("Backend capture.bmp did not create BMP file")
+        bmp_path = out_path.with_suffix(f".{uuid4().hex}.bmp")
+        bmp_path.parent.mkdir(parents=True, exist_ok=True)
 
-        self._bmp_to_image(str(bmp_path), str(out_path))
+        ok_native = self.backend.capture.bmp(str(bmp_path))
+        if not ok_native or not bmp_path.exists():
+            raise RuntimeError("Backend capture.bmp failed to create BMP file")
 
-        try:
-            bmp_path.unlink(missing_ok=True)
-        # Justification: Various exceptions can occur on file deletion
-        # pylint: disable=broad-exception-caught
-        except Exception:
-            logger.warning(f"Failed to delete temporary BMP file: {bmp_path}")
-        # pylint: enable=broad-exception-caught
+        job_id = f"{run_id}:{frame_index}"
+        ok = self.worker.enqueue(
+            CaptureJob(job_id=job_id, out_path=out_path, bmp_path=bmp_path)
+        )
+        if not ok:
+            logger.warning("Sim screenshot dropped: capture queue full")
+            try:
+                bmp_path.unlink(missing_ok=True)
+            # Justification: Broad exception catch for cleanup
+            # pylint: disable=broad-exception-caught
+            except Exception:
+                pass
+            # pylint: enable=broad-exception-caught
 
         return str(out_path)

mini_arcade_core-1.2.1/src/mini_arcade_core/runtime/capture/capture_worker.py

@@ -0,0 +1,174 @@
+"""
+Capture worker thread for saving screenshots.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from queue import Empty, Queue
+from threading import Event, Thread
+from typing import Callable, Optional
+
+from PIL import Image
+
+from mini_arcade_core.utils import logger
+
+
+@dataclass(frozen=True)
+class CaptureJob:
+    """
+    Job representing a screenshot to be saved.
+
+    :ivar job_id (str): Unique identifier for the capture job.
+    :ivar out_path (Path): Destination path for the saved screenshot.
+    :ivar bmp_path (Path): Temporary path of the bitmap image to be saved.
+    """
+
+    job_id: str
+    out_path: Path
+    bmp_path: Path  # <-- file-based now
+
+
+@dataclass(frozen=True)
+class CaptureResult:
+    """
+    Result of a completed capture job.
+
+    :ivar job_id (str): Unique identifier for the capture job.
+    :ivar out_path (Path): Destination path where the screenshot was saved.
+    :ivar ok (bool): Whether the capture was successful.
+    :ivar error (Optional[str]): Error message if the capture failed.
+    """
+
+    job_id: str
+    out_path: Path
+    ok: bool
+    error: str | None = None
+
+
+@dataclass
+class WorkerConfig:
+    """
+    Configuration options for the CaptureWorker.
+
+    :ivar queue_size (int): Maximum number of jobs to queue.
+    :ivar on_done (Optional[Callable[[CaptureResult], None]]):
+        Optional callback invoked when a job is done.
+    :ivar name (str): Name of the worker thread.
+    :ivar daemon (bool): Whether the thread is a daemon thread.
+    :ivar delete_temp (bool): Whether to delete temporary bitmap files after saving.
+    """
+
+    queue_size: int = 64
+    on_done: Optional[Callable[[CaptureResult], None]] = None
+    name: str = "capture-worker"
+    daemon: bool = True
+    delete_temp: bool = True
+
+
+class CaptureWorker:
+    """Capture worker thread for saving screenshots asynchronously."""
+
+    def __init__(
+        self,
+        worker_config: WorkerConfig | None = None,
+    ):
+        """
+        :param queue_size: Maximum number of jobs to queue.
+        :type queue_size: int
+        :param on_done: Optional callback invoked when a job is done.
+        :type on_done: Optional[Callable[[CaptureResult], None]]
+        :param name: Name of the worker thread.
+        :type name: str
+        :param daemon: Whether the thread is a daemon thread.
+        :type daemon: bool
+        :param delete_temp: Whether to delete temporary bitmap files after saving.
+        :type delete_temp: bool
+        """
+        if worker_config is None:
+            worker_config = WorkerConfig()
+        self._q: Queue[CaptureJob] = Queue(maxsize=worker_config.queue_size)
+        self._stop = Event()
+        self._thread = Thread(
+            target=self._run,
+            name=worker_config.name,
+            daemon=worker_config.daemon,
+        )
+        self._on_done = worker_config.on_done
+        self._delete_temp = worker_config.delete_temp
+
+    def start(self):
+        """Start the capture worker thread."""
+        if self._thread.is_alive():
+            return
+        self._stop.clear()
+        self._thread.start()
+
+    def stop(self):
+        """Stop the capture worker thread."""
+        self._stop.set()
+        if self._thread.is_alive():
+            self._thread.join(timeout=2.0)
+
+    def enqueue(self, job: CaptureJob) -> bool:
+        """
+        Enqueue a capture job.
+
+        :param job: CaptureJob to enqueue.
+        :type job: CaptureJob
+        :return: True if the job was enqueued successfully, False otherwise.
+        :rtype: bool
+        """
+        if self._stop.is_set():
+            return False
+        try:
+            self._q.put_nowait(job)
+            return True
+        # Justification: Queue.put_nowait can raise a broad exception
+        # pylint: disable=broad-exception-caught
+        except Exception:
+            return False
+        # pylint: enable=broad-exception-caught
+
+    def _run(self):
+        while not self._stop.is_set():
+            try:
+                job = self._q.get(timeout=0.1)
+            except Empty:
+                continue
+
+            try:
+                job.out_path.parent.mkdir(parents=True, exist_ok=True)
+
+                img = Image.open(str(job.bmp_path))
+                img.save(str(job.out_path))
+
+                if self._delete_temp:
+                    try:
+                        job.bmp_path.unlink(missing_ok=True)
+                    except Exception:  # pylint: disable=broad-exception-caught
+                        logger.warning(
+                            f"Failed to delete temp bmp: {job.bmp_path}"
+                        )
+
+                res = CaptureResult(
+                    job_id=job.job_id, out_path=job.out_path, ok=True
+                )
+
+            except Exception as exc:  # pylint: disable=broad-exception-caught
+                logger.exception("CaptureWorker failed to save screenshot")
+                res = CaptureResult(
+                    job_id=job.job_id,
+                    out_path=job.out_path,
+                    ok=False,
+                    error=str(exc),
+                )
+
+            if self._on_done:
+                try:
+                    self._on_done(res)
+                except Exception:  # pylint: disable=broad-exception-caught
+                    logger.warning("CaptureWorker on_done callback failed")
+
+            self._q.task_done()