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

pythonnative/native_modules/desktop.py

@@ -0,0 +1,322 @@
+"""Off-device implementations of the built-in native modules.
+
+On iOS and Android every module in this package is implemented in
+Swift and Kotlin (``PythonNativeKit`` and the ``pythonnative`` Gradle
+module). Off device (``pn preview``, unit tests) the same module names
+resolve to the plain Python classes below, which keep the API usable
+without a device: in-memory buffers, ``"unknown"`` states, and no-op
+feedback.
+
+Each class has the same method names and argument shapes as its native
+counterpart, so a facade in this package never branches on platform.
+Apps and tests may swap any of these with
+[`register_python_module`][pythonnative.native_modules.registry.register_python_module].
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import platform as _platform
+import sys
+import threading
+from typing import Any, Callable, Dict, List, Optional
+
+__all__ = ["default_implementation"]
+
+
+# ======================================================================
+# Device / host information
+# ======================================================================
+
+
+class DesktopDevice:
+    """Static device information for the desktop preview."""
+
+    def info(self) -> Dict[str, Any]:
+        home = os.path.expanduser("~")
+        app_dir = os.path.join(home, ".pythonnative_data")
+        return {
+            "platform": "desktop",
+            "os": sys.platform,
+            "os_version": _platform.release(),
+            "model": _platform.machine(),
+            "app_dir": app_dir,
+            "cache_dir": os.path.join(app_dir, "cache"),
+            "temp_dir": os.path.join(app_dir, "tmp"),
+            "locale": os.environ.get("LANG", "en_US").split(".")[0],
+            "app_version": "0.0.0",
+            "build_number": "0",
+            "bundle_id": "com.pythonnative.preview",
+            "python_version": _platform.python_version(),
+        }
+
+
+class DesktopAppState:
+    def current_state(self) -> str:
+        return "active"
+
+
+# ======================================================================
+# Storage
+# ======================================================================
+
+
+class DesktopStorage:
+    """Dict-backed ``AsyncStorage`` with optional JSON persistence.
+
+    Set ``PN_STORAGE_DIR`` to persist between runs (``pn preview`` does
+    this); leave it unset in tests for a purely in-memory store.
+    """
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._store: Dict[str, str] = {}
+        self._loaded = False
+
+    def _path(self) -> Optional[str]:
+        base = os.environ.get("PN_STORAGE_DIR")
+        if not base:
+            return None
+        try:
+            os.makedirs(base, exist_ok=True)
+        except OSError:
+            return None
+        return os.path.join(base, "pn_async_storage.json")
+
+    def _load(self) -> None:
+        if self._loaded:
+            return
+        self._loaded = True
+        path = self._path()
+        if path is None or not os.path.exists(path):
+            return
+        try:
+            with open(path, encoding="utf-8") as f:
+                data = json.load(f)
+        except (OSError, json.JSONDecodeError):
+            return
+        if isinstance(data, dict):
+            self._store.update({str(k): str(v) for k, v in data.items()})
+
+    def _persist(self) -> None:
+        path = self._path()
+        if path is None:
+            return
+        try:
+            with open(path, "w", encoding="utf-8") as f:
+                json.dump(self._store, f)
+        except OSError:
+            pass
+
+    def get(self, key: str) -> Optional[str]:
+        with self._lock:
+            self._load()
+            return self._store.get(key)
+
+    def set(self, key: str, value: str) -> None:
+        with self._lock:
+            self._load()
+            self._store[key] = value
+            self._persist()
+
+    def delete(self, key: str) -> None:
+        with self._lock:
+            self._load()
+            self._store.pop(key, None)
+            self._persist()
+
+    def all_keys(self) -> List[str]:
+        with self._lock:
+            self._load()
+            return list(self._store.keys())
+
+    def clear(self) -> None:
+        with self._lock:
+            self._store.clear()
+            self._persist()
+
+    def _reset(self) -> None:
+        """Forget everything, including the on-disk snapshot (tests)."""
+        with self._lock:
+            self._store.clear()
+            self._loaded = False
+
+
+class DesktopSecureStore:
+    def __init__(self) -> None:
+        self._store: Dict[str, str] = {}
+
+    def set_item(self, key: str, value: str) -> bool:
+        self._store[key] = value
+        return True
+
+    def get_item(self, key: str) -> Optional[str]:
+        return self._store.get(key)
+
+    def delete_item(self, key: str) -> bool:
+        return self._store.pop(key, None) is not None
+
+    def clear(self) -> None:
+        self._store.clear()
+
+
+class DesktopClipboard:
+    def __init__(self) -> None:
+        self._buffer = ""
+
+    def set_string(self, text: str) -> None:
+        self._buffer = "" if text is None else str(text)
+
+    def get_string(self) -> str:
+        return self._buffer
+
+
+# ======================================================================
+# System integration
+# ======================================================================
+
+
+class DesktopAlert:
+    """Records alerts and answers with scripted responses.
+
+    The log and response queue live on
+    [`Alert`][pythonnative.alerts.Alert] (``Alert._test_log`` and
+    ``Alert.set_test_response``) so tests have one place to look.
+    """
+
+    @staticmethod
+    def _record(title: str, message: Optional[str], buttons: List[Dict[str, Any]], style: str) -> Any:
+        from ..alerts import Alert
+
+        Alert._test_log.append({"title": title, "message": message, "buttons": list(buttons), "style": style})
+        return Alert
+
+    def show(self, title: str, message: Optional[str], buttons: List[Dict[str, Any]], style: str) -> None:
+        self._record(title, message, buttons, style)
+
+    def present(self, title: str, message: Optional[str], buttons: List[Dict[str, Any]], style: str) -> int:
+        return int(self._record(title, message, buttons, style)._next_test_response())
+
+
+class DesktopShare:
+    def share(self, message: Optional[str] = None, url: Optional[str] = None, title: Optional[str] = None) -> bool:
+        del message, url, title
+        return False
+
+
+class DesktopLinking:
+    def open_url(self, url: str) -> bool:
+        del url
+        return False
+
+    def can_open_url(self, url: str) -> bool:
+        del url
+        return False
+
+    def open_settings(self) -> bool:
+        return False
+
+
+class DesktopHaptics:
+    def impact(self, style: str = "medium") -> None:
+        del style
+
+    def notification(self, type: str = "success") -> None:  # noqa: A002 - wire name
+        del type
+
+    def selection(self) -> None:
+        pass
+
+    def vibrate(self, duration_ms: int = 400) -> None:
+        del duration_ms
+
+    def cancel(self) -> None:
+        pass
+
+
+class DesktopBattery:
+    def get_level(self) -> float:
+        return -1.0
+
+    def get_state(self) -> str:
+        return "unknown"
+
+
+class DesktopNetInfo:
+    def fetch(self) -> Optional[Dict[str, Any]]:
+        # ``None`` means "no fresh reading"; the facade keeps whatever
+        # snapshot was last dispatched (tests push those directly).
+        return None
+
+
+class DesktopPermissions:
+    def check(self, permission: str) -> str:
+        del permission
+        return "undetermined"
+
+    def request(self, permission: str) -> str:
+        del permission
+        return "undetermined"
+
+
+class DesktopNotifications:
+    def request_permission(self) -> bool:
+        return False
+
+    def schedule(self, title: str, body: str = "", delay_seconds: float = 0, identifier: str = "default") -> bool:
+        del title, body, delay_seconds, identifier
+        return False
+
+    def cancel(self, identifier: str = "default") -> None:
+        del identifier
+
+    def get_device_token(self) -> Optional[str]:
+        return None
+
+
+class DesktopCamera:
+    def take_photo(self) -> Optional[str]:
+        return None
+
+    def pick_from_gallery(self) -> Optional[str]:
+        return None
+
+
+class DesktopLocation:
+    def get_current(self) -> Optional[Dict[str, float]]:
+        return None
+
+
+class DesktopBiometrics:
+    def is_available(self) -> bool:
+        return False
+
+    def authenticate(self, reason: str = "Authenticate") -> bool:
+        del reason
+        return False
+
+
+_DEFAULTS: Dict[str, Callable[[], Any]] = {
+    "Device": DesktopDevice,
+    "AppState": DesktopAppState,
+    "Storage": DesktopStorage,
+    "SecureStore": DesktopSecureStore,
+    "Clipboard": DesktopClipboard,
+    "Alert": DesktopAlert,
+    "Share": DesktopShare,
+    "Linking": DesktopLinking,
+    "Haptics": DesktopHaptics,
+    "Battery": DesktopBattery,
+    "NetInfo": DesktopNetInfo,
+    "Permissions": DesktopPermissions,
+    "Notifications": DesktopNotifications,
+    "Camera": DesktopCamera,
+    "Location": DesktopLocation,
+    "Biometrics": DesktopBiometrics,
+}
+
+
+def default_implementation(name: str) -> Optional[Callable[[], Any]]:
+    """Return the factory for the built-in desktop implementation of ``name``."""
+    return _DEFAULTS.get(name)

pythonnative/native_modules/file_system.py

@@ -17,8 +17,9 @@ Example:
 import os
 from typing import Any, Optional
 
-from .. import diagnostics
-from ..utils import IS_ANDROID
+from .registry import native_module
+
+_app_dir_cache: Optional[str] = None
 
 
 class FileSystem:
@@ -39,31 +40,24 @@ class FileSystem:
         On Android the result is `Context.getFilesDir()`. On iOS it is
         the user's Documents directory. On a desktop machine without
         either runtime, a `.pythonnative_data` directory is created
-        under the user's home folder.
+        under the user's home folder. The value comes from the native
+        ``Device`` module's ``info()`` and is cached after the first
+        call.
 
         Returns:
             Absolute path to the app's data directory.
         """
