window-grabber 0.1.0__py3-none-win32.whl

window_grabber-0.1.0.data/purelib/window_capture/__init__.py

@@ -0,0 +1,54 @@
+"""Window capture with a typed Python API and isolated, precompiled Rust workers."""
+
+from ._comparison import ChangeOptions
+from ._modes import recommended_capture_mode
+from .monitor import ProcessMonitor, WindowEvent
+from .recording import DirectoryRecorder, record_process
+from .events import CaptureEvent, CaptureEvents
+from ._api import CaptureSession, capture, find_windows, probe
+from .options import (
+    CaptureOptions,
+    ContentOptions,
+    CoordinatorOptions,
+    DesktopOptions,
+    DiagnosticOptions,
+    ImageOptions,
+    PreparedSource,
+    Match,
+    Target,
+    ValidationOptions,
+    WorkerOptions,
+)
+from .results import CapabilityReport, CapturedImage, CaptureError, CaptureResult, CloseReport
+
+__version__ = "0.1.0"
+__all__ = [
+    "recommended_capture_mode",
+    "DirectoryRecorder",
+    "record_process",
+    "ChangeOptions",
+    "ProcessMonitor",
+    "WindowEvent",
+    "CaptureEvent",
+    "CaptureEvents",
+    "capture",
+    "find_windows",
+    "probe",
+    "CaptureSession",
+    "Target",
+    "Match",
+    "PreparedSource",
+    "CaptureOptions",
+    "ContentOptions",
+    "DesktopOptions",
+    "DiagnosticOptions",
+    "ImageOptions",
+    "ValidationOptions",
+    "WorkerOptions",
+    "CoordinatorOptions",
+    "CapturedImage",
+    "CaptureResult",
+    "CaptureError",
+    "CapabilityReport",
+    "CloseReport",
+]

window_grabber-0.1.0.data/purelib/window_capture/__main__.py

