pythonnative 0.20.0__py3-none-any.whl → 0.22.0__py3-none-any.whl

pythonnative/project/ios.py

@@ -0,0 +1,344 @@
+"""Config-driven iOS project configurator.
+
+Adapts the bundled ``ios_template`` Xcode project to a specific
+[`AppConfig`][pythonnative.project.config.AppConfig]. Unlike Android, the
+iOS bundle identifier, version, team, and deployment target are *not*
+baked into files — they're passed to ``xcodebuild`` as build-setting
+overrides (see [`build_settings`][pythonnative.project.ios.build_settings]),
+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.
+- **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.
+"""
+
+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)."""
+
+PROJECT_FILE = "ios_template.xcodeproj"
+"""The ``.xcodeproj`` directory name within the staged template."""
+
+APP_BUNDLE_NAME = "ios_template.app"
+"""The built ``.app`` bundle name (product name is left as the target name)."""
+
+_ORIENTATIONS: Dict[str, List[str]] = {
+    "portrait": ["UIInterfaceOrientationPortrait"],
+    "landscape": [
+        "UIInterfaceOrientationLandscapeLeft",
+        "UIInterfaceOrientationLandscapeRight",
+    ],
+    "all": [
+        "UIInterfaceOrientationPortrait",
+        "UIInterfaceOrientationLandscapeLeft",
+        "UIInterfaceOrientationLandscapeRight",
+    ],
+}
+
+_EXPORT_METHODS = {
+    "development": "development",
+    "ad-hoc": "ad-hoc",
+    "app-store": "app-store",
+    "enterprise": "enterprise",
+}
+
+Logger = Callable[[str], None]
+
+
+@dataclass
+class IOSLayout:
+    """Resolved paths within a configured iOS project.
+
+    Attributes:
+        project_dir: The staged ``ios_template`` directory.
+        info_plist: Path to the app ``Info.plist``.
+        bundle_id: The resolved iOS bundle identifier.
+    """
+
+    project_dir: Path
+    info_plist: Path
+    bundle_id: str
+
+
+def configure(project_dir: Path, config: AppConfig, *, log: Optional[Logger] = None) -> IOSLayout:
+    """Configure a staged iOS template for ``config``.
+
+    Args:
+        project_dir: The staged ``ios_template`` directory.
+        config: The validated app configuration.
+        log: Optional progress logger.
+
+    Returns:
+        An [`IOSLayout`][pythonnative.project.ios.IOSLayout].
+    """
+    emit: Logger = log or (lambda _message: None)
+    project_dir = Path(project_dir)
+    info_plist = project_dir / "ios_template" / "Info.plist"
+
+    configure_info_plist(info_plist, config)
+    _apply_branding(project_dir, config, emit)
+
+    emit(f"Configured iOS project ({config.bundle_id}).")
+    return IOSLayout(project_dir=project_dir, info_plist=info_plist, bundle_id=config.bundle_id)
+
+
+# ======================================================================
+# Info.plist
+# ======================================================================
+
+
+def configure_info_plist(info_plist: Path, config: AppConfig) -> None:
+    """Write display name, orientation, permissions, and extras to the plist.
+
+    Args:
+        info_plist: Path to the app ``Info.plist``.
+        config: The validated app configuration.
+    """
+    with open(info_plist, "rb") as handle:
+        plist = plistlib.load(handle)
+
+    plist["CFBundleDisplayName"] = config.display_name
+    plist["CFBundleName"] = config.name
+
+    orientations = _ORIENTATIONS.get(config.orientation, _ORIENTATIONS["portrait"])
+    plist["UISupportedInterfaceOrientations"] = list(orientations)
+    plist["UISupportedInterfaceOrientations~ipad"] = list(orientations)
+
+    resolved = config.resolved_permissions()
+    for key, reason in resolved.ios_usage_descriptions.items():
+        plist[key] = reason
+    if resolved.ios_background_modes:
+        plist["UIBackgroundModes"] = list(resolved.ios_background_modes)
+
+    if config.splash:
+        plist["UILaunchStoryboardName"] = "LaunchScreen"
+
+    for key, value in config.ios.extra_info_plist.items():
+        plist[key] = value
+
+    with open(info_plist, "wb") as handle:
+        plistlib.dump(plist, handle)
+
+
+# ======================================================================
+# Build settings / export options
+# ======================================================================
+
+
+def build_settings(config: AppConfig, *, for_archive: bool = False) -> List[str]:
+    """Return ``KEY=VALUE`` ``xcodebuild`` overrides for this config.
+
+    Args:
+        config: The validated app configuration.
+        for_archive: When ``True``, include signing settings appropriate
+            for a device archive.
+
+    Returns:
+        A list of ``"SETTING=value"`` strings to append to an
+        ``xcodebuild`` invocation.
+    """
+    orientations = _ORIENTATIONS.get(config.orientation, _ORIENTATIONS["portrait"])
+    orientation_value = " ".join(orientations)
+    settings = [
+        f"PRODUCT_BUNDLE_IDENTIFIER={config.bundle_id}",
+        f"MARKETING_VERSION={config.version}",
+        f"CURRENT_PROJECT_VERSION={config.build}",
+        f"IPHONEOS_DEPLOYMENT_TARGET={config.ios.deployment_target}",
+        f"INFOPLIST_KEY_UISupportedInterfaceOrientations_iPhone={orientation_value}",
+        f"INFOPLIST_KEY_UISupportedInterfaceOrientations_iPad={orientation_value}",
+    ]
+    if config.ios.development_team:
+        settings.append(f"DEVELOPMENT_TEAM={config.ios.development_team}")
+    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:
+    """Write an ``exportOptions.plist`` for ``xcodebuild -exportArchive``.
+
+    Args:
+        config: The validated app configuration.
+        dest: Destination plist path.
+
+    Returns:
+        ``dest``.
+    """
+    signing = config.ios.signing
+    options: Dict[str, object] = {
+        "method": _EXPORT_METHODS.get(signing.export_method, "development"),
+        "compileBitcode": False,
+        "stripSwiftSymbols": True,
+    }
+    if config.ios.development_team:
+        options["teamID"] = config.ios.development_team
+    if signing.provisioning_profile:
+        options["signingStyle"] = "manual"
+        options["provisioningProfiles"] = {config.bundle_id: signing.provisioning_profile}
+    else:
+        options["signingStyle"] = "automatic"
+
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    with open(dest, "wb") as handle:
+        plistlib.dump(options, handle)
+    return dest
+
+
+# ======================================================================
+# Branding
+# ======================================================================
+
+
+def _apply_branding(project_dir: Path, config: AppConfig, emit: Logger) -> None:
+    assets_dir = project_dir / "ios_template" / "Assets.xcassets"
+    icon_path = config.resolve_path(config.icon) if config.icon else None
+    splash_path = config.resolve_path(config.splash) if config.splash else None
+
+    if icon_path and icons.has_source(icon_path):
+        if icons.generate_ios_icons(icon_path, assets_dir / "AppIcon.appiconset"):
+            emit("Generated iOS app icon.")
+        else:
+            emit("Skipping iOS icon: Pillow not installed (pip install 'pythonnative[build]').")
+
+    if splash_path and icons.has_source(splash_path):
+        if icons.generate_ios_splash(splash_path, assets_dir / "Splash.imageset"):
+            _write_launch_storyboard(project_dir)
+            emit("Configured iOS splash screen.")
+        else:
+            emit("Skipping iOS splash: Pillow not installed (pip install 'pythonnative[build]').")
+
+
+def _write_launch_storyboard(project_dir: Path) -> None:
+    """Overwrite ``LaunchScreen.storyboard`` with a centered splash image."""
+    storyboard = project_dir / "ios_template" / "Base.lproj" / "LaunchScreen.storyboard"
+    storyboard.write_text(_LAUNCH_STORYBOARD, encoding="utf-8")
+
+
+# An edge-pinned image view (aspect-fit) over a white background. The
+# image references the generated "Splash" asset set.
+_LAUNCH_STORYBOARD = """<?xml version="1.0" encoding="UTF-8"?>
+<document type="com.apple.InterfaceBuilder3.CocoaTouch.Storyboard.XIB" version="3.0" toolsVersion="22155" targetRuntime="iOS.CocoaTouch" propertyAccessControl="none" useAutolayout="YES" launchScreen="YES" useTraitCollections="YES" useSafeAreas="YES" colorMatched="YES" initialViewController="01J-lp-oVM">
+    <dependencies>
+        <plugIn identifier="com.apple.InterfaceBuilder.IBCocoaTouchPlugin" version="22131"/>
+        <capability name="Safe area layout guides" minToolsVersion="9.0"/>
+        <capability name="documents saved in the Xcode 8 format" minToolsVersion="8.0"/>
+    </dependencies>
+    <scenes>
+        <scene sceneID="EHf-IW-A2E">
+            <objects>
+                <viewController id="01J-lp-oVM" sceneMemberID="viewController">
+                    <view key="view" contentMode="scaleToFill" id="Ze5-6b-2t3">
+                        <rect key="frame" x="0.0" y="0.0" width="393" height="852"/>
+                        <autoresizingMask key="autoresizingMask" widthSizable="YES" heightSizable="YES"/>
+                        <subviews>
+                            <imageView clipsSubviews="YES" userInteractionEnabled="NO" contentMode="scaleAspectFit" image="Splash" translatesAutoresizingMaskIntoConstraints="NO" id="Spl-aS-h00"/>
+                        </subviews>
+                        <viewLayoutGuide key="safeArea" id="6Tk-OE-BBY"/>
+                        <color key="backgroundColor" systemColor="systemBackgroundColor"/>
+                        <constraints>
+                            <constraint firstItem="Spl-aS-h00" firstAttribute="leading" secondItem="Ze5-6b-2t3" secondAttribute="leading" id="lea-Sp-001"/>
+                            <constraint firstItem="Spl-aS-h00" firstAttribute="trailing" secondItem="Ze5-6b-2t3" secondAttribute="trailing" id="tra-Sp-002"/>
+                            <constraint firstItem="Spl-aS-h00" firstAttribute="top" secondItem="Ze5-6b-2t3" secondAttribute="top" id="top-Sp-003"/>
+                            <constraint firstItem="Spl-aS-h00" firstAttribute="bottom" secondItem="Ze5-6b-2t3" secondAttribute="bottom" id="bot-Sp-004"/>
+                        </constraints>
+                    </view>
+                </viewController>
+                <placeholder placeholderIdentifier="IBFirstResponder" id="iYj-Kq-Ea1" userLabel="First Responder" sceneMemberID="firstResponder"/>
+            </objects>
+            <point key="canvasLocation" x="53" y="375"/>
+        </scene>
+    </scenes>
+    <resources>
+        <image name="Splash" width="393" height="393"/>
+    </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

