idevice 0.1.0__tar.gz

idevice-0.1.0/.cursor/rules/AGENTS.md

@@ -0,0 +1,55 @@
+---
+description: "Cursor rules for Python development with projects guide integration."
+globs: **/*
+alwaysApply: true
+---
+You are an AI assistant specialized in Python development. Your approach emphasizes:
+
+1. Clear project structure with monorepo.
+3. Configuration management using environment variables.
+4. Robust error handling and logging use fstring, including context capture.
+5. Comprehensive testing with pytest.
+6. Detailed documentation using docstrings and README files.
+7. Dependency management via https://docs.astral.sh/uv and virtual environments.
+8. Code style consistency using Ruff.
+9. CI/CD implementation with GitHub Actions or GitLab CI.
+10. AI-friendly coding practices:
+   - Descriptive variable and function names
+   - Type hints
+   - Detailed comments for complex logic
+   - Rich error context for debugging
+
+You provide code snippets and explanations tailored to these principles, optimizing for clarity and AI-assisted development.
+
+## Project Structure
+- Use src-layout with `src/your_package_name/`
+- Place tests in `tests/` directory parallel to `src/`
+- Keep configuration in `config/` or as environment variables
+- Store requirements in `pyproject.toml`
+- Place static files in `static/` directory
+
+## Code Style
+- Follow Black code formatting
+- Use isort for import sorting
+- Follow PEP 8 naming conventions:
+  - snake_case for functions and variables
+  - PascalCase for classes
+  - UPPER_CASE for constants
+- Maximum line length of 88 characters (Black default)
+- Use absolute imports over relative imports
+
+## Type Hints
+- Use type hints for all function parameters and returns
+- Import types from `typing` module
+- Use `Optional[Type]` instead of `Type | None`
+- Use `TypeVar` for generic types
+- Define custom types in `types.py`
+- Use `Protocol` for duck typing
+
+## Documentation
+- Use Google-style docstrings
+- Document all public APIs
+- Keep README.md updated
+- Use proper inline comments
+- Generate API documentation
+- Document environment setup

idevice-0.1.0/.github/workflows/workflow.yml

@@ -0,0 +1,49 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.14"
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --extra dev --frozen
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Test
+        run: uv run pytest --import-mode=importlib
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.14"
+
+      - name: Build
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

idevice-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# IDEs
+.vscode/
+.idea/
+
+# OS generated files
+.DS_Store
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+Icon?
+$RECYCLE.BIN/
+$SystemVolumeInformation/
+$Windows.~WS/
+$Windows.~WS/

idevice-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

idevice-0.1.0/AGENTS.md

@@ -0,0 +1,13 @@
+# Agents
+
+This repository uses VS Code Copilot agents and customization files to assist with development tasks.
+
+## Purpose
+
+- Document available agents and how to use them in this workspace.
+- Provide a reference for contributors.
+
+## Notes
+
+- The workspace contains a `.cursor/rules/AGENTS.md` file for agent behavior rules.
+- Add any high-level agent usage or customization details here as needed.

idevice-0.1.0/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: idevice
+Version: 0.1.0
+Summary: Cross-platform device automation for end-to-end test workflows
+Requires-Python: >=3.14
+Requires-Dist: uiautomator2>=3.5.2
+Provides-Extra: dev
+Requires-Dist: pytest-mock>=3.14; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.9; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# idevice
+
+Cross-platform device automation for end-to-end test workflows: install and manage apps on physical devices, and drive UI interactions through a small, platform-agnostic API.
+
+**Status:** iOS is implemented (go-ios for package management, WebDriverAgent for UI). Android, Windows, macOS, and HarmonyOS are planned.

idevice-0.1.0/README.md

@@ -0,0 +1,5 @@
+# idevice
+
+Cross-platform device automation for end-to-end test workflows: install and manage apps on physical devices, and drive UI interactions through a small, platform-agnostic API.
+
+**Status:** iOS is implemented (go-ios for package management, WebDriverAgent for UI). Android, Windows, macOS, and HarmonyOS are planned.

idevice-0.1.0/examples/README.md

@@ -0,0 +1,34 @@
+# Examples
+
+## Android: install an APK
+
+Install a package on a connected device and verify it with `pm list packages`:
+
+```bash
+uv run python examples/android_device_install.py \
+  --serial "$(adb devices | awk 'NR>2 && $2=="device" {print $1; exit}')" \
+  --apk tests/apk/app.apk \
+  --package com.Unity.TrashDash
+```
+
+Optional: dismiss OEM post-install dialogs after install:
+
+```bash
+uv run python examples/android_device_install.py \
+  --serial e8b2b043 \
+  --apk tests/apk/app.apk \
+  --package com.Unity.TrashDash \
+  --dismiss-dialogs
+```
+
+Minimal Python usage:
+
+```python
+from pathlib import Path
+
+from idevice.device.android.device import AndroidDevice
+
+device = AndroidDevice("e8b2b043")
+device.install(Path("tests/apk/app.apk"), app_id="com.Unity.TrashDash")
+assert device.is_installed("com.Unity.TrashDash")
+```

idevice-0.1.0/examples/android_device_install.py

@@ -0,0 +1,131 @@
+#!/usr/bin/env python3
+"""Install an APK on a connected Android device using :class:`AndroidDevice`.
+
+Prerequisites:
+    - ``adb`` on PATH (or set ``IDEVICE_ADB_BINARY``)
+    - Device visible in ``adb devices`` with state ``device``
+    - ``uiautomator2`` (installed with idevice)
+
+Example:
+    uv run python examples/android_device_install.py \\
+        --serial e8b2b043 \\
+        --apk tests/apk/app.apk \\
+        --package com.Unity.TrashDash
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import subprocess
+import sys
+from pathlib import Path
+
+from idevice.device.android.device import AndroidDevice, AndroidDeviceError
+from idevice.device.config import adb_binary
+from idevice.uiauto.android.automation import AndroidUIAuto
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+DEFAULT_APK = REPO_ROOT / "tests" / "apk" / "app.apk"
+
+logger = logging.getLogger(__name__)
+
+
+def _resolve_serial(explicit: str | None) -> str:
+    if explicit:
+        return explicit
+    try:
+        completed = subprocess.run(
+            [adb_binary(), "devices"],
+            capture_output=True,
+            text=True,
+            timeout=30,
+            check=True,
+        )
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        raise SystemExit(f"Failed to list devices: {exc}") from exc
+
+    for line in completed.stdout.splitlines():
+        parts = line.split()
+        if len(parts) >= 2 and parts[1] == "device":
+            return parts[0]
+    raise SystemExit("No connected device found. Pass --serial or connect a device via adb.")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Install an APK on an Android device via idevice.",
+    )
+    parser.add_argument(
+        "--serial",
+        help="adb device serial (default: first device in `adb devices`)",
+    )
+    parser.add_argument(
+        "--apk",
+        type=Path,
+        default=DEFAULT_APK,
+        help=f"Path to the APK (default: {DEFAULT_APK.relative_to(REPO_ROOT)})",
+    )
+    parser.add_argument(
+        "--package",
+        required=True,
+        help="Android package name (applicationId), e.g. com.example.app",
+    )
+    parser.add_argument(
+        "--dismiss-dialogs",
+        action="store_true",
+        help="Dismiss OEM post-install dialogs after install",
+    )
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="Enable debug logging",
+    )
+    args = parser.parse_args(argv)
+
+    logging.basicConfig(
+        level=logging.DEBUG if args.verbose else logging.INFO,
+        format="%(levelname)s %(message)s",
+    )
+
+    serial = _resolve_serial(args.serial)
+    apk_path = args.apk.resolve()
+    if not apk_path.is_file():
+        logger.error("APK not found: %s", apk_path)
+        return 1
+
+    try:
+        device = AndroidDevice(serial)
+    except AndroidDeviceError as exc:
+        logger.error("%s", exc)
+        return 1
+
+    logger.info("Installing %s on %s", apk_path.name, serial)
+    try:
+        device.install(apk_path, app_id=args.package)
+    except (AndroidDeviceError, FileNotFoundError) as exc:
+        logger.error("Install failed: %s", exc)
+        return 1
+
+    if not device.is_installed(args.package):
+        logger.error("Package %s not reported as installed", args.package)
+        return 1
+
+    pkg_file = device.get_installed_pkg_name(args.package)
+    logger.info(
+        "Installed %s (recorded package file: %s)",
+        args.package,
+        pkg_file or apk_path.name,
+    )
+
+    if args.dismiss_dialogs:
+        uiauto = AndroidUIAuto(serial)
+        dismissed = uiauto.dismiss_post_install_dialogs()
+        logger.info("Dismissed %s post-install dialog(s)", dismissed)
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

idevice-0.1.0/idevice/__init__.py

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

idevice-0.1.0/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-0.1.0/idevice/device/android/__init__.py

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

idevice-0.1.0/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-0.1.0/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",
+]