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

pythonnative/native_modules/__init__.py

@@ -1,11 +1,21 @@
 """Native API modules for device capabilities.
 
-Provides cross-platform Python interfaces to common device APIs. Each
-module auto-detects the platform at import time and dispatches to the
-appropriate native APIs via Chaquopy (Android) or rubicon-objc (iOS).
-On a desktop machine without either runtime, modules fall back to safe
-defaults (in-memory buffers, ``"unknown"`` states, no-op feedback) so
-the same code stays runnable in the desktop mock and unit tests.
+Cross-platform Python interfaces to common device APIs. Every module
+here is a thin facade over a *native module*: a Swift class in
+``PythonNativeKit`` and a Kotlin class in the ``pythonnative`` Gradle
+module registered under the same name (``"Camera"``, ``"Haptics"``,
+...). Facades reach them through
+[`native_module`][pythonnative.native_modules.registry.native_module]
+and the bridge described in ``docs/concepts/bridge.md``; there is no
+Python-side Objective-C or JNI anywhere in this package.
+
+On a desktop machine (``pn preview``, unit tests) the same names
+resolve to plain Python implementations in
+[`pythonnative.native_modules.desktop`][pythonnative.native_modules.desktop]
+with safe defaults (in-memory buffers, ``"unknown"`` states, no-op
+feedback), so the same code stays runnable off device. Third-party
+packages ship their own native modules the same way; see
+``docs/guides/native-modules.md``.
 
 Hardware / media:
 
@@ -43,8 +53,6 @@ Reactive state (with hooks):
   [`use_net_info`][pythonnative.use_net_info]: connectivity.
 """
 
-from typing import Any, Sequence
-
 from .app_state import AppState, use_app_state
 from .battery import Battery
 from .biometrics import Biometrics
@@ -57,46 +65,39 @@ from .location import Location
 from .net_info import NetInfo, use_net_info
 from .notifications import Notifications
 from .permissions import Permissions
+from .registry import (
+    BridgeModule,
+    NativeModule,
+    NativeModuleError,
+    PythonModule,
+    native_module,
+    register_python_module,
+)
 from .secure_store import SecureStore
 from .share import Share
 
-
-def dispatch_activity_result(request_code: int, result_code: int, data: Any) -> bool:
-    """Route an Android ``onActivityResult`` to whichever module is waiting on it.
-
-    Called by the screen host. Returns ``True`` when a pending request
-    consumed the result.
-    """
-    from .camera import deliver_android_activity_result
-
-    return deliver_android_activity_result(request_code, result_code, data)
-
-
-def dispatch_permissions_result(request_code: int, permissions: Sequence[str], grant_results: Sequence[int]) -> bool:
-    """Route an Android ``onRequestPermissionsResult`` to the pending ``Permissions.request``."""
-    from .permissions import deliver_android_permission_result
-
-    return deliver_android_permission_result(request_code, permissions, grant_results)
-
-
 __all__ = [
     "AppState",
     "Battery",
     "Biometrics",
+    "BridgeModule",
     "Camera",
     "Clipboard",
     "FileSystem",
     "Haptics",
     "Linking",
     "Location",
+    "NativeModule",
+    "NativeModuleError",
     "NetInfo",
     "Notifications",
     "Permissions",
+    "PythonModule",
     "SecureStore",
     "Share",
     "Vibration",
-    "dispatch_activity_result",
-    "dispatch_permissions_result",
+    "native_module",
+    "register_python_module",
     "use_app_state",
     "use_net_info",
 ]

pythonnative/native_modules/app_state.py

@@ -2,10 +2,10 @@
 
 [`AppState`][pythonnative.AppState] exposes the current lifecycle phase
 (``"active"``, ``"inactive"``, or ``"background"``) and lets you