@@ -0,0 +1,343 @@
+"""Cross-platform permission/capability catalog.
+
+PythonNative apps declare the device capabilities they need in a single,
+platform-agnostic ``[permissions]`` table in ``pythonnative.toml``:
+
+```toml
+[permissions]
+camera = "Scan receipts with your camera."
+location_when_in_use = "Show nearby stores."
+notifications = true
+face_id = "Unlock the app with Face ID."
+```
+
+This module maps each high-level capability to the concrete native
+artifacts it requires:
+
+- iOS: one or more ``Info.plist`` *usage description* keys (the strings
+  shown in the system permission prompt), plus optional
+  ``UIBackgroundModes`` entries.
+- Android: one or more ``<uses-permission>`` entries in
+  ``AndroidManifest.xml``.
+
+A capability's value may be either a string (used verbatim as the iOS
+usage description) or ``true`` (use the capability's
+[`default_reason`][pythonnative.project.permissions.Capability]). A value
+of ``false`` disables the capability — useful for switching one off
+without deleting the line.
+
+The catalog is the single source of truth shared by the iOS and Android
+configurators and by ``pn doctor``; adding a capability here is all that
+is required to make it declarable.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Mapping, Tuple, Union
+
+PermissionValue = Union[bool, str]
+"""Type of a value in the ``[permissions]`` table: a reason string or a bool."""
+
+
+@dataclass(frozen=True)
+class Capability:
+    """A declarable device capability and its native requirements.
+
+    Attributes:
+        key: The capability name as written in ``[permissions]``
+            (e.g., ``"camera"``).
+        summary: Human-readable description, shown by ``pn doctor`` and
+            the docs.
+        ios_usage_keys: ``Info.plist`` keys that receive the usage
+            description string (e.g., ``"NSCameraUsageDescription"``).
+        android_permissions: Fully-qualified Android permission names
+            (e.g., ``"android.permission.CAMERA"``).
+        ios_background_modes: ``UIBackgroundModes`` values to add
+            (e.g., ``"location"``).
+        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
+            capability. When ``False`` (e.g., notifications), declaring
+            the capability as ``true`` is sufficient and no string is
+            needed.
+    """
+
+    key: str
+    summary: str
+    ios_usage_keys: Tuple[str, ...] = ()
+    android_permissions: Tuple[str, ...] = ()
+    ios_background_modes: Tuple[str, ...] = ()
+    default_reason: str = ""
+    needs_reason: bool = True
+
+
+def _cap(*args: object, **kwargs: object) -> Capability:
+    return Capability(*args, **kwargs)  # type: ignore[arg-type]
+
+
+# ======================================================================
+# The catalog
+# ======================================================================
+
+CAPABILITIES: Dict[str, Capability] = {
+    c.key: c
+    for c in [
+        Capability(
+            key="camera",
+            summary="Capture photos and video with the device camera.",
+            ios_usage_keys=("NSCameraUsageDescription",),
+            android_permissions=("android.permission.CAMERA",),
+            default_reason="This app uses the camera.",
+        ),
+        Capability(
+            key="microphone",
+            summary="Record audio from the microphone.",
+            ios_usage_keys=("NSMicrophoneUsageDescription",),
+            android_permissions=("android.permission.RECORD_AUDIO",),
+            default_reason="This app uses the microphone.",
+        ),
+        Capability(
+            key="photo_library",
+            summary="Read photos and videos from the photo library.",
+            ios_usage_keys=("NSPhotoLibraryUsageDescription",),
+            android_permissions=(
+                "android.permission.READ_MEDIA_IMAGES",
+                "android.permission.READ_MEDIA_VIDEO",
+            ),
+            default_reason="This app accesses your photo library.",
+        ),
+        Capability(
+            key="photo_library_add",
+            summary="Save photos and videos to the photo library.",
+            ios_usage_keys=("NSPhotoLibraryAddUsageDescription",),
+            android_permissions=(),
+            default_reason="This app saves photos to your library.",
+        ),
+        Capability(
+            key="location_when_in_use",
+            summary="Access location while the app is in the foreground.",
+            ios_usage_keys=("NSLocationWhenInUseUsageDescription",),
+            android_permissions=(
+                "android.permission.ACCESS_FINE_LOCATION",
+                "android.permission.ACCESS_COARSE_LOCATION",
+            ),
+            default_reason="This app uses your location.",
+        ),
+        Capability(
+            key="location_always",
+            summary="Access location in the foreground and background.",
+            ios_usage_keys=(
+                "NSLocationAlwaysAndWhenInUseUsageDescription",
+                "NSLocationWhenInUseUsageDescription",
+            ),
+            android_permissions=(
+                "android.permission.ACCESS_FINE_LOCATION",
+                "android.permission.ACCESS_COARSE_LOCATION",
+                "android.permission.ACCESS_BACKGROUND_LOCATION",
+            ),
+            ios_background_modes=("location",),
+            default_reason="This app uses your location, even in the background.",
+        ),
+        Capability(
+            key="contacts",
+            summary="Read the device address book.",
+            ios_usage_keys=("NSContactsUsageDescription",),
+            android_permissions=("android.permission.READ_CONTACTS",),
+            default_reason="This app accesses your contacts.",
+        ),
+        Capability(
+            key="calendars",
+            summary="Read and write calendar events.",
+            ios_usage_keys=("NSCalendarsUsageDescription",),
+            android_permissions=(
+                "android.permission.READ_CALENDAR",
+                "android.permission.WRITE_CALENDAR",
+            ),
+            default_reason="This app accesses your calendar.",
+        ),
+        Capability(
+            key="reminders",
+            summary="Read and write reminders (iOS only).",
+            ios_usage_keys=("NSRemindersUsageDescription",),
+            android_permissions=(),
+            default_reason="This app accesses your reminders.",
+        ),
+        Capability(
+            key="motion",
+            summary="Access motion and fitness / activity data.",
+            ios_usage_keys=("NSMotionUsageDescription",),
+            android_permissions=("android.permission.ACTIVITY_RECOGNITION",),
+            default_reason="This app uses motion and fitness data.",
+        ),
+        Capability(
+            key="face_id",
+            summary="Authenticate with Face ID / biometrics.",
+            ios_usage_keys=("NSFaceIDUsageDescription",),
+            android_permissions=("android.permission.USE_BIOMETRIC",),
+            default_reason="This app uses Face ID to authenticate you.",
+        ),
+        Capability(
+            key="bluetooth",
+            summary="Communicate with nearby Bluetooth devices.",
+            ios_usage_keys=("NSBluetoothAlwaysUsageDescription",),
+            android_permissions=(
+                "android.permission.BLUETOOTH_CONNECT",
+                "android.permission.BLUETOOTH_SCAN",
+            ),
+            default_reason="This app connects to Bluetooth devices.",
+        ),
+        Capability(
+            key="speech_recognition",
+            summary="Perform speech recognition (iOS only).",
+            ios_usage_keys=("NSSpeechRecognitionUsageDescription",),
+            android_permissions=(),
+            default_reason="This app uses speech recognition.",
+        ),
+        Capability(
+            key="notifications",
+            summary="Show local and push notifications.",
+            ios_usage_keys=(),
+            android_permissions=("android.permission.POST_NOTIFICATIONS",),
+            needs_reason=False,
+        ),
+        Capability(
+            key="vibration",
+            summary="Trigger haptic feedback / vibration.",
+            ios_usage_keys=(),
+            android_permissions=("android.permission.VIBRATE",),
+            needs_reason=False,
+        ),
+        Capability(
+            key="background_audio",
+            summary="Continue playing audio in the background (iOS).",
+            ios_usage_keys=(),
+            ios_background_modes=("audio",),
+            android_permissions=("android.permission.FOREGROUND_SERVICE",),
+            needs_reason=False,
+        ),
+        Capability(
+            key="background_fetch",
+            summary="Perform periodic background fetches (iOS).",
+            ios_usage_keys=(),
+            ios_background_modes=("fetch",),
+            android_permissions=(),
+            needs_reason=False,
+        ),
+    ]
+}
+"""Mapping of capability key → [`Capability`][pythonnative.project.permissions.Capability]."""
+
+
+# Permissions every app gets, regardless of declared capabilities. Both are
+# "normal" (install-time) Android permissions that never prompt the user, and
+# nearly every PythonNative app needs the network (``fetch``, ``use_query``,
+# ``NetInfo``, remote images).
+BASE_ANDROID_PERMISSIONS: Tuple[str, ...] = (
+    "android.permission.INTERNET",
+    "android.permission.ACCESS_NETWORK_STATE",
+)
+"""Android permissions added to every app (network access)."""
+
+
+@dataclass
+class ResolvedPermissions:
+    """The native permission artifacts for a resolved capability set.
+
+    Attributes:
+        ios_usage_descriptions: ``Info.plist`` usage-description keys
+            mapped to their reason strings.
+        ios_background_modes: Ordered, de-duplicated ``UIBackgroundModes``
+            values.
+        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)
+    android_permissions: List[str] = field(default_factory=list)
+
+
+def unknown_capabilities(keys: object) -> List[str]:
+    """Return any declared capability keys that aren't in the catalog.
+
+    Args:
+        keys: An iterable of capability key strings.
+
+    Returns:
+        The subset of ``keys`` not present in
+        [`CAPABILITIES`][pythonnative.project.permissions.CAPABILITIES],
+        in input order.
+    """
+    result: List[str] = []
+    for key in keys:
+        if key not in CAPABILITIES:
+            result.append(str(key))
+    return result
+
+
+def resolve_permissions(
+    permissions: Mapping[str, PermissionValue],
+    *,
+    extra_android_permissions: object = (),
+) -> ResolvedPermissions:
+    """Resolve a declared capability map into native permission artifacts.
+
+    Args:
+        permissions: The ``[permissions]`` table — capability key to a
+            reason string or boolean. ``false``/``None`` values are
+            skipped (capability disabled).
+        extra_android_permissions: Additional raw Android permission
+            names (e.g., from ``[android].permissions``) to append.
+
+    Returns:
+        A [`ResolvedPermissions`][pythonnative.project.permissions.ResolvedPermissions]
+        with iOS usage descriptions, iOS background modes, and the full
+        ordered Android permission list (base set first).
+
+    Raises:
+        ValueError: If an unknown capability key is present. Validate
+            earlier with
+            [`unknown_capabilities`][pythonnative.project.permissions.unknown_capabilities]
+            for a friendlier error.
+    """
+    resolved = ResolvedPermissions()
+    android: List[str] = list(BASE_ANDROID_PERMISSIONS)
+    background: List[str] = []
+
+    for key, value in permissions.items():
+        if key not in CAPABILITIES:
+            raise ValueError(f"Unknown capability: {key!r}")
+        if value is False or value is None:
+            continue
+        cap = CAPABILITIES[key]
+        reason = value if isinstance(value, str) and value.strip() else cap.default_reason
+        for plist_key in cap.ios_usage_keys:
+            # First declaration wins for a shared key (e.g. location_*).
+            resolved.ios_usage_descriptions.setdefault(plist_key, reason)
+        for mode in cap.ios_background_modes:
+            if mode not in background:
+                background.append(mode)
+        for perm in cap.android_permissions:
+            if perm not in android:
+                android.append(perm)
+
+    for perm in extra_android_permissions:
+        if perm and perm not in android:
+            android.append(str(perm))
+
+    resolved.ios_background_modes = background
+    resolved.android_permissions = android
+    return resolved
+
+
+def describe_catalog() -> str:
+    """Return a multi-line, human-readable listing of all capabilities.
+
+    Used by ``pn doctor`` / docs tooling to show what can be declared.
+    """
+    lines: List[str] = []
+    for key in sorted(CAPABILITIES):
+        cap = CAPABILITIES[key]
+        lines.append(f"  {key:<22} {cap.summary}")
+    return "\n".join(lines)