idevice 0.1.0__py3-none-any.whl

idevice/__init__.py

@@ -0,0 +1,5 @@
+"""Cross-platform device automation library."""
+
+from idevice import device, uiauto
+
+__all__ = ["device", "uiauto"]

idevice/device/__init__.py

@@ -0,0 +1,29 @@
+"""Public API for ``DeviceBase`` and platform-specific device implementations."""
+
+from idevice.device.android.device import AndroidDevice
+from idevice.device.base.device import DeviceBase
+from idevice.device.base.errors import (
+    AppNotInstalledError,
+    CommandExecutionError,
+    DeviceError,
+    DeviceNotFoundError,
+)
+from idevice.device.base.runner import CommandResult, SubprocessRunner
+from idevice.device.factory import Platform, create_device
+from idevice.device.ios.device import IOSDevice
+from idevice.device.windows.device import WindowsDevice
+
+__all__ = [
+    "AndroidDevice",
+    "AppNotInstalledError",
+    "CommandExecutionError",
+    "CommandResult",
+    "DeviceError",
+    "DeviceNotFoundError",
+    "DeviceBase",
+    "IOSDevice",
+    "Platform",
+    "SubprocessRunner",
+    "WindowsDevice",
+    "create_device",
+]

idevice/device/android/__init__.py

@@ -0,0 +1,5 @@
+"""Android ``DeviceBase`` implementation."""
+
+from idevice.device.android.device import AndroidDevice
+
+__all__ = ["AndroidDevice"]

idevice/device/android/device.py