@@ -0,0 +1,120 @@
+import argparse
+import json
+
+from . import CaptureOptions, CaptureSession, DesktopOptions, Target, capture, find_windows, probe
+from .results import thaw
+from .recording import DirectoryRecorder, record_process
+from .monitor import ProcessMonitor
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Capture a window using the bundled Rust helper")
+    parser.add_argument("--monitor", action="store_true")
+    parser.add_argument("--interval-seconds", type=float, default=5.0)
+    parser.add_argument("--recording-max-bytes", type=int, default=1024 * 1024 * 1024)
+    parser.add_argument("--probe", action="store_true")
+    parser.add_argument("--find", action="store_true")
+    parser.add_argument("--hwnd", type=lambda x: int(x, 0))
+    parser.add_argument("--x11-window-id", type=lambda x: int(x, 0))
+    parser.add_argument(
+        "--select-window", action="store_true", help="Select a Wayland window interactively"
+    )
+    parser.add_argument("--pid", type=int)
+    parser.add_argument(
+        "--process-name", action="append", help="Repeat to monitor multiple executables"
+    )
+    parser.add_argument("--process-path")
+    parser.add_argument("--window-class")
+    parser.add_argument("--window-title")
+    parser.add_argument("--mode", choices=("isolated", "controlled_desktop"))
+    parser.add_argument("--allow-resize", action="store_true", default=None)
+    parser.add_argument("--desktop", action="store_true", help="Permit temporary desktop changes")
+    parser.add_argument("--separate-owned-popups", action="store_true")
+    parser.add_argument(
+        "--resize-to-fit", action="store_true", help="Permit temporary layout changes"
+    )
+    parser.add_argument("--timeout-ms", type=int, default=2000)
+    parser.add_argument("--output", default="capture.png")
+    args = parser.parse_args()
+    if sum((args.monitor, args.probe, args.find, args.select_window)) > 1:
+        parser.error("Choose only one operation")
+    if args.mode and (args.desktop or args.separate_owned_popups or args.resize_to_fit):
+        parser.error("--mode replaces the advanced desktop flags; use --allow-resize")
+    if args.allow_resize and args.mode != "controlled_desktop":
+        parser.error("--allow-resize requires --mode controlled_desktop")
+    if args.process_name and len(args.process_name) > 1 and not args.monitor:
+        parser.error("Repeated --process-name requires --monitor")
+    if args.probe:
+        report = probe(timeout_ms=args.timeout_ms)
+        print(json.dumps(thaw(report.__dict__), indent=2))
+        return 0
+    options = CaptureOptions(
+        timeout_ms=args.timeout_ms,
+        desktop=DesktopOptions(
+            enabled=args.desktop,
+            separate_owned_popups=args.separate_owned_popups,
+            resize_to_fit=args.resize_to_fit,
+        ),
+    )
+    if args.select_window:
+        with CaptureSession(
+            options=options, mode=args.mode, allow_resize=args.allow_resize
+        ) as session:
+            source = session.select_window()
+            result = session.capture(Target(portal_source=source))
+        print(json.dumps(result.metadata(), indent=2))
+        if result.accepted:
+            result.require_image().save(args.output)
+        return 0 if result.accepted else 1
+    targets = [
+        Target(
+            hwnd=args.hwnd,
+            x11_window_id=args.x11_window_id,
+            pid=args.pid,
+            process_name=name,
+            process_path=args.process_path,
+            window_class=args.window_class,
+            window_title=args.window_title,
+        )
+        for name in (args.process_name or [None])
+    ]
+    target = targets[0]
+    if args.monitor:
+        if args.find or args.hwnd or args.x11_window_id:
+            parser.error("--monitor requires a process selector")
+        if args.output == "capture.png":
+            parser.error("--monitor requires --output DIRECTORY")
+        try:
+            with ProcessMonitor(
+                targets,
+                options=options,
+                allow_desktop_capture=args.desktop,
+                mode=args.mode,
+                allow_resize=args.allow_resize,
+            ) as monitor:
+                record_process(
+                    monitor,
+                    DirectoryRecorder(args.output, max_bytes=args.recording_max_bytes),
+                    interval_seconds=args.interval_seconds,
+                    discovery_timeout_ms=args.timeout_ms,
+                )
+        except KeyboardInterrupt:
+            return 0
+        return 0
+    if args.find:
+        print(json.dumps(thaw(find_windows(target, timeout_ms=args.timeout_ms)), indent=2))
+        return 0
+    result = capture(
+        target,
+        options=options,
+        mode=args.mode,
+        allow_resize=args.allow_resize,
+    )
+    print(json.dumps(result.metadata(), indent=2))
+    if result.accepted:
+        result.require_image().save(args.output)
+    return 0 if result.accepted else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

window_grabber-0.1.0.data/purelib/window_capture/_api.py

