mini-arcade-core 1.2.0__py3-none-any.whl → 1.2.1__py3-none-any.whl

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/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()

{mini_arcade_core-1.2.0.dist-info → mini_arcade_core-1.2.1.dist-info}/METADATA

@@ -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.dist-info → mini_arcade_core-1.2.1.dist-info}/RECORD

@@ -46,8 +46,9 @@ mini_arcade_core/runtime/audio/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5
 mini_arcade_core/runtime/audio/audio_adapter.py,sha256=lnP35txPzSKX1_il0nXcK7RMF5Qp9Qhi9YMh_7LTdPM,588
 mini_arcade_core/runtime/audio/audio_port.py,sha256=jBd9WabN41uK3MHjg_1n4AOw83NivJlGE2m430WZTnk,831
 mini_arcade_core/runtime/capture/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-mini_arcade_core/runtime/capture/capture_adapter.py,sha256=XBtiKw3AS2dzB4QogPm9kjhiQAenS25guX87tg-zK58,4882
+mini_arcade_core/runtime/capture/capture_adapter.py,sha256=T3Ca7qCB4ZtGDLE5iKxSWwStMen4RTWdQEn8Zs48tqk,5447
 mini_arcade_core/runtime/capture/capture_port.py,sha256=niHi0pAo10mC9p73FxFkYBIGLOLRN0PiOvxE4Zgo5fM,1162
+mini_arcade_core/runtime/capture/capture_worker.py,sha256=XAzL28jD8jnGoG3bvsd9yQW5S4Nv7licNJn94QTIzp4,5393
 mini_arcade_core/runtime/context.py,sha256=ONKQryO3KEOOqHaByxCUola07kdjrnvr4WfXwgwTobk,1777
 mini_arcade_core/runtime/file/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 mini_arcade_core/runtime/file/file_adapter.py,sha256=09q7G9Qijml9d4AAjo6HLC1yuoVTjE_7xaT8apT4mk0,523
@@ -86,7 +87,7 @@ mini_arcade_core/utils/__init__.py,sha256=id1C0au8r1oIzGha42xXwnI9ojcU1hxPgto6QS
 mini_arcade_core/utils/deprecated_decorator.py,sha256=yrrW2ZqPskK-4MUTyIrMb465Wc54X2poV53ZQutZWqc,1140
 mini_arcade_core/utils/logging.py,sha256=ygKpey6nikp30PrNDP_yRs8pxPPRbsQ0ivR6LUuEn3Q,6413
 mini_arcade_core/utils/profiler.py,sha256=vLzrxDfAplgKGxpuzk4eFJx4t5DU5M3DQAn6sfS5D_4,8733
-mini_arcade_core-1.2.0.dist-info/METADATA,sha256=PeD3ImQ4FG5bjuYKFdLThR59fOvr-lgOS3OaF1XVRis,8188
-mini_arcade_core-1.2.0.dist-info/WHEEL,sha256=kJCRJT_g0adfAJzTx2GUMmS80rTJIVHRCfG0DQgLq3o,88
-mini_arcade_core-1.2.0.dist-info/licenses/LICENSE,sha256=3lHAuV0584cVS5vAqi2uC6GcsVgxUijvwvtZckyvaZ4,1096
-mini_arcade_core-1.2.0.dist-info/RECORD,,
+mini_arcade_core-1.2.1.dist-info/METADATA,sha256=me0QR43UEolQONEt9HpCqPM-R9Khq6nq9YNa2GcePtw,8188
+mini_arcade_core-1.2.1.dist-info/WHEEL,sha256=kJCRJT_g0adfAJzTx2GUMmS80rTJIVHRCfG0DQgLq3o,88
+mini_arcade_core-1.2.1.dist-info/licenses/LICENSE,sha256=3lHAuV0584cVS5vAqi2uC6GcsVgxUijvwvtZckyvaZ4,1096
+mini_arcade_core-1.2.1.dist-info/RECORD,,