@@ -0,0 +1,217 @@
+"""Android ``DeviceBase`` implementation via adb."""
+
+from __future__ import annotations
+
+import logging
+import os
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from idevice.device.base.device import DeviceBase
+from idevice.device.base.errors import AppNotInstalledError
+from idevice.device.base.runner import SubprocessRunner
+from idevice.device.config import adb_binary
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class InstallResult:
+    ok: bool
+    returncode: int
+    stdout: str
+    stderr: str
+
+
+class AndroidDeviceError(RuntimeError):
+    """Raised when an Android device operation fails."""
+
+
+class AndroidDevice(DeviceBase):
+    """``DeviceBase`` implementation for Android using adb."""
+
+    DEFAULT_BINARY = "adb"
+
+    def __init__(self, device_id: str) -> None:
+        super().__init__(device_id)
+        self._binary = self.DEFAULT_BINARY
+        self._runner = SubprocessRunner()
+        if shutil.which(self._binary) is None:
+            logger.error(f"[AndroidDevice] `{self._binary}` CLI not found on PATH")
+            raise AndroidDeviceError(
+                f"`{self._binary}` CLI not found on PATH. "
+                "Install adb: https://developer.android.com/studio/releases/platform-tools"
+            )
+        self._installed_pkg_names: dict[str, str] = {}
+
+    def _base_command(self) -> list[str]:
+        return [adb_binary(), "-s", self.device_id]
+
+    def install(self, package_path: Path, app_id: str | None = None) -> None:
+        """Install an APK on the bound device via uiautomator2.
+
+        Example::
+
+            from pathlib import Path
+
+            from idevice.device.android.device import AndroidDevice
+
+            device = AndroidDevice("e8b2b043")
+            apk = Path("tests/apk/app.apk")
+            device.install(apk, app_id="com.example.app")
+            assert device.is_installed("com.example.app")
+        """
+        logger.info(f"[AndroidDevice] Installing package on {self.device_id}: {package_path}")
+        if not package_path.exists():
+            raise FileNotFoundError(f"Package not found: {package_path}")
+
+        try:
+            cmd = self._base_command()
+            cmd.extend(["install", "-r", str(package_path)])
+            result = self._install_with_uiautomator2(cmd, device_id=self.device_id)
+            if not result.ok:
+                raise AndroidDeviceError(f"Package install failed on {self.device_id}: {result.stderr}")
+        except Exception as exc:
+            raise AndroidDeviceError(f"Package install failed on {self.device_id}: {exc}") from exc
+
+        if app_id:
+            self._installed_pkg_names[app_id] = package_path.name
+            logger.debug(f"[AndroidDevice] Cached package name for app_id={app_id}")
+
+    def uninstall(self, app_id: str) -> None:
+        logger.info(f"[AndroidDevice] Uninstalling {app_id} on {self.device_id}")
+        command = self._base_command()
+        command.extend(["uninstall", app_id])
+        self._runner.run(command)
+        self._installed_pkg_names.pop(app_id, None)
+
+    def is_installed(self, app_id: str) -> bool:
+        command = self._base_command()
+        command.extend(["shell", "pm", "list", "packages", app_id])
+        result = self._runner.run(command)
+        prefix = f"package:{app_id}"
+        installed = any(line.strip() == prefix for line in result.stdout.splitlines())
+        logger.debug(f"App {app_id} installed on Android device {self.device_id}: {installed}")
+        return installed
+
+    def launch_app(self, app_id: str) -> None:
+        if not app_id:
+            raise ValueError("app_id is required and must be a non-empty string")
+        if not self.is_installed(app_id):
+            raise AppNotInstalledError(f"App not installed: {app_id}")
+        logger.info(f"[AndroidDevice] Launching {app_id} on {self.device_id}")
+        command = self._base_command()
+        command.extend(
+            [
+                "shell",
+                "monkey",
+                "-p",
+                app_id,
+                "-c",
+                "android.intent.category.LAUNCHER",
+                "1",
+            ]
+        )
+        self._runner.run(command)
+
+    def stop_app(self, app_id: str) -> None:
+        if not app_id:
+            raise ValueError("app_id is required and must be a non-empty string")
+        logger.info(f"Stopping app on Android device {self.device_id}: {app_id}")
+        command = self._base_command()
+        command.extend(["shell", "am", "force-stop", app_id])
+        self._runner.run(command)
+
+    def get_installed_pkg_name(self, app_id: str) -> str | None:
+        if not self.is_installed(app_id):
+            return None
+        return self._installed_pkg_names.get(app_id)
+
+    def host_is_running(self) -> bool:
+        return True
+
+    def push(
+        self,
+        local: Path | str,
+        remote: str,
+        *,
+        app_id: str | None = None,
+    ) -> None:
+        """Push a local file or directory to the device via ``adb push``."""
+        del app_id
+        if not remote:
+            raise ValueError("remote is required and must be a non-empty string")
+        local_path = Path(local)
+        if not local_path.exists():
+            raise FileNotFoundError(f"Local path not found: {local_path}")
+        logger.info(f"[AndroidDevice] Pushing {local_path} to {self.device_id}:{remote}")
+        command = self._base_command()
+        command.extend(["push", str(local_path), remote])
+        self._runner.run(command)
+
+    def pull(
+        self,
+        remote: str,
+        local: Path | str,
+        *,
+        app_id: str | None = None,
+    ) -> None:
+        """Pull a remote file or directory from the device via ``adb pull``."""
+        del app_id
+        if not remote:
+            raise ValueError("remote is required and must be a non-empty string")
+        local_path = Path(local)
+        local_path.parent.mkdir(parents=True, exist_ok=True)
+        logger.info(f"[AndroidDevice] Pulling {self.device_id}:{remote} to {local_path}")
+        command = self._base_command()
+        command.extend(["pull", remote, str(local_path)])
+        self._runner.run(command)
+
+    def _install_with_uiautomator2(self, cmd: list[str], *, device_id: str | None) -> InstallResult:
+        """Use uiautomator2 WatchContext (builtin + extra) while adb install runs."""
+        import uiautomator2 as u2
+
+        logger.info(f"install with uiautomator2: {cmd}")
+        d = u2.connect(device_id) if device_id else u2.connect()
+        # autostart=False so we can register rules before the background thread runs.
+        with d.watch_context(builtin=True, autostart=False) as ctx:
+            # Builtin rules cover common install prompts (继续安装, ALLOW, Agree, …).
+            ctx.when("仍要安装").click()
+            ctx.when("Install").click()
+            ctx.start()
+            p = subprocess.run(cmd, capture_output=True, text=True, timeout=600)
+
+        if p.returncode == 0:
+            self._dismiss_post_install_popups(d)
+
+        out = (p.stdout or "").strip()
+        err = (p.stderr or "").strip()
+        ok = p.returncode == 0
+        return InstallResult(ok, p.returncode, out, err)
+
+    def _dismiss_post_install_popups(self, d) -> None:
+        """Dismiss OEM dialogs after adb install; watcher already stopped."""
+        stable = float(os.environ.get("GAUTO_APK_POST_INSTALL_STABLE_SEC", "2"))
+        timeout_sec = float(os.environ.get("GAUTO_APK_POST_INSTALL_TIMEOUT_SEC", "30"))
+        with d.watch_context(builtin=True, autostart=False) as ctx:
+            # Prefer dismiss over launching the app when both exist.
+            ctx.when("完成").click()
+            ctx.when("完成安装").click()
+            ctx.when("知道了").click()
+            ctx.when("我知道了").click()
+            ctx.when("以后再说").click()
+            ctx.when("稍后").click()
+            ctx.when("暂不").click()
+            ctx.when("跳过").click()
+            ctx.when("关闭").click()
+            ctx.when("Done").click()
+            ctx.when("OPEN").click()
+            ctx.when("打开").click()
+            ctx.when("立即打开").click()
+            ctx.start()
+            try:
+                ctx.wait_stable(seconds=stable, timeout=timeout_sec)
+            except TimeoutError:
+                logger.debug(f"post-install popups did not stabilize within {timeout_sec}s")