@@ -0,0 +1,359 @@
+"""Synchronous Python facade over the precompiled Rust coordinator protocol."""
+
+import os
+import queue
+import threading
+import time
+import uuid
+from typing import Any, Mapping, Optional, Tuple
+
+from ._response import capture_result
+from ._discovery import identity as window_identity
+from ._modes import options_for_mode
+from .events import CaptureEvents
+from ._pool import NativePool
+from . import _transport
+from ._deadline import Failure
+from .options import (
+    BACKENDS,
+    CaptureOptions,
+    CoordinatorOptions,
+    PreparedSource,
+    Target,
+    WorkerOptions,
+    integer,
+    to_wire,
+)
+from .results import (
+    CapabilityReport,
+    CaptureError,
+    CaptureResult,
+    CloseReport,
+    freeze,
+    validate_metadata,
+    validate_capabilities,
+)
+
+
+class CaptureSession:
+    def __init__(
+        self,
+        *,
+        options: Optional[CaptureOptions] = None,
+        workers: Optional[WorkerOptions] = None,
+        coordinator: Optional[CoordinatorOptions] = None,
+        event_capacity: int = 128,
+        mode: Optional[str] = None,
+        allow_resize: Optional[bool] = None,
+    ) -> None:
+        self._pid = os.getpid()
+        self.options = options_for_mode(options, mode, allow_resize)
+        self._mode = mode
+        self._allow_resize = allow_resize
+        self.workers = WorkerOptions() if workers is None else workers
+        if not isinstance(self.options, CaptureOptions) or not isinstance(
+            self.workers, WorkerOptions
+        ):
+            raise ValueError("options and workers require complete typed option objects")
+        if coordinator is not None and not isinstance(coordinator, CoordinatorOptions):
+            raise ValueError("coordinator requires CoordinatorOptions")
+        self.coordinator = coordinator
+        self.events = CaptureEvents(event_capacity)
+        # Slots are released by the I/O worker, not by a timed-out caller.
+        self._pool = NativePool(self.workers.idle_timeout_ms)
+        self._slots = threading.BoundedSemaphore(self.workers.max_workers)
+        self._lock = threading.Lock()
+        self._drained = threading.Condition(self._lock)
+        self._tickets = set()
+        self._closed = False
+        self._recovery = "not_needed"
+
+    def _check_process(self):
+        if self._pid != os.getpid():
+            raise RuntimeError(
+                "Create a new CaptureSession after fork; inherited sessions cannot be used"
+            )
+
+    def __enter__(self):
+        self._check_process()
+        return self
+
+    def __exit__(self, *args):
+        self.close(timeout_ms=0)
+
+    def _request(self, operation, start, timeout_ms, acquire_ms=None, *, _portal=False, **values):
+        self._check_process()
+        integer("timeout_ms", timeout_ms, 1, 86400000)
+        end = start + timeout_ms / 1000.0
+        with self._lock:
+            if self._closed:
+                raise Failure("CANCELLED", "Capture session is closed", "CANCELLED")
+            if not self._slots.acquire(blocking=False):
+                raise Failure("RESOURCE_LIMIT", "Session worker limit reached")
+        ticket = None
+        released = False
+
+        def done():
+            nonlocal released
+            with self._lock:
+                if released:
+                    return
+                released = True
+                self._tickets.discard(ticket)
+                self._slots.release()
+                self._drained.notify_all()
+
+        try:
+            portal = (
+                _portal
+                or operation == "select"
+                or values.get("target", {}).get("portal_source") is not None
+            )
+            command = _transport.portal_command() if portal else _transport.installed_command()
+            request = dict(
+                values,
+                protocol_version=1,
+                operation=operation,
+                workers=to_wire(self.workers),
+                coordinator=to_wire(self.coordinator),
+            )
+
+            ticket = _transport.Ticket(
+                command,
+                request,
+                end,
+                start + (acquire_ms if acquire_ms is not None else timeout_ms) / 1000.0,
+                self.workers.max_buffer_bytes,
+                values.get("options", {}).get("image", {}).get("max_pixels", 40000000),
+                done,
+                self._pool,
+            )
+            with self._lock:
+                if self._closed:
+                    ticket.cancelled.set()
+                self._tickets.add(ticket)
+            _transport.broker().submit(ticket)
+        except BaseException as exc:
+            done()
+            if isinstance(exc, (RuntimeError, OSError)):
+                raise Failure("WORKER_START_FAILED", "Native broker could not start") from None
+            raise
+        try:
+            reply = ticket.answer.get(timeout=max(0, end - time.monotonic()))
+        except queue.Empty:
+            ticket.cancelled.set()
+            raise Failure("DEADLINE_EXCEEDED") from None
+        except BaseException:
+            ticket.cancelled.set()
+            raise
+        if isinstance(reply, Failure):
+            raise reply
+        if time.monotonic() >= end:
+            raise Failure("DEADLINE_EXCEEDED")
+        meta, payload = reply
+        if meta.get("protocol_version") != 1 or meta.get("request_id") != values.get("request_id"):
+            raise Failure("INVALID_BUFFER", "Native response identity/version mismatch")
+        if meta.get("status") == "FAILED":
+            try:
+                validate_metadata(meta)
+            except ValueError:
+                raise Failure("INVALID_BUFFER", "Malformed native failure response") from None
+        if operation in ("find", "probe") and payload:
+            raise Failure("INVALID_BUFFER", "Unexpected discovery or capability payload")
+        return meta, payload
+
+    def capture(self, target: Target, *, options: Optional[CaptureOptions] = None) -> CaptureResult:
+        self._check_process()
+        start = time.monotonic()
+        if not isinstance(target, Target):
+            raise ValueError("target requires Target")
+        effective = (
+            self.options
+            if options is None
+            else options_for_mode(options, self._mode, self._allow_resize)
+        )
+        if not isinstance(effective, CaptureOptions):
+            raise ValueError("options requires a complete CaptureOptions")
+        request_id = uuid.uuid4().hex
+        try:
+            meta, payload = self._request(
+                "capture",
+                start,
+                effective.timeout_ms,
+                effective.effective_acquire_ms,
+                target=to_wire(target),
+                options=to_wire(effective),
+                request_id=request_id,
+            )
+            result = capture_result(meta, payload, effective)
+            if time.monotonic() >= start + effective.timeout_ms / 1000.0:
+                raise Failure("DEADLINE_EXCEEDED")
+        except (Failure, ValueError, TypeError, KeyError) as exc:
+            failure = (
+                exc
+                if isinstance(exc, Failure)
+                else Failure("INVALID_BUFFER", "Malformed capture response")
+            )
+            uncertain = effective.desktop.enabled and failure.reason in (
+                "DEADLINE_EXCEEDED",
+                "WORKER_EXITED",
+                "INVALID_BUFFER",
+            )
+            result = CaptureResult(
+                request_id,
+                failure.status,
+                failure.reason,
+                failure.message,
+                recovery="pending" if uncertain else "not_needed",
+            )
+        from dataclasses import replace
+
+        timing = dict(result.timing, total_ms=(time.monotonic() - start) * 1000)
+        result = replace(result, timing=timing)
+        if result.recovery in ("pending", "failed"):
+            with self._lock:
+                self._recovery = result.recovery
+        self.events._record(result)
+        if not result.accepted and effective.on_failure == "raise":
+            raise CaptureError(result)
+        return result
+
+    def find_windows(
+        self, target: Target, *, timeout_ms: int = 2000
+    ) -> Tuple[Mapping[str, Any], ...]:
+        integer("timeout_ms", timeout_ms)
+        if not isinstance(target, Target):
+            raise ValueError("target requires Target")
+        request_id = uuid.uuid4().hex
+        try:
+            meta, _ = self._request(
+                "find", time.monotonic(), timeout_ms, target=to_wire(target), request_id=request_id
+            )
+            if meta.get("status") == "FAILED":
+                raise Failure(meta["reason"], meta.get("message", ""))
+            windows = meta["windows"]
+            if not isinstance(windows, (list, tuple)) or any(
+                not isinstance(window, Mapping) for window in windows
+            ):
+                raise ValueError("Invalid window list")
+            for window in windows:
+                window_identity(window)
+            return tuple(freeze(window) for window in windows)
+        except (Failure, KeyError, TypeError, ValueError) as exc:
+            if not isinstance(exc, Failure):
+                exc = Failure("INVALID_BUFFER", "Malformed window discovery response")
+            raise CaptureError(
+                CaptureResult(request_id, "FAILED", exc.reason, exc.message)
+            ) from None
+
+    def prepare(self, *, timeout_ms: int = 5000) -> CapabilityReport:
+        return self._probe(timeout_ms)
+
+    def _probe(self, timeout_ms):
+        integer("timeout_ms", timeout_ms)
+        start = time.monotonic()
+        try:
+            meta, _ = self._request("probe", start, timeout_ms, request_id=uuid.uuid4().hex)
+            if meta.get("status") == "FAILED":
+                raise Failure(meta["reason"], meta.get("message", ""))
+            validate_capabilities(meta["backends"], meta.get("environment", {}))
+            # Optional Linux libraries live in a separate executable. Probe it
+            # under the original deadline and never open a permission dialog.
+            try:
+                _transport.portal_command()
+            except Failure:
+                pass
+            else:
+                try:
+                    portal, _ = self._request(
+                        "probe", start, timeout_ms, _portal=True, request_id=uuid.uuid4().hex
+                    )
+                    descriptor = portal["backends"]["wayland_portal"]
+                    validate_capabilities({"wayland_portal": descriptor}, {})
+                    meta["backends"]["wayland_portal"] = descriptor
+                except (Failure, KeyError, TypeError, ValueError) as exc:
+                    meta["backends"]["wayland_portal"] = {
+                        "available": False,
+                        "reason": exc.reason if isinstance(exc, Failure) else "INVALID_BUFFER",
+                    }
+            return CapabilityReport(meta["backends"], meta.get("environment", {}))
+        except (Failure, KeyError, TypeError, ValueError) as exc:
+            if not isinstance(exc, Failure):
+                exc = Failure("INVALID_BUFFER", "Malformed capability response")
+            return CapabilityReport(
+                {b: {"available": False, "reason": exc.reason} for b in BACKENDS},
+                {"reason": exc.reason, "message": exc.message},
+            )
+
+    def select_window(self, *, timeout_ms: Optional[int] = None) -> PreparedSource:
+        if timeout_ms is not None:
+            integer("timeout_ms", timeout_ms, 1, 86400000)
+        request_id = uuid.uuid4().hex
+        try:
+            meta, _ = self._request(
+                "select",
+                time.monotonic(),
+                timeout_ms or 86400000,
+                request_id=request_id,
+                options=to_wire(self.options),
+            )
+            if meta.get("status") == "FAILED":
+                raise Failure(meta["reason"], meta.get("message", ""))
+            return PreparedSource(**meta["source"])
+        except (Failure, ValueError, TypeError, KeyError) as exc:
+            failure = (
+                exc
+                if isinstance(exc, Failure)
+                else Failure("INVALID_BUFFER", "Invalid source response")
+            )
+            raise CaptureError(
+                CaptureResult(request_id, "FAILED", failure.reason, failure.message)
+            ) from None
+
+    def close(self, *, timeout_ms: int = 1000) -> CloseReport:
+        self._check_process()
+        integer("timeout_ms", timeout_ms, 0, 86400000)
+        end = time.monotonic() + timeout_ms / 1000.0
+        with self._drained:
+            self._closed = True
+            self._pool.close()
+            for ticket in self._tickets:
+                ticket.cancelled.set()
+                if ticket.request.get("options", {}).get("desktop", {}).get("enabled"):
+                    self._recovery = "pending"
+            # Watchdog owns teardown. A bounded wait releases the session lock.
+            while self._tickets:
+                remaining = end - time.monotonic()
+                if remaining <= 0:
+                    break
+                self._drained.wait(timeout=remaining)
+            return CloseReport(True, self._recovery)
+
+
+def capture(
+    target: Target,
+    *,
+    options: Optional[CaptureOptions] = None,
+    mode: Optional[str] = None,
+    allow_resize: Optional[bool] = None,
+) -> CaptureResult:
+    with CaptureSession(options=options, mode=mode, allow_resize=allow_resize) as session:
+        return session.capture(target)
+
+
+def find_windows(target: Target, *, timeout_ms: int = 2000) -> Tuple[Mapping[str, Any], ...]:
+    with CaptureSession() as session:
+        return session.find_windows(target, timeout_ms=timeout_ms)
+
+
+def probe(*, timeout_ms: int = 2000, check_workers: bool = True) -> CapabilityReport:
+    integer("timeout_ms", timeout_ms)
+    if type(check_workers) is not bool:
+        raise ValueError("check_workers must be a bool")
+    if not check_workers:
+        return CapabilityReport({b: {"available": None, "reason": "NOT_PROBED"} for b in BACKENDS})
+    with CaptureSession() as session:
+        return session._probe(timeout_ms)
+
+
+_capture_result = capture_result