-        if IS_ANDROID:
-            try:
-                from ..utils import get_android_context
-
-                return str(get_android_context().getFilesDir().getAbsolutePath())
-            except Exception:
-                diagnostics.swallowed("file_system.FileSystem.app_dir")
-        else:
+        global _app_dir_cache
+        if _app_dir_cache is None:
+            path: Optional[str] = None
             try:
-                from rubicon.objc import ObjCClass
-
-                NSSearchPathForDirectoriesInDomains = ObjCClass(
-                    "NSFileManager"
-                ).defaultManager.URLsForDirectory_inDomains_
-                docs = NSSearchPathForDirectoriesInDomains(9, 1)  # NSDocumentDirectory, NSUserDomainMask
-                if docs and docs.count > 0:
-                    return str(docs.objectAtIndex_(0).path)
+                info = native_module("Device").call("info")
+                if isinstance(info, dict):
+                    path = info.get("app_dir")
             except Exception:
-                diagnostics.swallowed("file_system.FileSystem.app_dir")
-        return os.path.join(os.path.expanduser("~"), ".pythonnative_data")
+                path = None
+            _app_dir_cache = str(path) if path else os.path.join(os.path.expanduser("~"), ".pythonnative_data")
+        return _app_dir_cache
 
     @staticmethod
     def read_text(path: str, encoding: str = "utf-8") -> Optional[str]:

