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

pythonnative/native_modules/linking.py

@@ -4,27 +4,38 @@
 ``Intent(ACTION_VIEW)`` so a Python app can hand a URL (``https:``,
 ``mailto:``, ``tel:``, a custom scheme, …) to the OS.
 
-All methods are synchronous and return a ``bool`` describing whether
-the platform accepted the request. On desktop they return ``False``.
+Outbound methods are synchronous and return a ``bool`` describing
+whether the platform accepted the request. On desktop they return
+``False``.
+
+Inbound deep links flow the other way: declare your schemes in
+``pythonnative.toml`` (``app.url_schemes``) and the native host calls
+[`dispatch_url`][pythonnative.native_modules.linking.dispatch_url] for
+every URL that opens the app. The URL that cold-started the app is kept
+and returned by ``get_initial_url``; later URLs reach subscribers added
+with ``add_listener``.
 
 Example:
     ```python
     import pythonnative as pn
 
-    if pn.Linking.can_open_url("tel:+15551234567"):
-        pn.Linking.open_url("tel:+15551234567")
+    if url := pn.Linking.get_initial_url():
+        navigate_to(url)
+
+    unsubscribe = pn.Linking.add_listener(navigate_to)
     ```
 """
 
 from __future__ import annotations
 
-from typing import Any, Optional
+from typing import Any, Callable, List, Optional
 
 from ..utils import IS_ANDROID, IS_IOS
 
 # Populated by the native host when the app is launched from a deep
-# link; ``get_initial_url`` returns it once.
+# link; ``get_initial_url`` returns it.
 _initial_url: Optional[str] = None
+_url_listeners: List[Callable[[str], None]] = []
 
 
 class Linking:
@@ -62,6 +73,28 @@ class Linking:
         """Return the URL that launched the app, if any."""
         return _initial_url
 
+    @staticmethod
+    def add_listener(callback: Callable[[str], None]) -> Callable[[], None]:
+        """Subscribe to deep links that arrive while the app is running.
+
+        Args:
+            callback: Called with the full URL string for every inbound
+                deep link (including the initial one, which is
+                dispatched right after startup).
+
+        Returns:
+            A zero-arg function that unsubscribes when called.
+        """
+        _url_listeners.append(callback)
+
+        def _unsubscribe() -> None:
+            try:
+                _url_listeners.remove(callback)
+            except ValueError:
+                pass
+
+        return _unsubscribe
+
 
 def set_initial_url(url: Optional[str]) -> None:
     """Record the launch URL (called by the native host on cold start)."""
@@ -69,6 +102,29 @@ def set_initial_url(url: Optional[str]) -> None:
     _initial_url = url
 
 
+def dispatch_url(url: str) -> None:
+    """Deliver an inbound deep link from the native host.
+
+    The first URL ever dispatched is also recorded as the initial URL
+    (a cold start from a deep link reaches Python only after the
+    interpreter boots, so the host can't call ``set_initial_url``
+    earlier than this).
+
+    Args:
+        url: The full URL string that opened the app.
+    """
+    global _initial_url
+    if _initial_url is None:
+        _initial_url = url
+    for listener in list(_url_listeners):
+        try:
+            listener(url)
+        except Exception as exc:
+            from .. import diagnostics
+
+            diagnostics.warn(f"Linking listener raised while handling {url!r}: {exc!r}")
+
+
 # ======================================================================
 # iOS
 # ======================================================================

pythonnative/native_modules/location.py

@@ -27,6 +27,7 @@ from __future__ import annotations
 import asyncio
 from typing import Any, Callable, Dict, Optional, Tuple
 
+from .. import diagnostics
 from ..runtime import resolve_future
 from ..utils import IS_ANDROID, IS_IOS
 
@@ -94,7 +95,7 @@ def _ios_get(on_result: Callable[[Optional[Coords]], None]) -> None:
                     if self._manager is not None:
                         self._manager.stopUpdatingLocation()
                 except Exception:
-                    pass
+                    diagnostics.swallowed("location._ios_get._PNLocationDelegate._finish")
                 cb = self._callback
                 self._callback = None
                 _pending_delegates.pop(id(self), None)
@@ -102,7 +103,7 @@ def _ios_get(on_result: Callable[[Optional[Coords]], None]) -> None:
                     try:
                         cb(coords)
                     except Exception:
-                        pass
+                        diagnostics.swallowed("location._ios_get._PNLocationDelegate._finish")
 
             @objc_method
             def locationManager_didUpdateLocations_(self, manager: Any, locations: Any) -> None:
@@ -131,7 +132,9 @@ def _ios_get(on_result: Callable[[Optional[Coords]], None]) -> None:
                     try:
                         manager.startUpdatingLocation()
                     except Exception:
-                        pass
+                        diagnostics.swallowed(
+                            "location._ios_get._PNLocationDelegate.locationManagerDidChangeAuthorization_"
+                        )
 
         delegate = _PNLocationDelegate.new()
         delegate._callback = on_result
@@ -143,11 +146,11 @@ def _ios_get(on_result: Callable[[Optional[Coords]], None]) -> None:
         try:
             manager.requestWhenInUseAuthorization()
         except Exception:
-            pass
+            diagnostics.swallowed("location._ios_get")
         try:
             manager.startUpdatingLocation()
         except Exception:
-            pass
+            diagnostics.swallowed("location._ios_get")
     except Exception:
         on_result(None)
 
@@ -176,7 +179,7 @@ def _android_get(on_result: Callable[[Optional[Coords]], None]) -> None:
                     on_result((float(loc.getLatitude()), float(loc.getLongitude())))
                     return
         except Exception:
-            pass
+            diagnostics.swallowed("location._android_get")
 
         LocationListener = jclass("android.location.LocationListener")
         delivered = [False]
@@ -188,12 +191,12 @@ def _android_get(on_result: Callable[[Optional[Coords]], None]) -> None:
             try:
                 lm.removeUpdates(listener)
             except Exception:
-                pass
+                diagnostics.swallowed("location._android_get._finish")
             _pending_delegates.pop(id(listener), None)
             try:
                 on_result(coords)
             except Exception:
-                pass
+                diagnostics.swallowed("location._android_get._finish")
 
         class _PNLocationListener(dynamic_proxy(LocationListener)):  # type: ignore[misc]
             def onLocationChanged(self, loc: Any) -> None:

pythonnative/native_modules/net_info.py

@@ -19,6 +19,7 @@ from __future__ import annotations
 
 from typing import Callable, Dict, List
 
+from .. import diagnostics
 from ..hooks import use_effect, use_state
 from ..utils import IS_ANDROID, IS_IOS
 
@@ -67,7 +68,7 @@ def dispatch_net_info(state: NetInfoState) -> None:
         try:
             listener(dict(state))
         except Exception:
-            pass
+            diagnostics.swallowed("net_info.dispatch_net_info")
 
 
 def use_net_info() -> NetInfoState:

pythonnative/native_modules/notifications.py

@@ -1,4 +1,4 @@
-"""Cross-platform local notifications.
+"""Cross-platform local notifications and remote push registration.
 
 Provides coroutines for requesting permission and scheduling /
 cancelling local push notifications. Uses Android's
@@ -9,6 +9,14 @@ scheduling. On Android 13+ the runtime permission should be requested
 through standard Android APIs (the manifest declaration is otherwise
 sufficient).
 
+For remote (server-sent) pushes, enable the ``remote_notifications``
+capability in ``pythonnative.toml`` and call
+``Notifications.get_device_token()`` to register with APNs and receive
+the device token your server needs. Android remote push requires
+Firebase Cloud Messaging, which needs a per-app ``google-services.json``
+and is not wired up by the built-in module; ``get_device_token`` returns
+``None`` there.
+
 Example:
     ```python
     import pythonnative as pn
@@ -28,10 +36,11 @@ Example:
 from __future__ import annotations
 
 import asyncio
-from typing import Any, Dict
+from typing import Any, Dict, List, Optional
 
-from ..runtime import resolve_future
-from ..utils import IS_ANDROID
+from .. import diagnostics
+from ..runtime import reject_future, resolve_future
+from ..utils import IS_ANDROID, IS_IOS
 
 # Delayed Android deliveries in flight, keyed by identifier, so
 # ``cancel`` can abort a notification that hasn't posted yet. (iOS
@@ -110,6 +119,28 @@ class Notifications:
             return
         await asyncio.to_thread(_ios_cancel, identifier)
 
+    @staticmethod
+    async def get_device_token() -> Optional[str]:
+        """Register for remote notifications and return the device token.
+
+        On iOS this calls ``registerForRemoteNotifications`` and waits
+        for the APNs callback; the token is a lowercase hex string your
+        server passes to APNs. Requires the ``remote_notifications``
+        capability (which adds the ``aps-environment`` entitlement) and
+        a real device (the simulator has no APNs connection).
+
+        Returns:
+            The APNs token, or ``None`` on platforms without built-in
+            remote push support (Android and desktop).
+
+        Raises:
+            RuntimeError: If APNs registration fails, with the native
+                error description.
+        """
+        if not IS_IOS:
+            return None
+        return await _ios_get_device_token()
+
 
 # ======================================================================
 # Android implementation
@@ -171,7 +202,7 @@ def _android_cancel(identifier: str) -> None:
         nm = ctx.getSystemService(jclass("android.content.Context").NOTIFICATION_SERVICE)
         nm.cancel(abs(hash(identifier)) % (2**31))
     except Exception:
-        pass
+        diagnostics.swallowed("notifications._android_cancel")
 
 
 # ======================================================================
@@ -235,4 +266,64 @@ def _ios_cancel(identifier: str) -> None:
         arr = NSArray.arrayWithObject_(identifier)
         center.removePendingNotificationRequestsWithIdentifiers_(arr)
     except Exception:
-        pass
+        diagnostics.swallowed("notifications._ios_cancel")
+
+
+# ----------------------------------------------------------------------
+# Remote notifications (APNs)
+# ----------------------------------------------------------------------
+#
+# The registration result arrives through UIApplicationDelegate
+# callbacks in the native template, which forward here via
+# dispatch_device_token / dispatch_device_token_error. The token is
+# cached so later get_device_token() calls resolve immediately.
+
+_device_token: Optional[str] = None
+_device_token_error: Optional[str] = None
+_token_waiters: List["asyncio.Future[str]"] = []
+
+
+async def _ios_get_device_token() -> str:
+    if _device_token is not None:
+        return _device_token
+    if _device_token_error is not None:
+        raise RuntimeError(f"APNs registration failed: {_device_token_error}")
+
+    loop = asyncio.get_running_loop()
+    future: asyncio.Future[str] = loop.create_future()
+    _token_waiters.append(future)
+
+    def _register() -> None:
+        from rubicon.objc import ObjCClass
+
+        ObjCClass("UIApplication").sharedApplication.registerForRemoteNotifications()
+
+    try:
+        # registerForRemoteNotifications must run on the main thread.
+        from ..runtime import call_on_main_thread
+
+        call_on_main_thread(_register)
+    except Exception as exc:
+        _token_waiters.remove(future)
+        raise RuntimeError(f"Could not start APNs registration: {exc}") from exc
+    return await future
+
+
+def dispatch_device_token(token: str) -> None:
+    """Deliver the APNs device token from the native host."""
+    global _device_token, _device_token_error
+    _device_token = token
+    _device_token_error = None
+    waiters, _token_waiters[:] = list(_token_waiters), []
+    for future in waiters:
+        resolve_future(future, token)
+
+
+def dispatch_device_token_error(message: str) -> None:
+    """Deliver an APNs registration failure from the native host."""
+    global _device_token_error
+    _device_token_error = message
+    waiters, _token_waiters[:] = list(_token_waiters), []
+    error = RuntimeError(f"APNs registration failed: {message}")
+    for future in waiters:
+        reject_future(future, error)

pythonnative/native_modules/permissions.py

@@ -21,6 +21,7 @@ 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
 
@@ -141,7 +142,7 @@ def deliver_android_permission_result(request_code: int, permissions: Any, grant
     try:
         cb(status)
     except Exception:
-        pass
+        diagnostics.swallowed("permissions.deliver_android_permission_result")
     return True
 
 
@@ -215,7 +216,7 @@ def _ios_request(permission: str, on_done: Callable[[PermissionStatus], None]) -
             center.requestAuthorizationWithOptions_completionHandler_(0x07, Block(_notif_done, None, bool, object))
             return
     except Exception:
-        pass
+        diagnostics.swallowed("permissions._ios_request")
     # Fall back to reporting the current status for permissions whose
     # request flow isn't wired up natively (location needs a
     # CLLocationManager delegate; use the Location module's own

pythonnative/native_modules/share.py

@@ -22,6 +22,7 @@ from __future__ import annotations
 import asyncio
 from typing import Any, Callable, Dict, Optional
 
+from .. import diagnostics
 from ..runtime import resolve_future
 from ..utils import IS_ANDROID, IS_IOS
 
@@ -102,7 +103,7 @@ def _ios_share(
             try:
                 on_done(bool(completed))
             except Exception:
-                pass
+                diagnostics.swallowed("share._ios_share._completion")
 
         controller.setCompletionWithItemsHandler_(
             Block(_completion, None, ObjCClass("NSString"), Block, ObjCClass("NSArray"), ObjCClass("NSError"))