pythonnative 0.40.0__cp313-cp313-win_amd64.whl

pythonnative/native_modules/linking.py

@@ -0,0 +1,123 @@
+"""Open URLs, deep links, and the system settings page.
+
+[`Linking`][pythonnative.Linking] wraps ``UIApplication.openURL`` /
+``Intent(ACTION_VIEW)`` (in the native ``Linking`` module) so a Python
+app can hand a URL (``https:``, ``mailto:``, ``tel:``, a custom
+scheme, ...) to the OS.
+
+Outbound methods hand the URL to the OS and return at once, so they
+are synchronous; the ``bool`` says whether the platform accepted the
+request. Off device they return ``False``.
+
+Inbound deep links flow the other way: declare your schemes in
+``pythonnative.toml`` (``app.url_schemes``) and the native module
+pushes a ``url`` event for every URL that opens the app, which lands in
+[`dispatch_url`][pythonnative.native_modules.linking.dispatch_url]. 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 url := pn.Linking.get_initial_url():
+        navigate_to(url)
+
+    unsubscribe = pn.Linking.add_listener(navigate_to)
+    ```
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, List, Optional
+
+from .registry import native_module, on_event
+
+_initial_url: Optional[str] = None
+_url_listeners: List[Callable[[str], None]] = []
+
+
+def _call_bool(method: str, **args: Any) -> bool:
+    return bool(native_module("Linking").call(method, **args))
+
+
+class Linking:
+    """System URL / deep-link interface (synchronous).
+
+    Raises:
+        NativeModuleError: If the native module fails.
+    """
+
+    @staticmethod
+    def open_url(url: str) -> bool:
+        """Hand ``url`` to the OS. Returns ``True`` if it was accepted."""
+        return _call_bool("open_url", url=url)
+
+    @staticmethod
+    def can_open_url(url: str) -> bool:
+        """Return ``True`` when some installed app can handle ``url``."""
+        return _call_bool("can_open_url", url=url)
+
+    @staticmethod
+    def open_settings() -> bool:
+        """Open this app's entry in the system Settings app."""
+        return _call_bool("open_settings")
+
+    @staticmethod
+    def get_initial_url() -> Optional[str]:
+        """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 (or clear it with ``None``)."""
+    global _initial_url
+    _initial_url = url
+
+
+def dispatch_url(url: str) -> None:
+    """Deliver an inbound deep link.
+
+    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 native can't report it 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}")
+
+
+on_event("Linking", "url", lambda payload: dispatch_url(str(payload)))

pythonnative/native_modules/location.py

@@ -0,0 +1,75 @@
+"""Cross-platform location / GPS access.
+
+[`Location.get_current`][pythonnative.native_modules.location.Location.get_current]
+is a coroutine that resolves to a ``(latitude, longitude)`` tuple, or
+``None`` if no fix is available (the user denied permission, location
+services are off, or the request timed out).
+The native ``Location`` module owns the ``CLLocationManager`` /
+``LocationManager`` session and resolves the call with
+``{"latitude", "longitude", "accuracy", "altitude", "timestamp"}``.
+
+Permission prompts are triggered the first time a location-using API
+is called; ensure the appropriate manifest entries
+(``android.permission.ACCESS_FINE_LOCATION``) and Info.plist keys
+(``NSLocationWhenInUseUsageDescription``) are present.
+
+Example:
+    ```python
+    import pythonnative as pn
+
+    async def show_position():
+        coords = await pn.Location.get_current()
+        if coords is None:
+            return
+        lat, lon = coords
+        print(f"You are at {lat:.5f}, {lon:.5f}")
+    ```
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional, Tuple
+
+from .registry import NativeModuleError, native_module
+
+Coords = Tuple[float, float]
+
+
+class Location:
+    """GPS / location-services interface."""
+
+    @staticmethod
+    async def get_current(**options: Any) -> Optional[Coords]:
+        """Request the device's current location.
+
+        Args:
+            **options: Forwarded to the native module (``accuracy``,
+                ``timeout``). Unknown keys are ignored.
+
+        Returns:
+            ``(latitude, longitude)`` if a fix was obtained, otherwise
+            ``None``.
+
+        Raises:
+            NativeModuleError: If the native module fails.
+        """
+        fix = await Location.get_current_fix(**options)
+        if fix is None:
+            return None
+        return (fix["latitude"], fix["longitude"])
+
+    @staticmethod
+    async def get_current_fix(**options: Any) -> Optional[Dict[str, float]]:
+        """Like ``get_current`` but returns the full fix dict.
+
+        Keys: ``latitude``, ``longitude``, and when the platform reports
+        them ``accuracy`` (meters), ``altitude`` (meters), ``speed``
+        (m/s), ``heading`` (degrees), ``timestamp`` (Unix seconds).
+        """
+        result = await native_module("Location").call_async("get_current", **options)
+        if not isinstance(result, dict):
+            return None
+        fix: Dict[str, float] = {k: float(v) for k, v in result.items() if v is not None}
+        if "latitude" not in fix or "longitude" not in fix:
+            raise NativeModuleError("Location", "get_current", f"fix is missing coordinates: {sorted(result)}")
+        return fix