pythonnative/native_modules/haptics.py

@@ -1,6 +1,6 @@
 """Haptic feedback and raw vibration.
 
-Two interfaces live here:
+Two interfaces live here, both backed by the native ``Haptics`` module:
 
 - [`Haptics`][pythonnative.Haptics]: semantic, iOS-style feedback
   (impact / notification / selection) backed by
@@ -17,20 +17,20 @@ than errors.
 
 from __future__ import annotations
 
-from typing import Any, Optional
+from typing import Any
 
 from .. import diagnostics
-from ..utils import IS_ANDROID, IS_IOS
+from .registry import native_module
 
 ImpactStyle = str  # "light" | "medium" | "heavy" | "soft" | "rigid"
 NotificationType = str  # "success" | "warning" | "error"
 
-_IOS_IMPACT_STYLE = {"light": 0, "medium": 1, "heavy": 2, "soft": 4, "rigid": 5}
-_IOS_NOTIFICATION_TYPE = {"success": 0, "warning": 1, "error": 2}
 
-# Approximate Android fallback durations (ms) per semantic feedback.
-_ANDROID_IMPACT_MS = {"light": 10, "medium": 20, "heavy": 40, "soft": 15, "rigid": 30}
-_ANDROID_NOTIFICATION_MS = {"success": 30, "warning": 50, "error": 70}
+def _call(method: str, **args: Any) -> None:
+    try:
+        native_module("Haptics").call(method, **args)
+    except Exception:
+        diagnostics.swallowed(f"haptics.{method}")
 
 
 class Haptics:
@@ -39,26 +39,17 @@ class Haptics:
     @staticmethod
     def impact(style: ImpactStyle = "medium") -> None:
         """Play a physical "impact" tap of the given ``style``."""
-        if IS_IOS:
-            _ios_impact(style)
-        elif IS_ANDROID:
-            _android_buzz(_ANDROID_IMPACT_MS.get(style, 20))
+        _call("impact", style=style)
 
     @staticmethod
     def notification(type_: NotificationType = "success") -> None:
         """Play a success / warning / error notification pattern."""
-        if IS_IOS:
-            _ios_notification(type_)
-        elif IS_ANDROID:
-            _android_buzz(_ANDROID_NOTIFICATION_MS.get(type_, 30))
+        _call("notification", type=type_)
 
     @staticmethod
     def selection() -> None:
         """Play the light "selection changed" tick."""
-        if IS_IOS:
-            _ios_selection()
-        elif IS_ANDROID:
-            _android_buzz(8)
+        _call("selection")
 
 
 class Vibration:
@@ -66,116 +57,15 @@ class Vibration:
 
     @staticmethod
     def vibrate(duration_ms: int = 400) -> None:
-        """Vibrate for ``duration_ms`` milliseconds."""
-        if IS_ANDROID:
-            _android_buzz(int(duration_ms))
-        elif IS_IOS:
-            # iOS has no arbitrary-duration API; approximate with a
-            # heavy impact for short buzzes and the legacy AudioServices
-            # vibration for longer ones.
-            if duration_ms >= 200:
-                _ios_legacy_vibrate()
-            else:
-                _ios_impact("heavy")
+        """Vibrate for ``duration_ms`` milliseconds.
+
+        iOS has no arbitrary-duration API; the native module
+        approximates short buzzes with a heavy impact and longer ones
+        with the legacy system vibration sound.
+        """
+        _call("vibrate", duration_ms=int(duration_ms))
 
     @staticmethod
     def cancel() -> None:
         """Cancel an in-progress vibration (Android only)."""
-        if IS_ANDROID:
-            vibrator = _android_vibrator()
-            if vibrator is not None:
-                try:
-                    vibrator.cancel()
-                except Exception:
-                    diagnostics.swallowed("haptics.Vibration.cancel")
-
-
-# ======================================================================
-# iOS
-# ======================================================================
-
-
-def _ios_impact(style: str) -> None:
-    try:
-        from rubicon.objc import ObjCClass
-
-        generator = ObjCClass("UIImpactFeedbackGenerator").alloc().initWithStyle_(_IOS_IMPACT_STYLE.get(style, 1))
-        generator.prepare()
-        generator.impactOccurred()
-    except Exception:
-        diagnostics.swallowed("haptics._ios_impact")
-
-
-def _ios_notification(type_: str) -> None:
-    try:
-        from rubicon.objc import ObjCClass
-
-        generator = ObjCClass("UINotificationFeedbackGenerator").alloc().init()
-        generator.prepare()
-        generator.notificationOccurred_(_IOS_NOTIFICATION_TYPE.get(type_, 0))
-    except Exception:
-        diagnostics.swallowed("haptics._ios_notification")
-
-
-def _ios_selection() -> None:
-    try:
-        from rubicon.objc import ObjCClass
-
-        generator = ObjCClass("UISelectionFeedbackGenerator").alloc().init()
-        generator.prepare()
-        generator.selectionChanged()
-    except Exception:
-        diagnostics.swallowed("haptics._ios_selection")
-
-
-def _ios_legacy_vibrate() -> None:
-    try:
-        from ctypes import CDLL, util
-
-        audio = CDLL(util.find_library("AudioToolbox"))
-        audio.AudioServicesPlaySystemSound(4095)  # kSystemSoundID_Vibrate
-    except Exception:
-        diagnostics.swallowed("haptics._ios_legacy_vibrate")
-
-
-# ======================================================================
-# Android
-# ======================================================================
-
-
-def _android_vibrator() -> Optional[Any]:
-    try:
-        from java import jclass
-
-        from ..utils import get_android_context
-
-        ctx = get_android_context()
-        Build = jclass("android.os.Build")
-        if Build.VERSION.SDK_INT >= 31:
-            VibratorManager = jclass("android.os.VibratorManager")
-            Context = jclass("android.content.Context")
-            manager = ctx.getSystemService(Context.VIBRATOR_MANAGER_SERVICE)
-            VibratorManager  # referenced for clarity
-            return manager.getDefaultVibrator()
-        Context = jclass("android.content.Context")
-        return ctx.getSystemService(Context.VIBRATOR_SERVICE)
-    except Exception:
-        return None
-
-
-def _android_buzz(duration_ms: int) -> None:
-    vibrator = _android_vibrator()
-    if vibrator is None:
-        return
-    try:
-        from java import jclass
-
-        Build = jclass("android.os.Build")
-        if Build.VERSION.SDK_INT >= 26:
-            VibrationEffect = jclass("android.os.VibrationEffect")
-            effect = VibrationEffect.createOneShot(int(duration_ms), VibrationEffect.DEFAULT_AMPLITUDE)
-            vibrator.vibrate(effect)
-        else:
-            vibrator.vibrate(int(duration_ms))
-    except Exception:
-        diagnostics.swallowed("haptics._android_buzz")
+        _call("cancel")