pythonnative 0.37.0__py3-none-any.whl → 0.38.0__py3-none-any.whl

pythonnative/native_modules/permissions.py

@@ -4,7 +4,7 @@
 iOS and Android permission models behind two calls, both served by the
 native ``Permissions`` module:
 
-- ``check(permission)``: synchronous, returns a status string without
+- ``check(permission)``: synchronous, returns a status without
   prompting.
 - ``request(permission)``: a coroutine that shows the system prompt
   (if needed) and resolves to the resulting status.
@@ -12,27 +12,62 @@ native ``Permissions`` module:
 Statuses are ``"granted"``, ``"denied"``, ``"blocked"`` (denied with
 "don't ask again" / Settings required), or ``"undetermined"``.
 
-Supported ``permission`` names: ``"camera"``, ``"microphone"``,
-``"location"``, ``"photos"``, ``"notifications"``, ``"contacts"``.
-Unknown names resolve to ``"undetermined"``.
+Permission names are the same words you declare in the
+``[permissions]`` table of ``pythonnative.toml``, so the string that
+puts ``NSCameraUsageDescription`` in your Info.plist is the string you
+pass here: ``"camera"``, ``"microphone"``, ``"photo_library"``,
+``"location_when_in_use"``, ``"contacts"``, ``"notifications"``. The
+full list is [`RUNTIME_PERMISSIONS`][pythonnative.native_modules.permissions.RUNTIME_PERMISSIONS];
+capabilities that have no runtime prompt (``vibration``,
+``background_fetch``, ...) are declared in the config only. A name
+outside the list raises ``ValueError`` before anything reaches native.
+
+Example:
+    ```python
+    import pythonnative as pn
+
+    async def scan():
+        if await pn.Permissions.request("camera") != "granted":
+            return
+        await pn.Camera.take_photo()
+    ```
 """
 
 from __future__ import annotations
 
+from typing import Literal
+
 from .registry import native_module
 
-PermissionStatus = str
-PermissionName = str
+PermissionStatus = Literal["granted", "denied", "blocked", "undetermined"]
+"""Outcome of a check or request."""
+
+PermissionName = Literal[
+    "camera",
+    "microphone",
+    "photo_library",
+    "location_when_in_use",
+    "contacts",
+    "notifications",
+]
+"""A capability that has a runtime prompt; the same names as ``[permissions]`` in ``pythonnative.toml``."""
 
-GRANTED = "granted"
-DENIED = "denied"
-BLOCKED = "blocked"
-UNDETERMINED = "undetermined"
+GRANTED: PermissionStatus = "granted"
+DENIED: PermissionStatus = "denied"
+BLOCKED: PermissionStatus = "blocked"
+UNDETERMINED: PermissionStatus = "undetermined"
 
 _STATUSES = (GRANTED, DENIED, BLOCKED, UNDETERMINED)
 
-PERMISSION_NAMES = ("camera", "microphone", "location", "photos", "notifications", "contacts")
-"""Permission names understood by every platform."""
+RUNTIME_PERMISSIONS = (
+    "camera",
+    "microphone",
+    "photo_library",
+    "location_when_in_use",
+    "contacts",
+    "notifications",
+)
+"""Every permission name ``check`` / ``request`` accept, in the ``[permissions]`` vocabulary."""
 
 
 def _coerce(value: object) -> PermissionStatus:
@@ -40,21 +75,34 @@ def _coerce(value: object) -> PermissionStatus:
     return status if status in _STATUSES else UNDETERMINED
 
 
+def _validate(permission: str) -> str:
+    if permission not in RUNTIME_PERMISSIONS:
+        raise ValueError(
+            f"Unknown permission {permission!r}. Use one of {', '.join(RUNTIME_PERMISSIONS)} "
+            "(the same names as [permissions] in pythonnative.toml)."
+        )
+    return permission
+
+
 class Permissions:
-    """Runtime permission interface."""
+    """Runtime permission interface.
+
+    Raises:
+        ValueError: For a permission name outside
+            [`RUNTIME_PERMISSIONS`][pythonnative.native_modules.permissions.RUNTIME_PERMISSIONS].
+        NativeModuleError: If the native module fails.
+    """
 
     @staticmethod
     def check(permission: PermissionName) -> PermissionStatus:
         """Return the current status of ``permission`` without prompting."""
-        try:
-            return _coerce(native_module("Permissions").call("check", permission=permission))
-        except Exception:
-            return UNDETERMINED
+        return _coerce(native_module("Permissions").call("check", permission=_validate(permission)))
 
     @staticmethod
     async def request(permission: PermissionName) -> PermissionStatus:
-        """Prompt for ``permission`` (if needed) and return the result."""
-        try:
-            return _coerce(await native_module("Permissions").call_async("request", permission=permission))
-        except Exception:
-            return UNDETERMINED
+        """Prompt for ``permission`` (if needed) and return the result.
+
+        Off device (``pn preview``, tests) the answer is always
+        ``"undetermined"``: there is no prompt to show.
+        """
+        return _coerce(await native_module("Permissions").call_async("request", permission=_validate(permission)))

pythonnative/native_modules/secure_store.py

@@ -6,10 +6,10 @@ native ``SecureStore`` module), the right place for auth tokens and
 other secrets that [`AsyncStorage`][pythonnative.AsyncStorage] (plain,
 unencrypted) should never hold.
 
-All methods are synchronous and return a ``bool`` (writes/deletes) or
-``Optional[str]`` (reads). On desktop the module falls back to an
-in-process dict so code paths stay exercisable without a device
-Keychain.
+Both backing stores complete on the calling thread, so every method is
+synchronous. Reads return ``Optional[str]``; writes return nothing and
+raise on failure. On desktop the module falls back to an in-process dict
+so code paths stay exercisable without a device Keychain.
 
 Example:
     ```python
@@ -28,29 +28,25 @@ from .registry import native_module
 
 
 class SecureStore:
-    """Encrypted secret storage (synchronous)."""
+    """Encrypted secret storage (synchronous).
+
+    Raises:
+        NativeModuleError: If the Keychain / EncryptedSharedPreferences
+            operation fails (for example a Keychain entitlement problem).
+    """
 
     @staticmethod
-    def set_item(key: str, value: str) -> bool:
-        """Store ``value`` under ``key``. Returns ``True`` on success."""
-        try:
-            return bool(native_module("SecureStore").call("set_item", key=key, value=value))
-        except Exception:
-            return False
+    def set_item(key: str, value: str) -> None:
+        """Store ``value`` under ``key``, replacing any previous value."""
+        native_module("SecureStore").call("set_item", key=key, value=value)
 
     @staticmethod
     def get_item(key: str) -> Optional[str]:
         """Return the value for ``key``, or ``None`` if absent."""
-        try:
-            value = native_module("SecureStore").call("get_item", key=key)
-        except Exception:
-            return None
+        value = native_module("SecureStore").call("get_item", key=key)
         return None if value is None else str(value)
 
     @staticmethod
     def delete_item(key: str) -> bool:
-        """Delete ``key``. Returns ``True`` if it existed and was removed."""
-        try:
-            return bool(native_module("SecureStore").call("delete_item", key=key))
-        except Exception:
-            return False
+        """Delete ``key``. Returns ``True`` if it existed, ``False`` if there was nothing to delete."""
+        return bool(native_module("SecureStore").call("delete_item", key=key))

pythonnative/native_modules/share.py

@@ -43,9 +43,9 @@ class Share:
 
         Returns:
             ``True`` if the user completed a share, ``False`` if they
-            cancelled or no share UI is available.
+            dismissed the sheet or the platform has no share UI (desktop).
+
+        Raises:
+            NativeModuleError: If the sheet could not be presented.
         """
