pythonnative 0.36.0__py3-none-any.whl → 0.38.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

@@ -1,9 +1,19 @@
-"""Cross-platform app-scoped file I/O.
-
-Provides static helpers for reading, writing, and deleting files in the
-app's sandboxed storage area. Relative paths are resolved against
-[`FileSystem.app_dir`][pythonnative.native_modules.file_system.FileSystem.app_dir];
-absolute paths are used as-is.
+"""App-scoped file I/O.
+
+[`FileSystem`][pythonnative.FileSystem] answers one question the
+standard library can't, "where may this app write?", and then gets out
+of the way: [`app_dir`][pythonnative.native_modules.file_system.FileSystem.app_dir]
+comes from the native ``Device`` module, and
+[`path`][pythonnative.native_modules.file_system.FileSystem.path] turns
+an app-relative name into a ``pathlib.Path`` you use like any other.
+The read/write helpers are thin conveniences over that path; they
+raise the same ``OSError`` subclasses ``open`` and ``os`` do
+(``FileNotFoundError``, ``PermissionError``, ...) rather than hiding
+them behind ``None`` and ``False``.
+
+Relative paths are resolved against ``app_dir``; absolute paths are used
+as-is. Everything here is synchronous: it is local disk I/O on the
+calling thread, exactly like the standard library.
 
 Example:
     ```python
@@ -11,232 +21,125 @@ Example:
 
     FileSystem.write_text("notes/today.txt", "Hello, file system!")
     print(FileSystem.read_text("notes/today.txt"))
+
+    # Or work with the Path directly:
+    notes = FileSystem.path("notes")
+    for entry in sorted(notes.iterdir()):
+        print(entry.name)
     ```
 """
 
+from __future__ import annotations
+
 import os
-from typing import Any, Optional
+from pathlib import Path
+from typing import Any, List, Optional, Union
+
+from .registry import native_module
 
-from .. import diagnostics
-from ..utils import IS_ANDROID
+PathLike = Union[str, "os.PathLike[str]"]
+
+_app_dir_cache: Optional[str] = None
 
 
 class FileSystem:
     """App-scoped file I/O.
 
-    Every instance method operates on either an absolute path or a path
-    relative to
-    [`app_dir`][pythonnative.native_modules.file_system.FileSystem.app_dir].
-    Errors are swallowed and reported as falsy return values (`None`
-    for readers, `False` for writers) so callers can treat the API as
-    best-effort.
+    Every helper accepts an absolute path or a path relative to
+    [`app_dir`][pythonnative.native_modules.file_system.FileSystem.app_dir],
+    and raises ``OSError`` (or a subclass) when the operation fails,
+    like the standard library it wraps.
     """
 
     @staticmethod
     def app_dir() -> str:
         """Return the app's writable data directory.
 
-        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.
+        On Android the result is ``Context.getFilesDir()``. On iOS it is
+        the app's Documents directory. On a desktop machine without
+        either runtime, a ``.pythonnative_data`` directory under the
+        user's home folder is used. 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:
-            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)
-            except Exception:
-                diagnostics.swallowed("file_system.FileSystem.app_dir")
-        return os.path.join(os.path.expanduser("~"), ".pythonnative_data")
+        global _app_dir_cache
+        if _app_dir_cache is None:
+            info = native_module("Device").call("info")
+            path = info.get("app_dir") if isinstance(info, dict) else 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]:
-        """Read a text file.
-
-        Args:
-            path: Absolute path or path relative to
-                [`app_dir`][pythonnative.native_modules.file_system.FileSystem.app_dir].
-            encoding: Text encoding (default `"utf-8"`).
+    def path(path: PathLike = "") -> Path:
+        """Resolve ``path`` against ``app_dir`` and return it as a ``pathlib.Path``.
 
