VirtualDesktop 1.6.5__py3-none-win_amd64.whl

VirtualDesktop/__init__.py

@@ -0,0 +1,152 @@
+"""``VirtualDesktop`` 鈥?an offscreen window workstation for Windows.
+
+The public surface is deliberately small:
+
+* :class:`~VirtualDesktop.session.OffscreenSession` 鈥?mount, capture, restore.
+* :func:`~VirtualDesktop.session.probe_environment` 鈥?diagnostics without side effects.
+* :class:`~VirtualDesktop.driver.DriverInstaller` 鈥?explicit driver control.
+* :mod:`VirtualDesktop.errors` 鈥?every exception, each with a ``code`` and a ``hint``.
+
+Typical use::
+
+    from VirtualDesktop import OffscreenSession
+
+    with OffscreenSession(target_window_title="WeChat") as session:
+        session.mount()
+        frame = session.capture()          # PIL image
+        frame.image.save("wechat.png")
+
+Nothing is installed until ``mount()`` actually needs a virtual display, and nothing is
+moved until a target window has been found, so a failed call leaves the machine as it was.
+"""
+
+from __future__ import annotations
+
+from ._log import enable_debug_logging, get_logger
+from ._winapi import (
+    IS_WINDOWS,
+    MonitorInfo,
+    enumerate_monitors,
+    is_admin,
+    list_windows,
+    select_virtual_monitor,
+)
+from .capture import DEFAULT_METHODS, CaptureEngine, Frame, analyze_image
+from .config import DriverConfig, SessionConfig
+from .desktop import DesktopBinding, current_desktop_name, ensure_default_desktop
+from .driver import DriverInstaller, InstallReport, virtual_display_present
+from .errors import (
+    AmbiguousWindowError,
+    CaptureError,
+    ConfigError,
+    DesktopBindError,
+    DownloadError,
+    DriverInstallError,
+    DriverNotFoundError,
+    DriverVerificationError,
+    ElevationDenied,
+    ElevationRequired,
+    ExtractionError,
+    IntegrityError,
+    MissingDependencyError,
+    OffscreenMountError,
+    SessionStateError,
+    UnsupportedPlatformError,
+    WindowMountError,
+    WindowNotFoundError,
+)
+from .manifest import load_manifest
+from .session import OffscreenSession, probe_environment
+from .desktop_session import DesktopProcess, VirtualDesktop, current_desktop_name
+from .window import WindowMounter, WindowRecord, find_window, window_diagnostics
+from .workspace import SHARED, VirtualWorkspace, WorkspaceWindow
+from .agent import AgentProcess, AgentSession
+from .display_setup import configure_virtual_display, current_primary_dpi, current_primary_size
+from .record import (
+    GIF_FORMATS,
+    IMAGE_FORMATS,
+    VIDEO_FORMATS,
+    Recorder,
+    RecordingReport,
+    record_stream,
+    supported_formats,
+)
+
+__version__ = "1.6.4"
+
+__all__ = [
+    "__version__",
+    # session
+    "OffscreenSession",
+    "probe_environment",
+    # drivers
+    "DriverInstaller",
+    "InstallReport",
+    "virtual_display_present",
+    "load_manifest",
+    # windows and displays
+    "WindowMounter",
+    "WindowRecord",
+    "find_window",
+    "window_diagnostics",
+    "enumerate_monitors",
+    "select_virtual_monitor",
+    "MonitorInfo",
+    "list_windows",
+    "ensure_default_desktop",
+    "current_desktop_name",
+    "DesktopBinding",
+    # private virtual desktop (no admin, no driver)
+    "VirtualDesktop",
+    "DesktopProcess",
+    # multi-window virtual-display workspace (externally controllable)
+    "VirtualWorkspace",
+    "WorkspaceWindow",
+    "SHARED",
+    # in-desktop agent (for isolated workspaces / private desktops)
+    "AgentSession",
+    "AgentProcess",
+    # virtual display geometry
+    "configure_virtual_display",
+    "current_primary_size",
+    "current_primary_dpi",
+    # capture
+    "CaptureEngine",
+    "Frame",
+    "analyze_image",
+    "DEFAULT_METHODS",
+    # recording
+    "Recorder",
+    "RecordingReport",
+    "record_stream",
+    "supported_formats",
+    "VIDEO_FORMATS",
+    "GIF_FORMATS",
+    "IMAGE_FORMATS",
+    # configuration
+    "DriverConfig",
+    "SessionConfig",
+    # platform helpers
+    "IS_WINDOWS",
+    "is_admin",
+    "enable_debug_logging",
+    # errors
+    "OffscreenMountError",
+    "UnsupportedPlatformError",
+    "MissingDependencyError",
+    "ConfigError",
+    "IntegrityError",
+    "DownloadError",
+    "ExtractionError",
+    "ElevationRequired",
+    "ElevationDenied",
+    "DriverInstallError",
+    "DriverNotFoundError",
+    "DriverVerificationError",
+    "DesktopBindError",
+    "WindowNotFoundError",
+    "AmbiguousWindowError",
+    "WindowMountError",
+    "CaptureError",
+    "SessionStateError",
+]