-        try:
-            return bool(await native_module("Share").call_async("share", message=message, url=url, title=title))
-        except Exception:
-            return False
+        return bool(await native_module("Share").call_async("share", message=message, url=url, title=title))

pythonnative/navigation/__init__.py

@@ -66,7 +66,7 @@ from .navigators import (
     create_tab_navigator,
 )
 from .screen import HeaderSlot, ScreenDef, ScreenOptions
-from .state import NavigationState, Route
+from .state import NavigationState, Route, RouteParams
 
 __all__ = [
     "NAV_STATE_ARG",
@@ -87,6 +87,7 @@ __all__ = [
     "NavigationState",
     "NavigatorCore",
     "Route",
+    "RouteParams",
     "ScreenDef",
     "ScreenOptions",
     "StackNavigator",

pythonnative/navigation/hooks.py

@@ -2,11 +2,11 @@
 
 from __future__ import annotations
 
-from typing import Any, Callable, Optional, Sequence
+from typing import Any, Callable, Dict, Optional, Sequence, overload
 
 from ..hooks import use_context, use_effect
 from .handle import FocusContext, Navigation, NavigationContext
-from .state import Route
+from .state import Route, RouteParams
 
 __all__ = ["use_focus_effect", "use_is_focused", "use_navigation", "use_route"]
 
@@ -34,25 +34,64 @@ def use_navigation() -> Navigation:
     return nav
 
 
-def use_route() -> Route:
+@overload
+def use_route() -> Route[Dict[str, Any]]: ...
+
+
+@overload
+def use_route[P: RouteParams](params_type: type[P], /) -> Route[P]: ...
+
+
+def use_route(params_type: Optional[type] = None, /) -> Route[Any]:
     """Return the current screen's [`Route`][pythonnative.navigation.Route].
 
+    Pass a ``TypedDict`` class as ``params_type`` to get a
+    ``Route[MyParams]`` whose ``params`` attribute is typed for editors
+    and type checkers. At runtime the hook also verifies that every
+    *required* key of the ``TypedDict`` is present on the active route,
+    so a screen opened with the wrong params fails at its first render
+    with a message naming the missing keys, instead of a ``KeyError``
+    deep inside the render.
+
     Outside any navigator a placeholder route named ``"__root__"`` with
-    empty params is returned, so components can be rendered standalone
-    (previews, tests) without special-casing.
+    empty params is returned (and no validation is performed), so
+    components can be rendered standalone (previews, tests) without
+    special-casing.
+
+    Args:
+        params_type: Optional ``TypedDict`` describing this screen's
+            params.
+
+    Raises:
+        TypeError: If the active route is missing a required param
+            declared by ``params_type``.
 
     Example:
         ```python
+        class DetailParams(TypedDict):
+            id: int
+            title: NotRequired[str]
+
         @pn.component
         def DetailScreen():
-            route = pn.use_route()
+            route = pn.use_route(DetailParams)
             return pn.Text(f"Item {route.params['id']}")
         ```
     """
     nav = use_context(NavigationContext)
     if nav is None:
         return Route("__root__", {}, key="__root__")
-    return nav.route
+    route = nav.route
+    if params_type is not None:
+        required = getattr(params_type, "__required_keys__", None)
+        if required:
+            missing = sorted(k for k in required if k not in route.params)
+            if missing:
+                raise TypeError(
+                    f"Screen {route.name!r} is missing required params {missing} "
+                    f"declared by {params_type.__name__}; got {sorted(route.params)}"
+                )
+    return route
 
 
 def use_is_focused() -> bool:

pythonnative/navigation/state.py

@@ -15,9 +15,16 @@ pushed screen the full history it belongs to.
 from __future__ import annotations
 
 import itertools
-from typing import Any, Dict, Iterable, Iterator, Mapping, Optional, Sequence, Tuple
+from typing import Any, Dict, Iterable, Iterator, Mapping, Optional, Sequence, Tuple, cast
 
-__all__ = ["NavigationState", "Route"]
+__all__ = ["NavigationState", "Route", "RouteParams"]
+
+type RouteParams = Mapping[str, Any]
+"""Bound for the ``P`` type parameter of [`Route`][pythonnative.navigation.Route].
+
+Declare a screen's params as a ``TypedDict`` and read them with
+``use_route(MyParams)`` for a fully typed ``route.params``.
+"""
 
 _route_keys = itertools.count(1)
 
@@ -26,13 +33,27 @@ def _new_key(name: str) -> str:
     return f"{name}-{next(_route_keys)}"
 
 
-class Route:
+class Route[P: RouteParams = Dict[str, Any]]:
     """One entry in a navigator's state.
 
+    ``Route`` is generic in its params type. Bare ``Route`` is
+    ``Route[dict[str, Any]]``; pass a ``TypedDict`` to
+    [`use_route`][pythonnative.use_route] to get ``Route[MyParams]``
+    with a typed ``params`` attribute:
+
+    ```python
+    class DetailParams(TypedDict):
+        id: int
+
+    route = pn.use_route(DetailParams)
+    route.params["id"]  # int
+    ```
+
     Attributes:
         name: The screen name this route renders.
         params: Parameters passed to the screen (read with
-            [`use_route`][pythonnative.use_route]).
+            [`use_route`][pythonnative.use_route]). Always a plain
+            ``dict`` at runtime.
         key: Stable identity for this particular visit to the screen,
             unique per process. Two pushes of the same screen have
             different keys, so their component state never mixes.
@@ -51,16 +72,16 @@ class Route:
         state: Optional["NavigationState"] = None,
     ) -> None:
         self.name = name
-        self.params: Dict[str, Any] = dict(params or {})
+        self.params: P = cast(P, dict(params or {}))
         self.key = key or _new_key(name)
         self.state = state
 
-    def with_params(self, params: Mapping[str, Any], *, merge: bool = True) -> "Route":
+    def with_params(self, params: Mapping[str, Any], *, merge: bool = True) -> "Route[P]":
         """Return a copy carrying ``params`` (merged over the current ones by default)."""
         merged = {**self.params, **params} if merge else dict(params)
         return Route(self.name, merged, key=self.key, state=self.state)
 
-    def with_state(self, state: Optional["NavigationState"]) -> "Route":
+    def with_state(self, state: Optional["NavigationState"]) -> "Route[P]":
         """Return a copy carrying a nested navigator seed ``state``."""
         return Route(self.name, self.params, key=self.key, state=state)
 
@@ -72,11 +93,11 @@ class Route:
         return out
 
     @classmethod
-    def from_dict(cls, data: Mapping[str, Any]) -> "Route":
+    def from_dict(cls, data: Mapping[str, Any]) -> "Route[Dict[str, Any]]":
         """Rebuild a route from ``to_dict`` output, keeping its ``key`` so component state carries over."""
         params = data.get("params")
         nested = data.get("state")
-        return cls(
+        return Route(
             str(data["name"]),
             params if isinstance(params, Mapping) else {},
             key=data.get("key"),

pythonnative/project/android.py

@@ -186,12 +186,35 @@ def configure_gradle(project_dir: Path, config: AppConfig) -> None:
     abi_csv = ", ".join(f'"{abi}"' for abi in config.android.abi_filters)
     content = re.sub(r"abiFilters[^\n]*", f"abiFilters {abi_csv}", content)
 
+    if config.extra_index_urls:
+        content = _inject_pip_options(content, config)
+
     if config.android.signing.is_configured:
         content = _inject_signing(content, config)
 
     gradle_path.write_text(content, encoding="utf-8")
 
 
+def _inject_pip_options(content: str, config: AppConfig) -> str:
+    """Add ``--extra-index-url`` pip options for ``[requirements].extra_index_urls``.
+
+    Chaquopy runs pip at Gradle build time; ``options`` lines inside the
+    ``pip { }`` block are passed straight through, so a private index
+    declared once in ``pythonnative.toml`` applies to Android too.
+    """
+    marker = '                install "-r", "requirements.txt"'
+    if marker not in content:
+        return content
+    lines = "".join(
+        f'                options "--extra-index-url", "{_gradle_escape(url)}"\n' for url in config.extra_index_urls
+    )
+    return content.replace(marker, lines + marker, 1)
+
+
+def _gradle_escape(value: str) -> str:
+    return value.replace("\\", "\\\\").replace('"', '\\"')
+
+
 def _inject_signing(content: str, config: AppConfig) -> str:
     signing = config.android.signing
     assert signing.keystore is not None and signing.key_alias is not None

pythonnative/project/builder.py

@@ -10,6 +10,10 @@ On iOS, the staged project is self-contained: ``Python.xcframework`` is
 linked at build time and an Xcode build phase installs the standard
 library and app code into the bundle, so ``xcodebuild`` output is
 directly runnable and archivable with no post-build patching.
+Third-party packages are resolved per destination (see
+[`deps`][pythonnative.project.deps]) into ``app_packages.iphoneos`` and
+``app_packages.iphonesimulator``; the build phase installs the slice
+matching the SDK being built.
 
 All shell-outs go through a small
 [`CommandRunner`][pythonnative.project.builder.CommandRunner] abstraction
@@ -37,9 +41,9 @@ from pathlib import Path
 from typing import Callable, List, Optional, Sequence, Union
 
 from . import android as android_config
+from . import deps, runtime_assets
 from . import ios as ios_config
 from . import plugins as native_plugins
-from . import runtime_assets
 from .android import AndroidLayout
 from .config import AppConfig
 from .ios import IOSLayout
@@ -272,7 +276,13 @@ class Builder:
 
     # -- Preparation ----------------------------------------------------
 
-    def prepare(self, platform: str, *, release: bool = False) -> PreparedProject:
+    def prepare(
+        self,
+        platform: str,
+        *,
+        release: bool = False,
+        ios_sdks: Sequence[str] = deps.IOS_SDKS,
+    ) -> PreparedProject:
         """Stage and configure the native project for ``platform``.
 
         Args:
@@ -281,12 +291,20 @@ class Builder:
                 byte-compiles the staged Python code and drops the
                 ``.py`` sources from the bundle. (Chaquopy does the
                 equivalent on Android automatically.)
+            ios_sdks: Which iOS SDKs to resolve third-party packages
+                for: ``"iphoneos"`` (devices, archives) and/or
+                ``"iphonesimulator"``. Each becomes an
+                ``app_packages.<sdk>`` slice in the staged project.
+                Defaults to both; the CLI narrows it to the destination
+                it is about to build so a package that only has a
+                Simulator wheel doesn't block a Simulator run.
 
         Returns:
             A [`PreparedProject`][pythonnative.project.builder.PreparedProject].
 
         Raises:
-            BuildError: For an unknown platform or a staging failure.
+            BuildError: For an unknown platform, a staging failure, or a
+                requirement with no wheel for a requested iOS SDK.
         """
         if platform not in _TEMPLATE_NAMES:
             raise BuildError(f"Unknown platform: {platform!r} (expected 'android' or 'ios').")
@@ -314,7 +332,7 @@ class Builder:
 
         ios_layout = ios_config.configure(project_dir, self.config, log=self.log)
         native_plugins.stage_ios_plugins(project_dir, plugins, log=self.log)
-        self._stage_ios_python(project_dir, release=release)
+        self._stage_ios_python(project_dir, release=release, sdks=ios_sdks)
         self._link_ios_runtime(project_dir)
         return PreparedProject(
             platform=platform,
@@ -338,46 +356,57 @@ class Builder:
         except native_plugins.PluginError as exc:
             raise BuildError(f"Invalid native plugin: {exc}") from exc
 
-    def _stage_ios_python(self, project_dir: Path, *, release: bool) -> None:
-        """Stage ``app/`` and ``app_packages/`` at the Xcode project root.
+    def _stage_ios_python(self, project_dir: Path, *, release: bool, sdks: Sequence[str]) -> None:
+        """Stage ``app/`` and one ``app_packages.<sdk>/`` slice per SDK.
 
-        The Xcode project references both folders as bundle resources
-        and the "Install Python runtime" build phase converts any
-        binary modules inside them into signed frameworks.
+        ``app/`` is a bundle resource. The package slices are not: the
+        "Install Python runtime" build phase copies the slice matching
+        ``EFFECTIVE_PLATFORM_NAME`` into the bundle as ``app_packages``
+        and converts any binary modules inside it into signed
+        frameworks. Every slice carries the ``pythonnative`` package
+        (pure Python) plus the project's requirements resolved for that
+        SDK's wheel tags.
         """
         app_dir = project_dir / "app"
-        packages_dir = project_dir / "app_packages"
-        for directory in (app_dir, packages_dir):
-            if directory.exists():
-                shutil.rmtree(directory)
-            directory.mkdir(parents=True, exist_ok=True)
+        if app_dir.exists():
+            shutil.rmtree(app_dir)
+        for stale in project_dir.glob("app_packages*"):
+            if stale.is_dir():
+                shutil.rmtree(stale)
+            else:
+                stale.unlink()
 
         app_src = self.config.project_root / "app"
         if not app_src.is_dir():
             raise BuildError(f"No app/ directory found at {app_src}; nothing to bundle.")
-        shutil.copytree(app_src, app_dir, dirs_exist_ok=True)
-
-        if self.dev_lib_root.is_dir():
-            shutil.copytree(
-                self.dev_lib_root,
-                packages_dir / "pythonnative",
-                dirs_exist_ok=True,
-                ignore=android_config.LIB_IGNORE,
-            )
-
-        # The framework has no Python-side native dependencies (the
-        # bridge into PythonNativeKit is ctypes); only user requirements
-        # are installed into the site directory.
-        if self.config.requirements:
-            result = self.runner.run(
-                [sys.executable, "-m", "pip", "install", "-t", str(packages_dir), *self.config.requirements],
-                capture=True,
-            )
-            if not result.ok:
-                raise BuildError(f"pip install of [requirements].packages failed:\n{result.stderr}")
+        shutil.copytree(app_src, app_dir)
+
+        slices: List[Path] = []
+        for target in deps.ios_targets(self.config, sdks=sdks):
+            packages_dir = project_dir / target.slice_name
+            packages_dir.mkdir(parents=True, exist_ok=True)
+            slices.append(packages_dir)
+
+            # The framework has no Python-side native dependencies (the
+            # bridge into PythonNativeKit is ctypes), so it is copied
+            # verbatim into every slice.
+            if self.dev_lib_root.is_dir():
+                shutil.copytree(
+                    self.dev_lib_root,
+                    packages_dir / "pythonnative",
+                    dirs_exist_ok=True,
+                    ignore=android_config.LIB_IGNORE,
+                )
+
+            if self.config.requirements:
+                self.log(f"Resolving {len(self.config.requirements)} requirement(s) for {target.label}...")
+                try:
+                    deps.install(self.config, target, packages_dir, runner=self.runner)
+                except deps.DependencyError as exc:
+                    raise BuildError(str(exc)) from exc
 
         if release:
-            self._compile_ios_bytecode(app_dir, packages_dir)
+            self._compile_ios_bytecode(app_dir, *slices)
 
     def _compile_ios_bytecode(self, *roots: Path) -> None:
         """Byte-compile staged Python code and drop the ``.py`` sources.