pythonnative 0.40.0__cp313-cp313-win_amd64.whl

pythonnative/project/devices.py

@@ -0,0 +1,304 @@
+"""Device and simulator discovery for ``pn devices`` / ``pn run --device``.
+
+Enumerates the three kinds of targets a PythonNative app can run on:
+
+- **Android devices and emulators** via ``adb devices -l``.
+- **iOS Simulators** via ``xcrun simctl list devices --json``.
+- **Physical iOS devices** via ``xcrun devicectl list devices`` (Xcode
+  15+; earlier Xcodes simply report no physical devices).
+
+The shell-outs are isolated in ``list_*`` functions; the parsers are
+pure functions over captured text/JSON so they can be unit tested
+without any toolchain installed.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+import tempfile
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+__all__ = [
+    "Device",
+    "list_devices",
+    "list_android_devices",
+    "list_ios_simulators",
+    "list_ios_physical_devices",
+    "find_device",
+    "parse_adb_devices",
+    "parse_simctl_devices",
+    "parse_devicectl_devices",
+]
+
+
+@dataclass
+class Device:
+    """One runnable target.
+
+    Attributes:
+        platform: ``"android"`` or ``"ios"``.
+        kind: ``"device"``, ``"emulator"``, or ``"simulator"``.
+        identifier: The stable id used to target the device (adb
+            serial, simulator UDID, or devicectl identifier).
+        name: Human-readable model or simulator name.
+        os_version: OS version string when known.
+        state: ``"booted"``, ``"connected"``, ``"shutdown"``, or
+            ``"offline"``.
+    """
+
+    platform: str
+    kind: str
+    identifier: str
+    name: str
+    os_version: str = ""
+    state: str = ""
+
+    @property
+    def is_ready(self) -> bool:
+        """Whether the target can be used right now (or booted on demand)."""
+        if self.kind == "simulator":
+            return self.state in ("booted", "shutdown")
+        return self.state in ("booted", "connected")
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Return a JSON-serializable view of this target.
+
+        Derived from the dataclass fields so a field added later is
+        carried into the payload automatically, plus the computed
+        ``is_ready`` that consumers would otherwise have to re-derive
+        from ``kind`` and ``state``.
+
+        Returns:
+            The declared fields in declaration order, then ``is_ready``.
+        """
+        return {**asdict(self), "is_ready": self.is_ready}
+
+    def format(self) -> str:
+        """Return one aligned listing row for the CLI."""
+        os_part = f" ({self.os_version})" if self.os_version else ""
+        return f"  {self.identifier:<40} {self.kind:<10} {self.state:<10} {self.name}{os_part}"
+
+
+# ======================================================================
+# Android (adb)
+# ======================================================================
+
+
+def parse_adb_devices(output: str) -> List[Device]:
+    """Parse ``adb devices -l`` output into devices.
+
+    Args:
+        output: Raw stdout from ``adb devices -l``.
+
+    Returns:
+        Android devices and emulators (offline entries included, with
+        ``state="offline"``).
+    """
+    devices: List[Device] = []
+    for line in output.splitlines():
+        line = line.strip()
+        if not line or line.startswith("List of devices"):
+            continue
+        parts = line.split()
+        if len(parts) < 2:
+            continue
+        serial, state = parts[0], parts[1]
+        if state == "unauthorized":
+            state = "offline"
+        elif state == "device":
+            state = "connected"
+        model = ""
+        for token in parts[2:]:
+            if token.startswith("model:"):
+                model = token[len("model:") :].replace("_", " ")
+        kind = "emulator" if serial.startswith("emulator-") else "device"
+        devices.append(
+            Device(
+                platform="android",
+                kind=kind,
+                identifier=serial,
+                name=model or serial,
+                state=state if state in ("connected", "offline") else "offline",
+            )
+        )
+    return devices
+
+
+def list_android_devices() -> List[Device]:
+    """Return connected Android devices/emulators (empty without adb)."""
+    try:
+        result = subprocess.run(["adb", "devices", "-l"], check=False, capture_output=True, text=True)
+    except FileNotFoundError:
+        return []
+    return parse_adb_devices(result.stdout or "")
+
+
+# ======================================================================
+# iOS Simulators (simctl)
+# ======================================================================
+
+_RUNTIME_RE = re.compile(r"iOS[.-](\d+)[.-](\d+)")
+
+
+def parse_simctl_devices(data: Dict[str, Any]) -> List[Device]:
+    """Parse ``simctl list devices --json`` payload into devices.
+
+    Args:
+        data: The decoded JSON payload.
+
+    Returns:
+        Available iOS Simulators (unavailable ones are skipped).
+    """
+    devices: List[Device] = []
+    for runtime, entries in (data.get("devices") or {}).items():
+        match = _RUNTIME_RE.search(runtime)
+        os_version = f"iOS {match.group(1)}.{match.group(2)}" if match else ""
+        if "iOS" not in runtime:
+            continue
+        for entry in entries or []:
+            if not entry.get("isAvailable") or not entry.get("udid"):
+                continue
+            devices.append(
+                Device(
+                    platform="ios",
+                    kind="simulator",
+                    identifier=str(entry["udid"]),
+                    name=str(entry.get("name") or entry["udid"]),
+                    os_version=os_version,
+                    state="booted" if entry.get("state") == "Booted" else "shutdown",
+                )
+            )
+    return devices
+
+
+def list_ios_simulators() -> List[Device]:
+    """Return available iOS Simulators (empty without Xcode)."""
+    try:
+        result = subprocess.run(
+            ["xcrun", "simctl", "list", "devices", "available", "--json"],
+            check=False,
+            capture_output=True,
+            text=True,
+        )
+    except FileNotFoundError:
+        return []
+    try:
+        data = json.loads(result.stdout or "{}")
+    except json.JSONDecodeError:
+        return []
+    return parse_simctl_devices(data)
+
+
+# ======================================================================
+# Physical iOS devices (devicectl)
+# ======================================================================
+
+
+def parse_devicectl_devices(data: Dict[str, Any]) -> List[Device]:
+    """Parse ``devicectl list devices --json-output`` payload into devices.
+
+    Args:
+        data: The decoded JSON payload.
+
+    Returns:
+        Physical iOS devices.
+    """
+    devices: List[Device] = []
+    for entry in (data.get("result") or {}).get("devices") or []:
+        props = entry.get("deviceProperties") or {}
+        hardware = entry.get("hardwareProperties") or {}
+        connection = entry.get("connectionProperties") or {}
+        identifier = str(entry.get("identifier") or "")
+        if not identifier:
+            continue
+        state = "connected" if connection.get("tunnelState") in ("connected", "available") else "offline"
+        os_version = props.get("osVersionNumber") or ""
+        devices.append(
+            Device(
+                platform="ios",
+                kind="device",
+                identifier=identifier,
+                name=str(props.get("name") or hardware.get("marketingName") or identifier),
+                os_version=f"iOS {os_version}" if os_version else "",
+                state=state,
+            )
+        )
+    return devices
+
+
+def list_ios_physical_devices() -> List[Device]:
+    """Return physical iOS devices (empty without Xcode 15+)."""
+    with tempfile.TemporaryDirectory() as tmp:
+        out_path = Path(tmp) / "devices.json"
+        try:
+            subprocess.run(
+                ["xcrun", "devicectl", "list", "devices", "--json-output", str(out_path)],
+                check=False,
+                capture_output=True,
+                text=True,
+                timeout=30,
+            )
+        except (FileNotFoundError, subprocess.TimeoutExpired):
+            return []
+        if not out_path.is_file():
+            return []
+        try:
+            data = json.loads(out_path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            return []
+    return parse_devicectl_devices(data)
+
+
+# ======================================================================
+# Aggregation / selection
+# ======================================================================
+
+
+def list_devices(platform: Optional[str] = None) -> List[Device]:
+    """Return all known targets, optionally restricted to one platform.
+
+    Args:
+        platform: ``"android"``, ``"ios"``, or ``None`` for both.
+
+    Returns:
+        Devices ordered: Android first, then physical iOS devices, then
+        simulators (booted simulators before shutdown ones).
+    """
+    devices: List[Device] = []
+    if platform in (None, "android"):
+        devices.extend(list_android_devices())
+    if platform in (None, "ios"):
+        devices.extend(list_ios_physical_devices())
+        simulators = list_ios_simulators()
+        simulators.sort(key=lambda dev: (dev.state != "booted", dev.name))
+        devices.extend(simulators)
+    return devices
+
+
+def find_device(devices: List[Device], query: str) -> Optional[Device]:
+    """Resolve ``query`` against ``devices`` (exact id, then name match).
+
+    Args:
+        devices: Candidate devices.
+        query: An identifier, exact name, or case-insensitive name
+            substring.
+
+    Returns:
+        The best match, or ``None``. Ready devices win ties.
+    """
+    ready_first = sorted(devices, key=lambda dev: not dev.is_ready)
+    for device in ready_first:
+        if device.identifier == query:
+            return device
+    lowered = query.lower()
+    for device in ready_first:
+        if device.name.lower() == lowered:
+            return device
+    for device in ready_first:
+        if lowered in device.name.lower():
+            return device
+    return None

pythonnative/project/doctor.py

@@ -0,0 +1,283 @@
+"""Environment diagnostics for ``pn doctor``.
+
+Inspects the local toolchain and the project's ``pythonnative.toml`` and
+reports what's ready and what's missing for building on each platform,
+analogous to ``flutter doctor`` / ``npx react-native doctor``. The checks
+are deliberately read-only and fast; they shell out only to ask tools for
+their versions.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List, Optional
+
+from . import icons
+from .config import SUPPORTED_PYTHON_VERSIONS, AppConfig, ConfigError
+from .runtime_assets import PINNED_ASSETS
+
+OK = "ok"
+WARN = "warn"
+ERROR = "error"
+INFO = "info"
+
+_SYMBOLS = {OK: "[ok]", WARN: "[!]", ERROR: "[x]", INFO: "[i]"}
+
+
+@dataclass
+class CheckResult:
+    """The outcome of a single diagnostic check.
+
+    Attributes:
+        name: Short label for the thing checked.
+        level: One of ``"ok"``, ``"warn"``, ``"error"``, ``"info"``.
+        detail: Human-readable detail / remediation hint.
+    """
+
+    name: str
+    level: str
+    detail: str = ""
+
+    def format(self) -> str:
+        """Return a single aligned line for terminal output."""
+        symbol = _SYMBOLS.get(self.level, "[?]")
+        suffix = f": {self.detail}" if self.detail else ""
+        return f"  {symbol} {self.name}{suffix}"
+
+
+def _which_version(tool: str, version_args: List[str]) -> Optional[str]:
+    path = shutil.which(tool)
+    if not path:
+        return None
+    try:
+        out = subprocess.run([tool, *version_args], capture_output=True, text=True, timeout=20)
+    except Exception:
+        return path
+    text = (out.stdout or out.stderr or "").strip().splitlines()
+    return text[0] if text else path
+
+
+def build_python_for(python_version: str) -> Optional[str]:
+    """Locate an interpreter matching ``python_version`` (e.g. ``python3.13``) on ``PATH``.
+
+    Args:
+        python_version: CPython ``major.minor``.
+
+    Returns:
+        The interpreter path, or ``None`` when none is installed.
+    """
+    host = f"{sys.version_info.major}.{sys.version_info.minor}"
+    if host == python_version:
+        return sys.executable
+    return shutil.which(f"python{python_version}")
+
+
+def check_common(config: Optional[AppConfig] = None) -> List[CheckResult]:
+    """Run platform-agnostic checks (interpreters, requirements, optional dependencies).
+
+    Args:
+        config: The loaded app config, or ``None`` if unavailable.
+
+    Returns:
+        Check results for the host and build Pythons, the declared
+        requirements, and optional dependencies.
+    """
+    results: List[CheckResult] = []
+    py_version = f"{sys.version_info.major}.{sys.version_info.minor}"
+    if py_version in SUPPORTED_PYTHON_VERSIONS:
+        results.append(CheckResult("Host Python", OK, f"{sys.version.split()[0]}"))
+    else:
+        results.append(
+            CheckResult(
+                "Host Python",
+                WARN,
+                f"{py_version} (PythonNative targets {', '.join(SUPPORTED_PYTHON_VERSIONS)})",
+            )
+        )
+
+    if config is not None:
+        # pip cross-resolves iOS wheels from any interpreter, but Chaquopy
+        # needs a matching python3.X on the build machine whenever there
+        # are requirements, and release bytecode is version-specific.
+        build_python = build_python_for(config.python_version)
+        label = f"Build Python {config.python_version} (matches app.python_version)"
+        if build_python:
+            results.append(CheckResult(label, OK, build_python))
+        else:
+            level = WARN if config.requirements else INFO
+            results.append(
+                CheckResult(
+                    label,
+                    level,
+                    f"python{config.python_version} not found on PATH; Android builds with [requirements] and "
+                    "release bytecode compilation need it (e.g. uv python install "
+                    f"{config.python_version})",
+                )
+            )
+        if config.requirements:
+            count = len(config.requirements)
+            results.append(
+                CheckResult(
+                    "Requirements",
+                    INFO,
+                    f"{count} package(s) declared; run 'pn deps' to check device wheel availability",
+                )
+            )
+
+    if icons.pillow_available():
+        results.append(CheckResult("Pillow (icon/splash generation)", OK))
+    else:
+        results.append(
+            CheckResult(
+                "Pillow (icon/splash generation)",
+                WARN,
+                "not installed; run: pip install 'pythonnative[build]'",
+            )
+        )
+    return results
+
+
+def check_android(config: Optional[AppConfig]) -> List[CheckResult]:
+    """Run Android toolchain and signing checks.
+
+    Args:
+        config: The loaded app config, or ``None`` if unavailable.
+
+    Returns:
+        Android-specific check results.
+    """
+    results: List[CheckResult] = []
+    adb = _which_version("adb", ["--version"])
+    results.append(CheckResult("adb (Android platform-tools)", OK if adb else WARN, adb or "not found on PATH"))
+
+    java_home = shutil.which("java")
+    import os
+
+    if os.environ.get("JAVA_HOME") or java_home:
+        results.append(CheckResult("Java (JDK 17 recommended)", OK, os.environ.get("JAVA_HOME") or java_home or ""))
+    else:
+        results.append(CheckResult("Java (JDK 17 recommended)", WARN, "JAVA_HOME not set and 'java' not on PATH"))
+
+    if config is not None:
+        signing = config.android.signing
+        if signing.is_configured:
+            keystore = config.resolve_path(signing.keystore) if signing.keystore else None
+            if keystore and keystore.is_file():
+                results.append(CheckResult("Android release keystore", OK, str(keystore)))
+            else:
+                results.append(CheckResult("Android release keystore", ERROR, f"not found: {keystore}"))
+            missing = [env for env in (signing.store_password_env, signing.key_password_env) if not os.environ.get(env)]
+            if missing:
+                results.append(CheckResult("Android signing passwords", WARN, f"unset env: {', '.join(missing)}"))
+        else:
+            results.append(
+                CheckResult(
+                    "Android release signing",
+                    INFO,
+                    "not configured; release builds will be unsigned (set [android.signing])",
+                )
+            )
+    return results
+
+
+def check_ios(config: Optional[AppConfig]) -> List[CheckResult]:
+    """Run iOS toolchain and signing checks.
+
+    Args:
+        config: The loaded app config, or ``None`` if unavailable.
+
+    Returns:
+        iOS-specific check results.
+    """
+    results: List[CheckResult] = []
+    if sys.platform != "darwin":
+        results.append(CheckResult("macOS (required for iOS)", ERROR, f"this is {sys.platform}; iOS builds need macOS"))
+        return results
+
+    xcodebuild = _which_version("xcodebuild", ["-version"])
+    results.append(CheckResult("Xcode (xcodebuild)", OK if xcodebuild else ERROR, xcodebuild or "not found on PATH"))
+    simctl = shutil.which("xcrun")
+    results.append(CheckResult("xcrun simctl (Simulators)", OK if simctl else WARN, simctl or "not found on PATH"))
+
+    if config is not None:
+        if config.python_version not in PINNED_ASSETS:
+            supported = ", ".join(sorted(PINNED_ASSETS))
+            results.append(
+                CheckResult(
+                    "iOS embedded Python",
+                    WARN,
+                    f"app.python_version={config.python_version}; pinned iOS builds exist for {supported}",
+                )
+            )
+        if config.ios.development_team:
+            results.append(CheckResult("iOS development team", OK, config.ios.development_team))
+        else:
+            results.append(
+                CheckResult(
+                    "iOS development team",
+                    INFO,
+                    "not set; required for device builds (set [ios].development_team)",
+                )
+            )
+    return results
+
+
+def check_config(project_root: Path) -> tuple[Optional[AppConfig], List[CheckResult]]:
+    """Load and validate the project config, returning it with a result.
+
+    Args:
+        project_root: Directory expected to contain ``pythonnative.toml``.
+
+    Returns:
+        A tuple of the loaded config (or ``None``) and the check results.
+    """
+    results: List[CheckResult] = []
+    try:
+        config = AppConfig.load(project_root)
+    except ConfigError as exc:
+        results.append(CheckResult("pythonnative.toml", ERROR, str(exc).splitlines()[0]))
+        return None, results
+    results.append(CheckResult("pythonnative.toml", OK, f"{config.app_id} (v{config.version})"))
+    return config, results
+
+
+def run_doctor(project_root: Path, *, platform: Optional[str] = None) -> List[CheckResult]:
+    """Run all diagnostics for ``project_root``.
+
+    Args:
+        project_root: The project directory.
+        platform: Restrict checks to ``"android"`` or ``"ios"``; ``None``
+            checks both.
+
+    Returns:
+        All check results in display order.
+    """
+    config, results = check_config(project_root)
+    results.extend(check_common(config))
+    if platform in (None, "android"):
+        results.extend(check_android(config))
+    if platform in (None, "ios"):
+        results.extend(check_ios(config))
+    return results
+
+
+def worst_level(results: List[CheckResult]) -> str:
+    """Return the most severe level among ``results``.
+
+    Args:
+        results: The diagnostic results.
+
+    Returns:
+        ``"error"`` if any error, else ``"warn"`` if any warning, else
+        ``"ok"``.
+    """
+    levels = {result.level for result in results}
+    if ERROR in levels:
+        return ERROR
+    if WARN in levels:
+        return WARN
+    return OK