idevice/device/base/__init__.py

@@ -0,0 +1,20 @@
+"""``DeviceBase`` and shared utilities for device control."""
+
+from idevice.device.base.device import DeviceBase
+from idevice.device.base.errors import (
+    AppNotInstalledError,
+    CommandExecutionError,
+    DeviceError,
+    DeviceNotFoundError,
+)
+from idevice.device.base.runner import CommandResult, SubprocessRunner
+
+__all__ = [
+    "AppNotInstalledError",
+    "CommandExecutionError",
+    "CommandResult",
+    "DeviceError",
+    "DeviceNotFoundError",
+    "DeviceBase",
+    "SubprocessRunner",
+]

idevice/device/base/device.py

@@ -0,0 +1,151 @@
+"""Abstract ``DeviceBase`` for cross-platform device app lifecycle."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+
+class DeviceBase(ABC):
+    """Install packages and launch apps on a device (adb / ios / hdc, etc.).
+
+    A device instance is always bound to a single ``device_id`` (UDID / serial).
+    """
+
+    def __init__(self, device_id: str):
+        if not device_id or not isinstance(device_id, str):
+            raise ValueError("device_id is required and must be a non-empty string")
+        self._device_id = device_id
+
+    @property
+    def device_id(self) -> str:
+        """Device id (UDID / serial) bound to this instance."""
+        return self._device_id
+
+    @abstractmethod
+    def install(self, package_path: Path, app_id: str | None = None) -> None:
+        """Install a package on the bound device.
+
+        Args:
+            package_path: Path to the package to install.
+            app_id: Optional app identifier (bundle id / package name) associated
+                with ``package_path``. When provided, implementations should
+                record the ``app_id -> package file name`` mapping so it can
+                later be retrieved via :meth:`get_installed_pkg_name`.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def uninstall(self, app_id: str) -> None:
+        """Remove an installed app (package / bundle name per platform).
+
+        Args:
+            app_id: ID of the app to uninstall.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def is_installed(self, app_id: str) -> bool:
+        """Check if an app is installed on the bound device.
+
+        Args:
+            app_id: ID of the app to check.
+
+        Returns:
+            bool: True if the app is installed, False otherwise.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def launch_app(self, app_id: str) -> None:
+        """Launch an installed app on the bound device.
+
+        Args:
+            app_id: ID of the app to launch (bundle id / package name).
+
+        Raises:
+            ValueError: If ``app_id`` is empty.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def stop_app(self, app_id: str) -> None:
+        """Stop (kill) a running app on the bound device.
+
+        Args:
+            app_id: ID of the app to stop (bundle id / package name).
+
+        Raises:
+            ValueError: If ``app_id`` is empty.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_installed_pkg_name(self, app_id: str) -> str | None:
+        """Return the installed package file name for an app on the bound device.
+
+        Implementations should return the original package file name
+        (e.g. the ``.ipa`` / ``.apk`` / ``.hap`` filename) recorded at install
+        time, or ``None`` if the app is not installed or no record is found.
+
+        Args:
+            app_id: ID of the app to look up (bundle id / package name).
+
+        Returns:
+            str | None: The installed package file name, or ``None`` if not found.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def host_is_running(self) -> bool:
+        """Check if the WDA/UIAutomator2  is running on the bound device.
+
+        Returns:
+            bool: True if the WDA/UIAutomator2 is running, False otherwise.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def push(
+        self,
+        local: Path | str,
+        remote: str,
+        *,
+        app_id: str | None = None,
+    ) -> None:
+        """Push a local file or directory to the bound device.
+
+        Args:
+            local: Path to the local file or directory.
+            remote: Destination path on the device.
+            app_id: Optional app identifier (bundle id / package name) when
+                the transfer targets an app sandbox. Ignored on platforms
+                that do not support scoped transfers.
+
+        Raises:
+            ValueError: If ``remote`` is empty.
+            FileNotFoundError: If ``local`` does not exist.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def pull(
+        self,
+        remote: str,
+        local: Path | str,
+        *,
+        app_id: str | None = None,
+    ) -> None:
+        """Pull a remote file or directory from the bound device.
+
+        Args:
+            remote: Source path on the device.
+            local: Destination path on the host.
+            app_id: Optional app identifier (bundle id / package name) when
+                the transfer targets an app sandbox. Ignored on platforms
+                that do not support scoped transfers.
+
+        Raises:
+            ValueError: If ``remote`` is empty.
+        """
+        raise NotImplementedError

idevice/device/base/errors.py

@@ -0,0 +1,32 @@
+"""Exceptions raised by ``DeviceBase`` implementations."""
+
+
+class DeviceError(Exception):
+    """Base exception for ``DeviceBase`` and platform device classes."""
+
+
+class DeviceNotFoundError(DeviceError):
+    """Raised when the specified device is not found."""
+
+
+class AppNotInstalledError(DeviceError):
+    """Raised when an operation requires an app that is not installed."""
+
+
+class CommandExecutionError(DeviceError):
+    """Raised when an underlying CLI command fails."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        command: list[str] | None = None,
+        returncode: int | None = None,
+        stdout: str = "",
+        stderr: str = "",
+    ) -> None:
+        super().__init__(message)
+        self.command = command
+        self.returncode = returncode
+        self.stdout = stdout
+        self.stderr = stderr