VirtualDesktop/__main__.py

@@ -0,0 +1,10 @@
+"""``python -m VirtualDesktop`` entry point (also used by the elevated helper)."""
+
+from __future__ import annotations
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

VirtualDesktop/_bundle.py

@@ -0,0 +1,369 @@
+"""Managed on-disk layout for the extracted driver package and the nefcon tool.
+
+```
+<cache>/                      (per-user, see VIRTUALDESKTOP_CACHE_DIR)
+  VirtualDisplayDriver-x86.Driver.Only.zip     verified artifact
+  x64/nefconw.exe + x64/nefconc.exe            extracted tool tree
+  driver/vdd_mtt/                              extracted driver package
+    .VirtualDesktop.json                      install marker (version + digest)
+    VirtualDisplayDriver/MttVDD.inf
+    VirtualDisplayDriver/vdd_settings.xml
+```
+
+The marker file records the digest the tree was extracted from, so a manifest bump (new
+driver release) automatically invalidates and re-extracts the tree instead of silently
+running a stale driver.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import sys
+import time
+import uuid
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Optional, Sequence, Tuple
+
+from ._download import default_cache_dir, download_artifact, extract_archive, sha256_of
+from ._log import get_logger
+from .errors import ConfigError, ExtractionError, IntegrityError
+from .manifest import Artifact, DriverSpec, Manifest, ToolSpec
+
+log = get_logger("bundle")
+
+__all__ = [
+    "MARKER_NAME",
+    "DriverBundle",
+    "BundleManager",
+    "driver_spec_for_arch",
+    "tool_executable",
+]
+
+MARKER_NAME = ".VirtualDesktop.json"
+_MARKER_SCHEMA = 1
+
+
+def machine_arch() -> str:
+    """Return ``x64``, ``arm64`` or ``x86`` for the machine class."""
+    import platform
+
+    machine = (platform.machine() or "").lower()
+    if machine in ("arm64", "aarch64"):
+        return "arm64"
+    if machine in ("x86", "i386", "i686"):
+        return "x86"
+    # PROCESSOR_ARCHITEW6432 tells a 32-bit Python on 64-bit Windows the real arch.
+    env = (os.environ.get("PROCESSOR_ARCHITEW6432") or "").lower()
+    if env in ("amd64", "x86"):
+        return "x64"
+    return "x64"
+
+
+def driver_spec_for_arch(manifest: Manifest, name: Optional[str] = None) -> DriverSpec:
+    """Pick the driver variant matching the current machine architecture."""
+    base = manifest.driver(name)
+    if machine_arch() != "arm64":
+        return base
+    arm = manifest.drivers.get(f"{base.name}_arm64")
+    if arm is None:
+        log.warning("no ARM64 variant of %s in the manifest; using the default build", base.name)
+        return base
+    log.info("ARM64 Windows detected; using driver variant %s", arm.name)
+    return arm
+
+
+def tool_executable(spec: ToolSpec, root: Path) -> Path:
+    """Resolve a tool executable inside its extracted tree, tolerating arch differences.
+
+    ``nefcon`` ships ``x64/``, ``x86/`` and ``ARM64/`` trees.  The manifest points at the
+    x64 build because that is what runs on both x64 and (under emulation) ARM64 Windows,
+    but if the declared path is missing we fall back to any sibling build rather than
+    failing with a bare "file not found".
+    """
+    declared = root / Path(spec.executable)
+    if declared.is_file():
+        return declared
+    name = Path(spec.executable).name
+    candidates = sorted(root.rglob(name))
+    if candidates:
+        log.debug("using %s instead of the declared %s", candidates[0], declared)
+        return candidates[0]
+    raise ConfigError(
+        f"{name} was not found under {root}",
+        code="tool-executable-missing",
+        details={"declared": str(declared)},
+    )
+
+
+def _read_marker(path: Path) -> Optional[Dict[str, Any]]:
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    if not isinstance(data, dict) or data.get("schema") != _MARKER_SCHEMA:
+        return None
+    return data
+
+
+def _write_marker(path: Path, payload: Dict[str, Any]) -> None:
+    tmp = path.with_suffix(path.suffix + f".{uuid.uuid4().hex[:8]}.tmp")
+    tmp.parent.mkdir(parents=True, exist_ok=True)
+    tmp.write_text(json.dumps(payload, indent=2, sort_keys=True), encoding="utf-8")
+    os.replace(tmp, path)
+
+
+@dataclass
+class DriverBundle:
+    """A verified, extracted driver package ready to be handed to the installer."""
+
+    spec: DriverSpec
+    root: Path
+    inf_path: Path
+    settings_path: Optional[Path] = None
+    from_cache: bool = False
+
+    @property
+    def driver_dir(self) -> Path:
+        return self.inf_path.parent
+
+    def files(self) -> List[Path]:
+        return sorted(p for p in self.driver_dir.iterdir() if p.is_file())
+
+    def to_dict(self) -> dict:
+        return {
+            "driver": self.spec.name,
+            "version": self.spec.version,
+            "root": str(self.root),
+            "inf": str(self.inf_path),
+            "settings": str(self.settings_path) if self.settings_path else None,
+            "from_cache": self.from_cache,
+        }
+
+
+class BundleManager:
+    """Prepares (and caches) the driver tree and tool trees under one cache root."""
+
+    def __init__(self, cache_dir: Optional[os.PathLike] = None):
+        self.cache_dir = Path(cache_dir) if cache_dir else default_cache_dir()
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+
+    def _mirrors(self) -> Tuple[str, ...]:
+        """Extra download URL prefixes for this environment.
+
+        ``VIRTUALDESKTOP_GITHUB_MIRRORS`` is the escape hatch for networks where github.com is slow
+        or blocked and the built-in accelerators in the manifest are not enough (an internal
+        mirror, a corporate proxy, a different accelerator).  Read once per download rather than
+        cached so a long-lived process picks up a change.  Each entry is either a full URL or a
+        prefix ending in ``/`` or ``?``; either way the digest is verified afterwards.
+        """
+        raw = os.environ.get("VIRTUALDESKTOP_GITHUB_MIRRORS", "")
+        return tuple(item.strip() for item in raw.split(",") if item.strip())
+
+    # -- driver ---------------------------------------------------------------------
+    @property
+    def driver_root(self) -> Path:
+        return self.cache_dir / "driver"
+
+    def prepare_driver(
+        self,
+        spec: DriverSpec,
+        *,
+        settings_file: Optional[os.PathLike] = None,
+        force: bool = False,
+        progress=None,
+    ) -> DriverBundle:
+        """Download (if needed), verify, extract and return the driver package."""
+        target = self.driver_root / spec.name
+        inf_path = target / Path(spec.inf_member)
+        marker = target / MARKER_NAME
+        existing = _read_marker(marker) if not force else None
+        if existing and existing.get("artifact_sha256") == spec.artifact.sha256 and inf_path.is_file():
+            log.debug("driver bundle %s already extracted from %s", spec.name, existing.get("version"))
+            settings = target / Path(spec.settings_member) if spec.settings_member else None
+            return DriverBundle(
+                spec=spec,
+                root=target,
+                inf_path=inf_path,
+                settings_path=settings if settings and settings.is_file() else None,
+                from_cache=True,
+            )
+
+        archive = download_artifact(
+            spec.artifact,
+            cache_dir=self.cache_dir,
+            progress=progress,
+            mirror_extra=self._mirrors(),
+        )
+        # Defence in depth: re-verify the artifact at the bundle boundary, so even a
+        # swapped-out downloader (or a file dropped into the cache between the two calls)
+        # cannot turn into an unverified driver tree.
+        actual = sha256_of(archive)
+        if actual != spec.artifact.sha256:
+            from ._download import _quarantine
+
+            _quarantine(archive, reason="bundle digest mismatch", dest_dir=self.cache_dir / "quarantine")
+            raise IntegrityError(
+                f"{archive.name} does not match the pinned SHA-256 at the bundle boundary",
+                code="digest-mismatch",
+                details={"expected": spec.artifact.sha256, "actual": actual},
+            )
+        staging = self.driver_root / f".{spec.name}.staging.{uuid.uuid4().hex[:8]}"
+        if staging.exists():  # pragma: no cover - defensive
+            shutil.rmtree(staging, ignore_errors=True)
+        try:
+            extract_archive(
+                archive,
+                staging,
+                strip_components=spec.artifact.strip_components,
+                members=spec.artifact.members,
+            )
+            if not (staging / Path(spec.inf_member)).is_file():
+                raise ExtractionError(
+                    f"extracted driver tree does not contain {spec.inf_member}",
+                    code="driver-inf-missing",
+                )
+            if settings_file is not None:
+                self._install_settings(staging, spec, settings_file)
+            if target.exists():
+                shutil.rmtree(target, ignore_errors=True)
+            target.parent.mkdir(parents=True, exist_ok=True)
+            os.replace(staging, target)
+        finally:
+            if staging.exists():  # pragma: no cover - cleanup on failure
+                shutil.rmtree(staging, ignore_errors=True)
+
+        _write_marker(
+            target / MARKER_NAME,
+            {
+                "schema": _MARKER_SCHEMA,
+                "driver": spec.name,
+                "version": spec.version,
+                "artifact_url": spec.artifact.url,
+                "artifact_sha256": spec.artifact.sha256,
+                "installed_at": time.time(),
+                "inf": spec.inf_member,
+            },
+        )
+        settings = target / Path(spec.settings_member) if spec.settings_member else None
+        log.info("prepared driver bundle %s at %s", spec.name, target)
+        return DriverBundle(
+            spec=spec,
+            root=target,
+            inf_path=target / Path(spec.inf_member),
+            settings_path=settings if settings and settings.is_file() else None,
+        )
+
+    @staticmethod
+    def _install_settings(staging: Path, spec: DriverSpec, settings_file: os.PathLike) -> None:
+        if not spec.settings_member:
+            raise ConfigError(
+                f"driver {spec.name} does not declare a settings file", code="no-settings-member"
+            )
+        destination = staging / Path(spec.settings_member)
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copyfile(settings_file, destination)
+        log.info("installed custom driver settings from %s", settings_file)
+
+    def cached_driver(self, spec: DriverSpec) -> Optional[DriverBundle]:
+        """Return the prepared bundle without touching the network, if it is intact."""
+        target = self.driver_root / spec.name
+        inf_path = target / Path(spec.inf_member)
+        marker = _read_marker(target / MARKER_NAME)
+        if marker and marker.get("artifact_sha256") == spec.artifact.sha256 and inf_path.is_file():
+            settings = target / Path(spec.settings_member) if spec.settings_member else None
+            return DriverBundle(
+                spec=spec,
+                root=target,
+                inf_path=inf_path,
+                settings_path=settings if settings and settings.is_file() else None,
+                from_cache=True,
+            )
+        return None
+
+    def remove_driver_tree(self, spec: DriverSpec) -> bool:
+        """Delete the extracted driver tree (used by ``uninstall-driver --purge-files``)."""
+        target = self.driver_root / spec.name
+        marker = target / MARKER_NAME
+        if not target.exists() or _read_marker(marker) is None:
+            log.debug("refusing to delete %s: no valid marker file", target)
+            return False
+        shutil.rmtree(target, ignore_errors=True)
+        log.info("removed extracted driver tree %s", target)
+        return True
+
+    # -- tools ----------------------------------------------------------------------
+    def tool(self, manifest: Manifest, name: str, *, progress=None) -> Path:
+        """Download (if needed), verify, extract a tool and return its executable path."""
+        spec = manifest.tool(name)
+        root = self.cache_dir / spec.name
+        marker = root / MARKER_NAME
+        existing = _read_marker(marker)
+        if existing and existing.get("artifact_sha256") == spec.artifact.sha256:
+            try:
+                return tool_executable(spec, root)
+            except ConfigError:
+                log.warning("tool tree %s is incomplete; re-extracting", root)
+        archive = download_artifact(
+            spec.artifact,
+            cache_dir=self.cache_dir,
+            progress=progress,
+            mirror_extra=self._mirrors(),
+        )
+        actual = sha256_of(archive)
+        if actual != spec.artifact.sha256:
+            from ._download import _quarantine
+
+            _quarantine(archive, reason="tool digest mismatch", dest_dir=self.cache_dir / "quarantine")
+            raise IntegrityError(
+                f"{archive.name} does not match the pinned SHA-256 at the bundle boundary",
+                code="digest-mismatch",
+                details={"expected": spec.artifact.sha256, "actual": actual},
+            )
+        staging = self.cache_dir / f".{spec.name}.staging.{uuid.uuid4().hex[:8]}"
+        try:
+            extract_archive(
+                archive,
+                staging,
+                strip_components=spec.artifact.strip_components,
+                members=spec.artifact.members,
+            )
+            if root.exists():
+                shutil.rmtree(root, ignore_errors=True)
+            os.replace(staging, root)
+        finally:
+            if staging.exists():  # pragma: no cover - cleanup on failure
+                shutil.rmtree(staging, ignore_errors=True)
+        _write_marker(
+            root / MARKER_NAME,
+            {
+                "schema": _MARKER_SCHEMA,
+                "tool": spec.name,
+                "version": spec.version,
+                "artifact_url": spec.artifact.url,
+                "artifact_sha256": spec.artifact.sha256,
+                "installed_at": time.time(),
+            },
+        )
+        return tool_executable(spec, root)
+
+    def cached_tool(self, manifest: Manifest, name: str) -> Optional[Path]:
+        spec = manifest.tool(name)
+        root = self.cache_dir / spec.name
+        marker = _read_marker(root / MARKER_NAME)
+        if marker and marker.get("artifact_sha256") == spec.artifact.sha256:
+            try:
+                return tool_executable(spec, root)
+            except ConfigError:
+                return None
+        return None
+
+    def tools_integrity(self, manifest: Manifest) -> Dict[str, Optional[str]]:
+        """Report which cached tool trees are usable (used by ``check``)."""
+        result: Dict[str, Optional[str]] = {}
+        for name in manifest.tools:
+            path = self.cached_tool(manifest, name)
+            result[name] = str(path) if path else None
+        return result