pythonnative/native_modules/net_info.py

@@ -0,0 +1,112 @@
+"""Network connectivity state.
+
+[`NetInfo`][pythonnative.NetInfo] reports whether the device is online
+and over what kind of connection. ``fetch`` returns a snapshot dict;
+``add_listener`` (and the [`use_net_info`][pythonnative.use_net_info]
+hook) deliver live updates pushed by the native ``NetInfo`` module
+(``NWPathMonitor`` on iOS, ``ConnectivityManager.NetworkCallback`` on
+Android) as ``change`` events. Off device, tests push snapshots through
+[`dispatch_net_info`][pythonnative.native_modules.net_info.dispatch_net_info].
+
+A snapshot looks like::
+
+    {"is_connected": True, "type": "wifi", "is_internet_reachable": True}
+
+``type`` is one of ``"wifi"``, ``"cellular"``, ``"ethernet"``,
+``"none"``, or ``"unknown"``.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, List
+
+from .. import diagnostics
+from ..hooks import use_effect, use_state
+from .registry import native_module, on_event
+
+NetInfoState = Dict[str, object]
+
+_listeners: List[Callable[[NetInfoState], None]] = []
+_last_state: NetInfoState = {
+    "is_connected": True,
+    "type": "unknown",
+    "is_internet_reachable": True,
+}
+
+
+class NetInfo:
+    """Network connectivity interface."""
+
+    @staticmethod
+    def fetch() -> NetInfoState:
+        """Return a fresh snapshot of connectivity state."""
+        global _last_state
+        snapshot = native_module("NetInfo").call("fetch")
+        if isinstance(snapshot, dict):
+            _last_state = _normalize(snapshot)
+        return dict(_last_state)
+
+    @staticmethod
+    def add_listener(callback: Callable[[NetInfoState], None]) -> Callable[[], None]:
+        """Subscribe to connectivity changes; returns an unsubscribe fn."""
+        _listeners.append(callback)
+
+        def _unsubscribe() -> None:
+            try:
+                _listeners.remove(callback)
+            except ValueError:
+                pass
+
+        return _unsubscribe
+
+
+def _normalize(snapshot: Dict[str, Any]) -> NetInfoState:
+    return {
+        "is_connected": bool(snapshot.get("is_connected", False)),
+        "type": str(snapshot.get("type", "unknown")),
+        "is_internet_reachable": bool(snapshot.get("is_internet_reachable", False)),
+    }
+
+
+def dispatch_net_info(state: NetInfoState) -> None:
+    """Push a new connectivity snapshot and notify listeners."""
+    global _last_state
+    _last_state = dict(state)
+    for listener in list(_listeners):
+        try:
+            listener(dict(state))
+        except Exception:
+            diagnostics.swallowed("net_info.dispatch_net_info")
+
+
+def _on_native_change(payload: Any) -> None:
+    if not isinstance(payload, dict):
+        return
+    state = _normalize(payload)
+    if state == _last_state:
+        return
+    dispatch_net_info(state)
+
+
+on_event("NetInfo", "change", _on_native_change)
+
+
+def use_net_info() -> NetInfoState:
+    """Subscribe a component to [`NetInfo`][pythonnative.NetInfo].
+
+    Returns:
+        The latest connectivity snapshot dict; the component
+        re-renders whenever connectivity changes.
+    """
+    state, set_state = use_state(NetInfo.fetch)
+
+    def _subscribe() -> Callable[[], None]:
+        set_state(NetInfo.fetch())
+
+        def on_change(snapshot: NetInfoState) -> None:
+            set_state(snapshot)
+
+        return NetInfo.add_listener(on_change)
+
+    use_effect(_subscribe, [])
+    return state

pythonnative/native_modules/notifications.py

@@ -0,0 +1,129 @@
+"""Local notifications and remote push registration.
+
+Coroutines for requesting permission and scheduling / cancelling local
+notifications, backed by the native ``Notifications`` module
+(``UNUserNotificationCenter`` on iOS, ``NotificationManager`` on
+Android).
+
+On iOS you must ``await Notifications.request_permission()`` before
+scheduling. On Android 13+ the ``POST_NOTIFICATIONS`` runtime
+permission is requested automatically the first time you schedule a
+notification (the template manifest declares it); earlier Android
+versions don't prompt at all.
+
+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
+
+    async def setup_reminders():
+        if not await pn.Notifications.request_permission():
+            return
+        await pn.Notifications.schedule(
+            title="Reminder",
+            body="Time for a walk!",
+            delay_seconds=60,
+            identifier="walk",
+        )
+    ```
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from .registry import native_module
+
+
+class Notifications:
+    """Local notification interface."""
+
+    @staticmethod
+    async def request_permission() -> bool:
+        """Request notification permission from the user.
+
+        On Android 12 and below the manifest declaration is sufficient
+        and this returns ``True`` without prompting. On Android 13+
+        (API 33) the ``POST_NOTIFICATIONS`` runtime permission prompt
+        is shown if the user hasn't decided yet.
+
+        Returns:
+            ``True`` if granted (or no prompt is needed), ``False`` if
+            the user declined (always ``False`` off device).
+
+        Raises:
+            NativeModuleError: If the native module fails.
+        """
+        return bool(await native_module("Notifications").call_async("request_permission"))
+
+    @staticmethod
+    async def schedule(
+        title: str,
+        body: str = "",
+        *,
+        delay_seconds: float = 0,
+        identifier: str = "default",
+        **options: Any,
+    ) -> bool:
+        """Schedule a local notification.
+
+        Args:
+            title: Notification title.
+            body: Notification body text.
+            delay_seconds: Seconds from now until delivery. Use ``0``
+                for an effectively immediate notification.
+            identifier: Stable ID used by
+                [`cancel`][pythonnative.native_modules.notifications.Notifications.cancel]
+                to target this notification.
+            **options: Forwarded to the native module (``sound``,
+                ``badge``, ...). Unknown keys are ignored.
+
+        Returns:
+            ``True`` once scheduled, ``False`` if the user has denied
+            notification permission (so nothing was scheduled).
+
+        Raises:
+            NativeModuleError: If the native module fails.
+        """
+        result = await native_module("Notifications").call_async(
+            "schedule",
+            title=title,
+            body=body,
+            delay_seconds=float(delay_seconds),
+            identifier=identifier,
+            **options,
+        )
+        return bool(result)
+
+    @staticmethod
+    async def cancel(identifier: str = "default") -> None:
+        """Cancel a pending notification by its identifier (a no-op when none is pending)."""
+        await native_module("Notifications").call_async("cancel", identifier=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 off device).
+
+        Raises:
+            NativeModuleError: If APNs registration fails; ``code`` is
+                ``"apns"`` and the message carries the system's error.
+        """
+        token = await native_module("Notifications").call_async("get_device_token")
+        return str(token) if token else None

pythonnative/native_modules/permissions.py

@@ -0,0 +1,108 @@
+"""Runtime permission checks and requests.
+
+[`Permissions`][pythonnative.Permissions] normalizes the very different
+iOS and Android permission models behind two calls, both served by the
+native ``Permissions`` module:
+
+- ``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.
+
+Statuses are ``"granted"``, ``"denied"``, ``"blocked"`` (denied with
+"don't ask again" / Settings required), or ``"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 = 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: PermissionStatus = "granted"
+DENIED: PermissionStatus = "denied"
+BLOCKED: PermissionStatus = "blocked"
+UNDETERMINED: PermissionStatus = "undetermined"
+
+_STATUSES = (GRANTED, DENIED, BLOCKED, UNDETERMINED)
+
+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:
+    status = str(value) if value is not None else UNDETERMINED
+    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.
+
+    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."""
+        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.
+
+        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)))