idevice/device/base/runner.py

@@ -0,0 +1,83 @@
+"""Shared subprocess runner for device CLI tools."""
+
+from __future__ import annotations
+
+import logging
+import os
+import subprocess
+from dataclasses import dataclass
+
+from idevice.device.base.errors import CommandExecutionError
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_COMMAND_TIMEOUT = 120
+
+
+@dataclass(frozen=True)
+class CommandResult:
+    """Result of a subprocess command."""
+
+    returncode: int
+    stdout: str
+    stderr: str
+
+
+class SubprocessRunner:
+    """Execute external CLI commands with consistent error handling."""
+
+    def __init__(self, timeout: int | None = None) -> None:
+        env_timeout = os.environ.get("IDEVICE_COMMAND_TIMEOUT")
+        if timeout is not None:
+            self.timeout = timeout
+        elif env_timeout:
+            self.timeout = int(env_timeout)
+        else:
+            self.timeout = DEFAULT_COMMAND_TIMEOUT
+
+    def run(
+        self,
+        command: list[str],
+        *,
+        check: bool = True,
+        input_text: str | None = None,
+    ) -> CommandResult:
+        """Run a command and optionally raise on non-zero exit."""
+        logger.debug(f"Running command: {command}")
+        try:
+            completed = subprocess.run(
+                command,
+                capture_output=True,
+                text=True,
+                timeout=self.timeout,
+                input=input_text,
+                check=False,
+            )
+        except subprocess.TimeoutExpired as exc:
+            logger.warning(f"Command timed out after {self.timeout}s: {' '.join(command)}")
+            raise CommandExecutionError(
+                f"Command timed out after {self.timeout}s: {' '.join(command)}",
+                command=command,
+            ) from exc
+        except FileNotFoundError as exc:
+            logger.warning(f"Command not found: {command[0]}")
+            raise CommandExecutionError(
+                f"Command not found: {command[0]}",
+                command=command,
+            ) from exc
+
+        result = CommandResult(
+            returncode=completed.returncode,
+            stdout=completed.stdout,
+            stderr=completed.stderr,
+        )
+        if check and completed.returncode != 0:
+            logger.warning(f"Command failed with exit code {completed.returncode}: {' '.join(command)}")
+            raise CommandExecutionError(
+                f"Command failed with exit code {completed.returncode}: {' '.join(command)}",
+                command=command,
+                returncode=completed.returncode,
+                stdout=completed.stdout,
+                stderr=completed.stderr,
+            )
+        return result

idevice/device/cache.py