-subscribe to transitions. The native host (the iOS app delegate /
-Android ``Activity``) forwards lifecycle callbacks by calling
-[`dispatch_app_state`][pythonnative.native_modules.app_state.dispatch_app_state],
-so the same listener machinery works on every platform and in tests.
+subscribe to transitions. The native ``AppState`` module pushes a
+``change`` event on every transition; off device, tests drive the same
+path through
+[`dispatch_app_state`][pythonnative.native_modules.app_state.dispatch_app_state].
 
 Prefer the [`use_app_state`][pythonnative.use_app_state] hook inside
 components; use the imperative API for non-UI code.
@@ -27,6 +27,7 @@ from typing import Callable, List
 
 from .. import diagnostics
 from ..hooks import use_effect, use_state
+from .registry import on_event
 
 AppStateStatus = str  # "active" | "inactive" | "background"
 
@@ -64,8 +65,8 @@ class AppState:
 def dispatch_app_state(state: AppStateStatus) -> None:
     """Update the current state and notify every listener.
 
-    Called by the native host on lifecycle transitions. Unknown values
-    are ignored so a misbehaving host can't push garbage into the tree.
+    Unknown values are ignored so a misbehaving host can't push garbage
+    into the tree.
     """
     global _current
     if state not in _VALID or state == _current:
@@ -78,6 +79,9 @@ def dispatch_app_state(state: AppStateStatus) -> None:
             diagnostics.swallowed("app_state.dispatch_app_state")
 
 
+on_event("AppState", "change", lambda payload: dispatch_app_state(str(payload)))
+
+
 def use_app_state() -> AppStateStatus:
     """Subscribe a component to [`AppState`][pythonnative.AppState].
 

pythonnative/native_modules/battery.py

@@ -2,16 +2,18 @@
 
 [`Battery`][pythonnative.Battery] reports the current charge fraction
 (``0.0``–``1.0``, or ``-1.0`` when unknown) and charging state, and
-lets you subscribe to changes that the native host forwards via
+lets you subscribe to changes. The native ``Battery`` module pushes a
+``change`` event with ``{"level", "state"}``; off device, tests drive
+the same path through
 [`dispatch_battery`][pythonnative.native_modules.battery.dispatch_battery].
 """
 
 from __future__ import annotations
 
-from typing import Callable, Dict, List
+from typing import Any, Callable, Dict, List
 
 from .. import diagnostics
-from ..utils import IS_ANDROID, IS_IOS
+from .registry import native_module, on_event
 
 BatteryState = str  # "unknown" | "unplugged" | "charging" | "full"
 
@@ -24,20 +26,20 @@ class Battery:
     @staticmethod
     def get_level() -> float:
         """Return the charge fraction in ``[0, 1]`` (``-1.0`` if unknown)."""
-        if IS_IOS:
-            return _ios_level()
-        if IS_ANDROID:
-            return _android_level()
-        return -1.0
+        try:
+            level = float(native_module("Battery").call("get_level"))
+        except Exception:
+            return -1.0
+        return level if 0.0 <= level <= 1.0 else -1.0
 
     @staticmethod
     def get_state() -> BatteryState:
         """Return ``"charging"`` / ``"full"`` / ``"unplugged"`` / ``"unknown"``."""
-        if IS_IOS:
-            return _ios_state()
-        if IS_ANDROID:
-            return _android_state()
-        return "unknown"
+        try:
+            state = str(native_module("Battery").call("get_state") or "unknown")
+        except Exception:
+            return "unknown"
+        return state if state in ("unknown", "unplugged", "charging", "full") else "unknown"
 
     @staticmethod
     def add_listener(callback: Callable[[Dict[str, object]], None]) -> Callable[[], None]:
@@ -57,7 +59,7 @@ class Battery:
 
 
 def dispatch_battery(level: float, state: BatteryState) -> None:
-    """Notify listeners of a battery change (called by the native host)."""
+    """Notify listeners of a battery change."""
     payload: Dict[str, object] = {"level": level, "state": state}
     for listener in list(_listeners):
         try:
@@ -66,75 +68,9 @@ def dispatch_battery(level: float, state: BatteryState) -> None:
             diagnostics.swallowed("battery.dispatch_battery")
 
 
