pythonnative 0.25.0__py3-none-any.whl → 0.26.0__py3-none-any.whl

pythonnative/project/devices.py

@@ -0,0 +1,291 @@
+"""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 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 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

@@ -17,7 +17,8 @@ from pathlib import Path
 from typing import List, Optional
 
 from . import icons
-from .config import IOS_SUPPORTED_PYTHON_VERSION, SUPPORTED_PYTHON_VERSIONS, AppConfig, ConfigError
+from .config import SUPPORTED_PYTHON_VERSIONS, AppConfig, ConfigError
+from .runtime_assets import PINNED_ASSETS
 
 OK = "ok"
 WARN = "warn"
@@ -154,13 +155,13 @@ def check_ios(config: Optional[AppConfig]) -> List[CheckResult]:
     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 != IOS_SUPPORTED_PYTHON_VERSION:
+        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}; only "
-                    f"{IOS_SUPPORTED_PYTHON_VERSION} has a pinned iOS build",
+                    f"app.python_version={config.python_version}; pinned iOS builds " f"exist for {supported}",
                 )
             )
         if config.ios.development_team:

pythonnative/project/ios.py

@@ -9,30 +9,32 @@ which avoids fragile ``project.pbxproj`` edits. This module owns the
 parts that must live on disk:
 
 - **Info.plist.** Display name, supported orientations, permission usage
-  descriptions (from ``[permissions]``), background modes, and any
-  ``[ios].extra_info_plist`` keys.
+  descriptions (from ``[permissions]``), background modes, URL schemes
+  (from ``[app].url_schemes``), and any ``[ios].extra_info_plist`` keys.
+- **Entitlements.** A ``.entitlements`` file generated when a declared
+  capability needs one (e.g., ``remote_notifications``).
 - **Branding.** The ``AppIcon`` asset and an optional ``Splash`` image
   set plus a generated ``LaunchScreen`` storyboard.
 - **Export options.** A plist for ``xcodebuild -exportArchive`` derived
   from ``[ios.signing]``.
 
-The embedded CPython runtime (``Python.framework``, the standard library,
-``rubicon-objc``, and user packages) is copied into the built ``.app``
-*after* the build by [`embed_runtime`][pythonnative.project.ios.embed_runtime],
-since PythonKit loads it at runtime rather than linking it.
+The embedded CPython runtime is *not* handled here: the bundled Xcode
+template links ``Python.xcframework`` directly and installs the standard
+library, app sources, and packages during the Xcode build (see the
+"Install Python runtime" build phase). The
+[`builder`][pythonnative.project.builder] stages the framework and the
+Python sources into the project before invoking ``xcodebuild``.
 """
 
 from __future__ import annotations
 
 import plistlib
-import shutil
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Callable, Dict, List, Optional
 
 from . import icons
 from .config import AppConfig
-from .runtime_assets import IOSRuntime
 
 PROJECT_NAME = "ios_template"
 """The fixed Xcode project/scheme/target name (kept stable on purpose)."""
@@ -43,6 +45,9 @@ PROJECT_FILE = "ios_template.xcodeproj"
 APP_BUNDLE_NAME = "ios_template.app"
 """The built ``.app`` bundle name (product name is left as the target name)."""
 