@@ -0,0 +1,52 @@
+"""Persistent cache for device app_id -> package_path mappings."""
+
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+
+from idevice.device.config import user_data_dir
+
+logger = logging.getLogger(__name__)
+
+
+class InstalledAppCache:
+    """Persist ``app_id -> package_path`` mappings per device in user data dir."""
+
+    def __init__(self, device_id: str, *, cache_dir: Path | None = None) -> None:
+        if not device_id:
+            raise ValueError("device_id is required and must be a non-empty string")
+        self._device_id = device_id
+        self._cache_dir = cache_dir or user_data_dir()
+        self._cache_file = self._cache_dir / f"{device_id}.json"
+
+    def _load(self) -> dict[str, dict[str, str]]:
+        if not self._cache_file.exists():
+            return {}
+        with open(self._cache_file, encoding="utf-8") as f:
+            return json.load(f)
+
+    def _save(self, data: dict[str, dict[str, str]]) -> None:
+        self._cache_dir.mkdir(parents=True, exist_ok=True)
+        with open(self._cache_file, "w", encoding="utf-8") as f:
+            json.dump(data, f)
+
+    def add(self, app_id: str, package_path: Path) -> None:
+        """Record ``app_id`` mapped to ``package_path`` for this device."""
+        logger.debug(f"Caching app_id={app_id} -> {package_path} for device {self._device_id}")
+        data = self._load()
+        data[app_id] = str(package_path.resolve())
+        self._save(data)
+
+    def remove(self, app_id: str) -> None:
+        """Remove the cached mapping for ``app_id`` on this device."""
+        logger.debug(f"Removing cached app_id={app_id} for device {self._device_id}")
+        data = self._load()
+        data.pop(app_id, None)
+        self._save(data)
+
+    def get(self, app_id: str) -> Path | None:
+        """Return the cached package path for ``app_id``, if present."""
+        path_str = self._load().get(self._device_id, {}).get(app_id)
+        return Path(path_str) if path_str else None

idevice/device/config.py

@@ -0,0 +1,26 @@
+"""Environment-based configuration for ``DeviceBase`` implementations."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def ios_binary() -> str:
+    """Return the go-ios CLI binary path."""
+    return os.environ.get("IDEVICE_IOS_BINARY", "ios")
+
+
+def adb_binary() -> str:
+    """Return the adb CLI binary path."""
+    return os.environ.get("IDEVICE_ADB_BINARY", "adb")
+
+
+def powershell_binary() -> str:
+    """Return the PowerShell binary path."""
+    return os.environ.get("IDEVICE_POWERSHELL_BINARY", "powershell")
+
+
+def user_data_dir() -> Path:
+    """Return the default directory for idevice user data."""
+    return Path.home() / ".idevice"

idevice/device/factory.py

@@ -0,0 +1,37 @@
+"""Device factory for platform-specific implementations."""
+
+from __future__ import annotations
+
+import logging
+from enum import StrEnum
+from typing import Any
+
+from idevice.device.android.device import AndroidDevice
+from idevice.device.base.device import DeviceBase
+from idevice.device.ios.device import IOSDevice
+from idevice.device.windows.device import WindowsDevice
+
+logger = logging.getLogger(__name__)
+
+
+class Platform(StrEnum):
+    """Supported device platforms."""
+
+    IOS = "ios"
+    ANDROID = "android"
+    WINDOWS = "windows"
+
+
+def create_device(platform: Platform, **kwargs: Any) -> DeviceBase:
+    """Create a platform-specific ``DeviceBase`` subclass instance."""
+    logger.debug(f"Creating device for platform={platform} kwargs={kwargs}")
+    if platform is Platform.IOS:
+        device = IOSDevice(**kwargs)
+    elif platform is Platform.ANDROID:
+        device = AndroidDevice(**kwargs)
+    elif platform is Platform.WINDOWS:
+        device = WindowsDevice(**kwargs)
+    else:
+        raise ValueError(f"Unsupported platform: {platform}")
+    logger.info(f"Created {type(device).__name__} for device_id={device.device_id}")
+    return device

idevice/device/ios/__init__.py

@@ -0,0 +1,6 @@
+"""iOS ``DeviceBase`` implementation."""
+
+from idevice.device.cache import InstalledAppCache
+from idevice.device.ios.device import IOSDevice, IOSDeviceError
+
+__all__ = ["IOSDevice", "IOSDeviceError", "InstalledAppCache"]