-# ======================================================================
-# iOS: UIDevice
-# ======================================================================
-
-
-def _ios_device() -> object:
-    from rubicon.objc import ObjCClass
-
-    device = ObjCClass("UIDevice").currentDevice
-    try:
-        device.setBatteryMonitoringEnabled_(True)
-    except Exception:
-        diagnostics.swallowed("battery._ios_device")
-    return device
-
-
-def _ios_level() -> float:
-    try:
-        level = float(_ios_device().batteryLevel)
-        return level if level >= 0 else -1.0
-    except Exception:
-        return -1.0
-
-
-def _ios_state() -> BatteryState:
-    try:
-        # UIDeviceBatteryState: 0 unknown, 1 unplugged, 2 charging, 3 full
-        return {0: "unknown", 1: "unplugged", 2: "charging", 3: "full"}.get(int(_ios_device().batteryState), "unknown")
-    except Exception:
-        return "unknown"
-
-
-# ======================================================================
-# Android: BatteryManager
-# ======================================================================
-
-
-def _android_level() -> float:
-    try:
-        from java import jclass
-
-        from ..utils import get_android_context
-
-        ctx = get_android_context()
-        Context = jclass("android.content.Context")
-        bm = ctx.getSystemService(Context.BATTERY_SERVICE)
-        BatteryManager = jclass("android.os.BatteryManager")
-        pct = bm.getIntProperty(BatteryManager.BATTERY_PROPERTY_CAPACITY)
-        return (pct / 100.0) if pct is not None and pct >= 0 else -1.0
-    except Exception:
-        return -1.0
-
-
-def _android_state() -> BatteryState:
-    try:
-        from java import jclass
+def _on_native_change(payload: Any) -> None:
+    if isinstance(payload, dict):
+        dispatch_battery(float(payload.get("level", -1.0)), str(payload.get("state", "unknown")))
 
-        from ..utils import get_android_context
 
-        ctx = get_android_context()
-        Context = jclass("android.content.Context")
-        bm = ctx.getSystemService(Context.BATTERY_SERVICE)
-        BatteryManager = jclass("android.os.BatteryManager")
-        status = bm.getIntProperty(BatteryManager.BATTERY_PROPERTY_STATUS)
-        return {
-            BatteryManager.BATTERY_STATUS_CHARGING: "charging",
-            BatteryManager.BATTERY_STATUS_FULL: "full",
-            BatteryManager.BATTERY_STATUS_DISCHARGING: "unplugged",
-            BatteryManager.BATTERY_STATUS_NOT_CHARGING: "unplugged",
-        }.get(status, "unknown")
-    except Exception:
-        return "unknown"
+on_event("Battery", "change", _on_native_change)

pythonnative/native_modules/biometrics.py

@@ -2,7 +2,8 @@
 
 [`Biometrics`][pythonnative.Biometrics] gates an action behind the
 device's biometric hardware via ``LAContext`` (iOS) and
-``BiometricPrompt`` (Android).
+``BiometricPrompt`` (Android), both implemented in the native
+``Biometrics`` module.
 
 ``is_available`` is synchronous; ``authenticate`` is a coroutine that
 presents the system prompt and resolves to ``True`` on success or
@@ -20,14 +21,7 @@ Example:
 
 from __future__ import annotations
 
-import asyncio
-from typing import Any, Callable, Dict
-
-from .. import diagnostics
-from ..runtime import resolve_future
-from ..utils import IS_ANDROID, IS_IOS
-
-_pending: Dict[int, Any] = {}
+from .registry import native_module
 
 
 class Biometrics:
@@ -36,122 +30,15 @@ class Biometrics:
     @staticmethod
     def is_available() -> bool:
         """Return ``True`` when biometric auth can be attempted."""
-        if IS_IOS:
-            return _ios_available()
-        if IS_ANDROID:
-            return _android_available()
-        return False
+        try:
+            return bool(native_module("Biometrics").call("is_available"))
+        except Exception:
+            return False
 
     @staticmethod
     async def authenticate(reason: str = "Authenticate") -> bool:
         """Present the biometric prompt; resolve ``True`` on success."""