window_grabber-0.1.0.data/purelib/window_capture/_comparison.py

@@ -0,0 +1,117 @@
+"""Bounded decoding of our native PNG output and configurable pixel comparison."""
+
+from dataclasses import dataclass, field
+import struct
+import zlib
+
+from .options import integer
+from .results import CapturedImage
+
+
+@dataclass(frozen=True)
+class ChangeOptions:
+    """A pixel counts when any RGBA channel differs by more than the tolerance."""
+
+    channel_tolerance: int = 3
+    min_changed_pixels: int = 1
+
+    def __post_init__(self):
+        integer("channel_tolerance", self.channel_tolerance, 0, 255)
+        integer("min_changed_pixels", self.min_changed_pixels)
+
+
+@dataclass(frozen=True)
+class Baseline:
+    width: int
+    height: int
+    color_space: str
+    alpha: str
+    pixels: bytes = field(repr=False)
+
+
+def decode(image: CapturedImage) -> Baseline:
+    integer("image.width", image.width, 1, 0xFFFFFFFF)
+    integer("image.height", image.height, 1, 0xFFFFFFFF)
+    length = image.width * image.height * 4
+    if image.format == "rgba":
+        if len(image.data) != length:
+            raise ValueError("RGBA dimensions do not match pixels")
+        pixels = image.data
+    elif image.format == "png":
+        data = image.data
+        if data[:8] != b"\x89PNG\r\n\x1a\n":
+            raise ValueError("Invalid PNG signature")
+        offset, compressed, header, ended = 8, bytearray(), False, False
+        while offset + 12 <= len(data):
+            size = struct.unpack_from(">I", data, offset)[0]
+            kind = data[offset + 4 : offset + 8]
+            stop = offset + 8 + size
+            if stop + 4 > len(data):
+                raise ValueError("Truncated PNG chunk")
+            body = data[offset + 8 : stop]
+            if zlib.crc32(kind + body) & 0xFFFFFFFF != struct.unpack_from(">I", data, stop)[0]:
+                raise ValueError("PNG checksum mismatch")
+            if not header:
+                expected = struct.pack(">IIBBBBB", image.width, image.height, 8, 6, 0, 0, 0)
+                if kind != b"IHDR" or body != expected:
+                    raise ValueError("Expected native RGBA8 PNG")
+                header = True
+            elif kind == b"IDAT":
+                compressed.extend(body)
+            elif kind == b"IEND":
+                if body or stop + 4 != len(data):
+                    raise ValueError("Invalid PNG ending")
+                ended = True
+                break
+            elif kind != b"sRGB" or body != b"\x00":
+                raise ValueError("Unexpected native PNG chunk")
+            offset = stop + 4
+        if not ended:
+            raise ValueError("Missing PNG ending")
+        decoder = zlib.decompressobj()
+        row_size = image.width * 4 + 1
+        expected_size = row_size * image.height
+        try:
+            raw = decoder.decompress(compressed, expected_size + 1)
+        except zlib.error as error:
+            raise ValueError("Invalid PNG compressed pixels") from error
+        if (
+            len(raw) != expected_size
+            or not decoder.eof
+            or decoder.unused_data
+            or decoder.unconsumed_tail
+        ):
+            raise ValueError("PNG decompression exceeds dimensions or is incomplete")
+        # The native encoder deliberately emits unfiltered rows. Reject a new
+        # encoding contract instead of interpreting filtered bytes as pixels.
+        if any(raw[y * row_size] != 0 for y in range(image.height)):
+            raise ValueError("Unsupported native PNG row filter")
+        pixels = b"".join(raw[y * row_size + 1 : (y + 1) * row_size] for y in range(image.height))
+    else:
+        raise ValueError("Unsupported image format")
+    return Baseline(image.width, image.height, image.color_space, image.alpha, pixels)
+
+
+def changed(previous: Baseline, current: Baseline, options: ChangeOptions) -> bool:
+    if (previous.width, previous.height, previous.color_space, previous.alpha) != (
+        current.width,
+        current.height,
+        current.color_space,
+        current.alpha,
+    ):
+        return True
+    if previous.pixels == current.pixels:
+        return False
+    count = 0
+    # Compare packed pixels first; identical pixels need no Python channel loop.
+    before = memoryview(previous.pixels).cast("I")
+    after = memoryview(current.pixels).cast("I")
+    for a, b in zip(before, after):
+        if a != b and any(
+            abs(((a >> shift) & 255) - ((b >> shift) & 255)) > options.channel_tolerance
+            for shift in (0, 8, 16, 24)
+        ):
+            count += 1
+            if count >= options.min_changed_pixels:
+                return True
+    return False

window_grabber-0.1.0.data/purelib/window_capture/_deadline.py

@@ -0,0 +1,25 @@
+import time
+
+
+class Failure(Exception):
+    def __init__(self, reason, message="", status="FAILED"):
+        self.reason = reason
+        self.message = message or reason.replace("_", " ").lower()
+        self.status = status
+        super().__init__(self.message)
+
+
+class Deadline:
+    def __init__(self, end, clock=time.monotonic):
+        self.end = end
+        self.clock = clock
+
+    def remaining(self):
+        return max(0.0, self.end - self.clock())
+
+    def check(self, reason="DEADLINE_EXCEEDED"):
+        if self.remaining() <= 0:
+            raise Failure(reason)
+
+    def cap(self, milliseconds):
+        return Deadline(min(self.end, self.clock() + milliseconds / 1000), self.clock)