+ENTITLEMENTS_FILE = "ios_template/ios_template.entitlements"
+"""Project-relative path of the generated entitlements file (when needed)."""
+
 _ORIENTATIONS: Dict[str, List[str]] = {
     "portrait": ["UIInterfaceOrientationPortrait"],
     "landscape": [
@@ -97,6 +102,7 @@ def configure(project_dir: Path, config: AppConfig, *, log: Optional[Logger] = N
     info_plist = project_dir / "ios_template" / "Info.plist"
 
     configure_info_plist(info_plist, config)
+    write_entitlements(project_dir, config)
     _apply_branding(project_dir, config, emit)
 
     emit(f"Configured iOS project ({config.bundle_id}).")
@@ -131,6 +137,14 @@ def configure_info_plist(info_plist: Path, config: AppConfig) -> None:
     if resolved.ios_background_modes:
         plist["UIBackgroundModes"] = list(resolved.ios_background_modes)
 
+    if config.url_schemes:
+        plist["CFBundleURLTypes"] = [
+            {
+                "CFBundleURLName": config.bundle_id,
+                "CFBundleURLSchemes": list(config.url_schemes),
+            }
+        ]
+
     if config.splash:
         plist["UILaunchStoryboardName"] = "LaunchScreen"
 
@@ -141,6 +155,27 @@ def configure_info_plist(info_plist: Path, config: AppConfig) -> None:
         plistlib.dump(plist, handle)
 
 
+def write_entitlements(project_dir: Path, config: AppConfig) -> Optional[Path]:
+    """Generate the app entitlements file when a capability needs one.
+
+    Args:
+        project_dir: The staged ``ios_template`` directory.
+        config: The validated app configuration.
+
+    Returns:
+        The written entitlements path, or ``None`` when no declared
+        capability requires entitlements.
+    """
+    entitlements = config.resolved_permissions().ios_entitlements
+    if not entitlements:
+        return None
+    dest = project_dir / ENTITLEMENTS_FILE
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    with open(dest, "wb") as handle:
+        plistlib.dump(dict(entitlements), handle)
+    return dest
+
+
 # ======================================================================
 # Build settings / export options
 # ======================================================================
@@ -170,17 +205,22 @@ def build_settings(config: AppConfig, *, for_archive: bool = False) -> List[str]
     ]
     if config.ios.development_team:
         settings.append(f"DEVELOPMENT_TEAM={config.ios.development_team}")
+    if config.resolved_permissions().ios_entitlements:
+        settings.append(f"CODE_SIGN_ENTITLEMENTS={ENTITLEMENTS_FILE}")
     if for_archive and not config.ios.signing.provisioning_profile:
         settings.append("CODE_SIGN_STYLE=Automatic")
     return settings
 
 
-def write_export_options(config: AppConfig, dest: Path) -> Path:
+def write_export_options(config: AppConfig, dest: Path, *, upload: bool = False) -> Path:
     """Write an ``exportOptions.plist`` for ``xcodebuild -exportArchive``.
 
     Args:
         config: The validated app configuration.
         dest: Destination plist path.
+        upload: When ``True``, ask ``xcodebuild`` to upload the build to
+            App Store Connect instead of exporting a local ``.ipa``
+            (requires ``export_method = "app-store"``).
 
     Returns:
         ``dest``.
@@ -191,6 +231,8 @@ def write_export_options(config: AppConfig, dest: Path) -> Path:
         "compileBitcode": False,
         "stripSwiftSymbols": True,
     }
+    if upload:
+        options["destination"] = "upload"
     if config.ios.development_team:
         options["teamID"] = config.ios.development_team
     if signing.provisioning_profile:
@@ -274,71 +316,3 @@ _LAUNCH_STORYBOARD = """<?xml version="1.0" encoding="UTF-8"?>
     </resources>
 </document>
 """
-
-
-# ======================================================================
-# Runtime embedding (post-build)
-# ======================================================================
-
-
-def embed_runtime(
-    app_bundle: Path,
-    *,
-    runtime: IOSRuntime,
-    destination: str,
-    python_sources: Path,
-    site_packages: Optional[Path] = None,
-    log: Optional[Logger] = None,
-) -> None:
-    """Copy the embedded CPython runtime and app code into a built ``.app``.
-
-    PythonKit loads CPython at runtime, so the framework, standard
-    library, app sources, and pure-Python site packages are copied into
-    the bundle after the build/archive completes.
-
-    Args:
-        app_bundle: Path to the built ``.app`` directory.
-        runtime: The resolved iOS runtime paths.
-        destination: ``"simulator"`` or ``"device"`` (selects the slice).
-        python_sources: Directory whose children (``app``,
-            ``pythonnative``) are copied to the bundle root.
-        site_packages: Optional directory of installed pure-Python
-            packages (``rubicon-objc`` and user requirements) copied to
-            ``platform-site``.
-        log: Optional progress logger.
-    """
-    emit: Logger = log or (lambda _message: None)
-    app_bundle = Path(app_bundle)
-
-    framework = runtime.framework_for(destination)
-    if framework and framework.is_dir():
-        frameworks_dir = app_bundle / "Frameworks"
-        frameworks_dir.mkdir(parents=True, exist_ok=True)
-        shutil.copytree(framework, frameworks_dir / "Python.framework", dirs_exist_ok=True)
-        emit("Embedded Python.framework.")
-    else:
-        emit(f"Warning: no Python.framework for {destination}; the app may not start.")
-
-    stdlib = runtime.stdlib_for(destination)
-    if stdlib and stdlib.is_dir():
-        shutil.copytree(stdlib, app_bundle / "python-stdlib", dirs_exist_ok=True)
-        emit("Embedded Python standard library.")
-
-    if python_sources.is_dir():
-        for child in python_sources.iterdir():
-            target = app_bundle / child.name
-            if child.is_dir():
-                shutil.copytree(child, target, dirs_exist_ok=True)
-            else:
-                shutil.copy2(child, target)
-
-    if site_packages and site_packages.is_dir():
-        platform_site = app_bundle / "platform-site"
-        platform_site.mkdir(parents=True, exist_ok=True)
-        for child in site_packages.iterdir():
-            target = platform_site / child.name
-            if child.is_dir():
-                shutil.copytree(child, target, dirs_exist_ok=True)
-            else:
-                shutil.copy2(child, target)
-        emit("Embedded pure-Python site packages.")

pythonnative/project/permissions.py

@@ -55,6 +55,9 @@ class Capability:
             (e.g., ``"android.permission.CAMERA"``).
         ios_background_modes: ``UIBackgroundModes`` values to add
             (e.g., ``"location"``).
+        ios_entitlements: Code-signing entitlement key/value pairs the
+            capability requires (e.g., ``aps-environment`` for remote
+            push notifications).
         default_reason: Fallback usage description used when the
             capability is declared as ``true`` instead of a string.
         needs_reason: Whether iOS requires a usage description for this
@@ -68,6 +71,7 @@ class Capability:
     ios_usage_keys: Tuple[str, ...] = ()
     android_permissions: Tuple[str, ...] = ()
     ios_background_modes: Tuple[str, ...] = ()
+    ios_entitlements: Tuple[Tuple[str, object], ...] = ()
     default_reason: str = ""
     needs_reason: bool = True
 
@@ -196,11 +200,20 @@ CAPABILITIES: Dict[str, Capability] = {
         ),
         Capability(
             key="notifications",
-            summary="Show local and push notifications.",
+            summary="Show local notifications.",
             ios_usage_keys=(),
             android_permissions=("android.permission.POST_NOTIFICATIONS",),
             needs_reason=False,
         ),
+        Capability(
+            key="remote_notifications",
+            summary="Receive remote (APNs) push notifications on iOS.",
+            ios_usage_keys=(),
+            android_permissions=("android.permission.POST_NOTIFICATIONS",),
+            ios_background_modes=("remote-notification",),
+            ios_entitlements=(("aps-environment", "development"),),
+            needs_reason=False,
+        ),
         Capability(
             key="vibration",
             summary="Trigger haptic feedback / vibration.",
@@ -249,12 +262,15 @@ class ResolvedPermissions:
             mapped to their reason strings.
         ios_background_modes: Ordered, de-duplicated ``UIBackgroundModes``
             values.
+        ios_entitlements: Code-signing entitlement keys mapped to their
+            values (empty when no capability needs entitlements).
         android_permissions: Ordered, de-duplicated Android permission
             names (including the always-on base set).
     """
 
     ios_usage_descriptions: Dict[str, str] = field(default_factory=dict)
     ios_background_modes: List[str] = field(default_factory=list)
+    ios_entitlements: Dict[str, object] = field(default_factory=dict)
     android_permissions: List[str] = field(default_factory=list)
 
 
@@ -318,6 +334,8 @@ def resolve_permissions(
         for mode in cap.ios_background_modes:
             if mode not in background:
                 background.append(mode)
+        for entitlement_key, entitlement_value in cap.ios_entitlements:
+            resolved.ios_entitlements.setdefault(entitlement_key, entitlement_value)
         for perm in cap.android_permissions:
             if perm not in android:
                 android.append(perm)