-        loop = asyncio.get_running_loop()
-        future: asyncio.Future[bool] = loop.create_future()
-
-        def _done(ok: bool) -> None:
-            resolve_future(future, ok)
-
-        if IS_IOS:
-            _ios_authenticate(reason, _done)
-        elif IS_ANDROID:
-            _android_authenticate(reason, _done)
-        else:
-            _done(False)
-
-        return await future
-
-
-# ======================================================================
-# iOS: LAContext
-# ======================================================================
-
-
-def _ios_context() -> Any:
-    from rubicon.objc import ObjCClass
-
-    return ObjCClass("LAContext").alloc().init()
-
-
-def _ios_available() -> bool:
-    try:
-        # LAPolicyDeviceOwnerAuthenticationWithBiometrics == 1
-        return bool(_ios_context().canEvaluatePolicy_error_(1, None))
-    except Exception:
-        return False
-
-
-def _ios_authenticate(reason: str, on_done: Callable[[bool], None]) -> None:
-    try:
-        from rubicon.objc import Block, ObjCClass
-
-        context = _ios_context()
-        token = id(context)
-        _pending[token] = context
-
-        def _reply(success: bool, error: Any) -> None:
-            del error
-            _pending.pop(token, None)
-            try:
-                on_done(bool(success))
-            except Exception:
-                diagnostics.swallowed("biometrics._ios_authenticate._reply")
-
-        context.evaluatePolicy_localizedReason_reply_(1, reason, Block(_reply, None, bool, ObjCClass("NSError")))
-    except Exception:
-        on_done(False)
-
-
-# ======================================================================
-# Android: BiometricPrompt
-# ======================================================================
-
-
-def _android_available() -> bool:
-    try:
-        from java import jclass
-
-        from ..utils import get_android_context
-
-        BiometricManager = jclass("androidx.biometric.BiometricManager")
-        manager = BiometricManager.from_(get_android_context())
-        Authenticators = jclass("androidx.biometric.BiometricManager$Authenticators")
-        result = manager.canAuthenticate(Authenticators.BIOMETRIC_WEAK)
-        return result == BiometricManager.BIOMETRIC_SUCCESS
-    except Exception:
-        return False
-
-
-def _android_authenticate(reason: str, on_done: Callable[[bool], None]) -> None:
-    try:
-        from java import dynamic_proxy, jclass
-
-        from ..utils import get_android_context
-
-        ctx = get_android_context()
-        FragmentActivity = jclass("androidx.fragment.app.FragmentActivity")
-        if not FragmentActivity.isInstance(ctx):
-            on_done(False)
-            return
-
-        BiometricPrompt = jclass("androidx.biometric.BiometricPrompt")
-        ContextCompat = jclass("androidx.core.content.ContextCompat")
-        executor = ContextCompat.getMainExecutor(ctx)
-
-        class _Callback(dynamic_proxy(BiometricPrompt.AuthenticationCallback)):  # type: ignore[misc]
-            def onAuthenticationSucceeded(self, result: Any) -> None:  # noqa: N802, ARG002
-                on_done(True)
-
-            def onAuthenticationError(self, code: int, message: Any) -> None:  # noqa: N802, ARG002
-                on_done(False)
-
-            def onAuthenticationFailed(self) -> None:  # noqa: N802
-                # Fired on a non-matching attempt; the prompt stays up,
-                # so don't resolve yet.
-                pass
-
-        prompt = BiometricPrompt(ctx, executor, _Callback())
-        Builder = jclass("androidx.biometric.BiometricPrompt$PromptInfo$Builder")
-        info = Builder().setTitle(reason).setNegativeButtonText("Cancel").build()
-        prompt.authenticate(info)
-    except Exception:
-        on_done(False)
+        try:
+            return bool(await native_module("Biometrics").call_async("authenticate", reason=reason))
+        except Exception:
+            return False