-        Returns:
-            File contents as a `str`, or `None` if the file cannot be
-            read.
+        Absolute paths are returned unchanged. With no argument, returns
+        ``app_dir`` itself.
         """
-        full = path if os.path.isabs(path) else os.path.join(FileSystem.app_dir(), path)
-        try:
-            with open(full, encoding=encoding) as f:
-                return f.read()
-        except OSError:
-            return None
+        candidate = Path(path)
+        return candidate if candidate.is_absolute() else Path(FileSystem.app_dir()) / candidate
 
     @staticmethod
-    def write_text(path: str, content: str, encoding: str = "utf-8") -> bool:
-        """Write a text file, creating parent directories as needed.
-
-        Args:
-            path: Absolute or `app_dir`-relative path.
-            content: String to write.
-            encoding: Text encoding (default `"utf-8"`).
-
-        Returns:
-            `True` on success, `False` on `OSError`.
-        """
-        full = path if os.path.isabs(path) else os.path.join(FileSystem.app_dir(), path)
-        try:
-            os.makedirs(os.path.dirname(full), exist_ok=True)
-            with open(full, "w", encoding=encoding) as f:
-                f.write(content)
-            return True
-        except OSError:
-            return False
+    def read_text(path: PathLike, encoding: str = "utf-8") -> str:
+        """Read a text file; raises ``FileNotFoundError`` and friends like ``open`` does."""
+        return FileSystem.path(path).read_text(encoding=encoding)
 
     @staticmethod
-    def exists(path: str) -> bool:
-        """Return whether a file or directory exists.
-
-        Args:
-            path: Absolute or `app_dir`-relative path.
-
-        Returns:
-            `True` if the path exists.
-        """
-        full = path if os.path.isabs(path) else os.path.join(FileSystem.app_dir(), path)
-        return os.path.exists(full)
+    def write_text(path: PathLike, content: str, encoding: str = "utf-8") -> None:
+        """Write a text file, creating parent directories as needed."""
+        target = FileSystem.path(path)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(content, encoding=encoding)
 
     @staticmethod
-    def delete(path: str) -> bool:
-        """Delete a single file.
-
-        Args:
-            path: Absolute or `app_dir`-relative path.
-
-        Returns:
-            `True` on success, `False` on `OSError`.
-        """
-        full = path if os.path.isabs(path) else os.path.join(FileSystem.app_dir(), path)
-        try:
-            os.remove(full)
-            return True
-        except OSError:
-            return False
+    def read_bytes(path: PathLike) -> bytes:
+        """Read a binary file."""
+        return FileSystem.path(path).read_bytes()
 
     @staticmethod
-    def list_dir(path: str = "") -> list:
-        """List the entries in a directory.
-
-        Args:
-            path: Absolute or `app_dir`-relative path. Defaults to the
-                app data directory itself.
-
-        Returns:
-            A list of entry names, or an empty list on error.
-        """
-        full = path if os.path.isabs(path) else os.path.join(FileSystem.app_dir(), path)
-        try:
-            return os.listdir(full)
-        except OSError:
-            return []
+    def write_bytes(path: PathLike, data: bytes) -> None:
+        """Write a binary file, creating parent directories as needed."""
+        target = FileSystem.path(path)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_bytes(data)
 
     @staticmethod
-    def read_bytes(path: str) -> Optional[bytes]:
-        """Read a binary file.
-
-        Args:
-            path: Absolute or `app_dir`-relative path.
-
-        Returns:
-            File contents as `bytes`, or `None` if the file cannot be
-            read.
-        """
-        full = path if os.path.isabs(path) else os.path.join(FileSystem.app_dir(), path)
-        try:
-            with open(full, "rb") as f:
-                return f.read()
-        except OSError:
-            return None
+    def exists(path: PathLike) -> bool:
+        """Return whether a file or directory exists."""
+        return FileSystem.path(path).exists()
 
     @staticmethod
-    def write_bytes(path: str, data: bytes) -> bool:
-        """Write a binary file, creating parent directories as needed.
+    def delete(path: PathLike, *, missing_ok: bool = False) -> None:
+        """Delete a single file.
 
         Args:
-            path: Absolute or `app_dir`-relative path.
-            data: Bytes to write.
-
-        Returns:
-            `True` on success, `False` on `OSError`.
+            path: Absolute or ``app_dir``-relative path.
+            missing_ok: Ignore a missing file instead of raising
+                ``FileNotFoundError`` (same as ``Path.unlink``).
         """
-        full = path if os.path.isabs(path) else os.path.join(FileSystem.app_dir(), path)
-        try:
-            os.makedirs(os.path.dirname(full), exist_ok=True)
-            with open(full, "wb") as f:
-                f.write(data)
-            return True
-        except OSError:
-            return False
+        FileSystem.path(path).unlink(missing_ok=missing_ok)
 
     @staticmethod
-    def get_size(path: str) -> Optional[int]:
-        """Return file size in bytes.
-
-        Args:
-            path: Absolute or `app_dir`-relative path.
-
-        Returns:
-            File size in bytes, or `None` if the file is missing or
-            unreadable.
-        """
-        full = path if os.path.isabs(path) else os.path.join(FileSystem.app_dir(), path)
-        try:
-            return os.path.getsize(full)
-        except OSError:
-            return None
+    def list_dir(path: PathLike = "") -> List[str]:
+        """Return the entry names in a directory (``app_dir`` by default), sorted."""
+        return sorted(entry.name for entry in FileSystem.path(path).iterdir())
 
     @staticmethod
-    def ensure_dir(path: str) -> bool:
-        """Create a directory (and any missing parents) idempotently.
-
-        Args:
-            path: Absolute or `app_dir`-relative path.
+    def get_size(path: PathLike) -> int:
+        """Return a file's size in bytes."""
+        return FileSystem.path(path).stat().st_size
 
-        Returns:
-            `True` on success or if the directory already exists.
-        """
-        full = path if os.path.isabs(path) else os.path.join(FileSystem.app_dir(), path)
-        try:
-            os.makedirs(full, exist_ok=True)
-            return True
-        except OSError:
-            return False
+    @staticmethod
+    def ensure_dir(path: PathLike) -> Path:
+        """Create a directory (and any missing parents) if needed; returns its ``Path``."""
+        target = FileSystem.path(path)
+        target.mkdir(parents=True, exist_ok=True)
+        return target
 
     @staticmethod
     def join(*parts: Any) -> str:
-        """Join path components using the OS separator.
-
-        Equivalent to `os.path.join(*map(str, parts))`. Provided as a
-        convenience so callers do not need to import `os.path`
-        directly.
-
-        Args:
-            *parts: Path components (each coerced to `str`).
-
-        Returns:
-            The joined path string.
-        """
+        """Join path components with the OS separator (``os.path.join`` over ``str(part)``)."""
         return os.path.join(*[str(p) for p in parts])