pythonnative 0.40.0__cp313-cp313-win_amd64.whl

pythonnative/native_modules/camera.py

@@ -0,0 +1,65 @@
+"""Cross-platform camera and gallery access.
+
+Both entry points are coroutines: ``await Camera.take_photo()`` returns
+the saved image path (a ``str``) or ``None`` if the user cancels. The
+native ``Camera`` module presents ``UIImagePickerController`` (iOS) or
+launches ``MediaStore.ACTION_IMAGE_CAPTURE`` / ``ACTION_PICK``
+(Android) and resolves the call when the picker finishes; Python only
+awaits the promise.
+
+Example:
+    ```python
+    import pythonnative as pn
+
+    async def add_photo():
+        path = await pn.Camera.take_photo()
+        if path is None:
+            return  # user cancelled
+        await save_to_album(path)
+    ```
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from .registry import native_module
+
+
+class Camera:
+    """Camera and image-picker interface (static coroutines)."""
+
+    @staticmethod
+    async def take_photo(**options: Any) -> Optional[str]:
+        """Launch the device camera to capture a photo.
+
+        Args:
+            **options: Forwarded to the native module (``quality``,
+                ``allow_editing``, ...). Unknown keys are ignored.
+
+        Returns:
+            The saved image path, or ``None`` if the user cancelled (or
+            there is no camera to present, as in the browser preview).
+
+        Raises:
+            NativeModuleError: If the picker can't be presented, for
+                example because another picker is already open.
+        """
+        return await _launch("take_photo", options)
+
+    @staticmethod
+    async def pick_from_gallery(**options: Any) -> Optional[str]:
+        """Open the system gallery picker.
+
+        Returns:
+            The selected image path, or ``None`` if the user cancelled.
+
+        Raises:
+            NativeModuleError: If the picker can't be presented.
+        """
+        return await _launch("pick_from_gallery", options)
+
+
+async def _launch(method: str, options: Any) -> Optional[str]:
+    result = await native_module("Camera").call_async(method, **options)
+    return str(result) if result else None

pythonnative/native_modules/clipboard.py

@@ -0,0 +1,46 @@
+"""Cross-platform clipboard access.
+
+[`Clipboard`][pythonnative.Clipboard] reads and writes the system
+pasteboard through the native ``Clipboard`` module (``UIPasteboard``
+on iOS, ``ClipboardManager`` on Android). The pasteboard lives in
+process memory on both platforms, so every method is synchronous.
+
+Off device the module is a process-local string buffer, which keeps it
+usable in ``pn preview`` and unit tests.
+
+Example:
+    ```python
+    import pythonnative as pn
+
+    pn.Clipboard.set_string("hello")
+    assert pn.Clipboard.get_string() == "hello"
+    ```
+"""
+
+from __future__ import annotations
+
+from .registry import native_module
+
+
+class Clipboard:
+    """System clipboard interface (synchronous).
+
+    Raises:
+        NativeModuleError: If the native module reports a failure.
+    """
+
+    @staticmethod
+    def set_string(text: str) -> None:
+        """Copy ``text`` onto the system clipboard."""
+        native_module("Clipboard").call("set_string", text="" if text is None else str(text))
+
+    @staticmethod
+    def get_string() -> str:
+        """Return the current clipboard string (``""`` when empty)."""
+        value = native_module("Clipboard").call("get_string")
+        return "" if value is None else str(value)
+
+    @staticmethod
+    def has_string() -> bool:
+        """Return ``True`` when the clipboard holds non-empty text."""
+        return bool(Clipboard.get_string())

pythonnative/native_modules/fallback.py

@@ -0,0 +1,324 @@
+"""Pure-Python fallbacks for 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 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. Unit tests use them
+directly; the browser preview implements a handful of modules in the
+page (``Alert``, ``Clipboard``, ``Device``, ...) and routes the rest
+here.
+
+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 FallbackDevice:
+    """Static device information for the host machine."""
+
+    def info(self) -> Dict[str, Any]:
+        home = os.path.expanduser("~")
+        app_dir = os.path.join(home, ".pythonnative_data")
+        return {
+            "platform": "test",
+            "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 FallbackAppState:
+    def current_state(self) -> str:
+        return "active"
+
+
+# ======================================================================
+# Storage
+# ======================================================================
+
+
+class FallbackStorage:
+    """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 FallbackSecureStore:
+    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 FallbackClipboard:
+    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 FallbackAlert:
+    """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 FallbackShare:
+    def share(self, message: Optional[str] = None, url: Optional[str] = None, title: Optional[str] = None) -> bool:
+        del message, url, title
+        return False
+
+
+class FallbackLinking:
+    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 FallbackHaptics:
+    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 FallbackBattery:
+    def get_level(self) -> float:
+        return -1.0
+
+    def get_state(self) -> str:
+        return "unknown"
+
+
+class FallbackNetInfo:
+    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 FallbackPermissions:
+    def check(self, permission: str) -> str:
+        del permission
+        return "undetermined"
+
+    def request(self, permission: str) -> str:
+        del permission
+        return "undetermined"
+
+
+class FallbackNotifications:
+    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 FallbackCamera:
+    def take_photo(self) -> Optional[str]:
+        return None
+
+    def pick_from_gallery(self) -> Optional[str]:
+        return None
+
+
+class FallbackLocation:
+    def get_current(self) -> Optional[Dict[str, float]]:
+        return None
+
+
+class FallbackBiometrics:
+    def is_available(self) -> bool:
+        return False
+
+    def authenticate(self, reason: str = "Authenticate") -> bool:
+        del reason
+        return False
+
+
+_DEFAULTS: Dict[str, Callable[[], Any]] = {
+    "Device": FallbackDevice,
+    "AppState": FallbackAppState,
+    "Storage": FallbackStorage,
+    "SecureStore": FallbackSecureStore,
+    "Clipboard": FallbackClipboard,
+    "Alert": FallbackAlert,
+    "Share": FallbackShare,
+    "Linking": FallbackLinking,
+    "Haptics": FallbackHaptics,
+    "Battery": FallbackBattery,
+    "NetInfo": FallbackNetInfo,
+    "Permissions": FallbackPermissions,
+    "Notifications": FallbackNotifications,
+    "Camera": FallbackCamera,
+    "Location": FallbackLocation,
+    "Biometrics": FallbackBiometrics,
+}
+
+
+def default_implementation(name: str) -> Optional[Callable[[], Any]]:
+    """Return the factory for the built-in Python fallback implementation of ``name``."""
+    return _DEFAULTS.get(name)

pythonnative/native_modules/file_system.py

@@ -0,0 +1,145 @@
+"""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
+    from pythonnative import FileSystem
+
+    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 pathlib import Path
+from typing import Any, List, Optional, Union
+
+from .registry import native_module
+
+PathLike = Union[str, "os.PathLike[str]"]
+
+_app_dir_cache: Optional[str] = None
+
+
+class FileSystem:
+    """App-scoped file I/O.
+
+    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 app's Documents directory. Off device, 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.
+        """
+        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 path(path: PathLike = "") -> Path:
+        """Resolve ``path`` against ``app_dir`` and return it as a ``pathlib.Path``.
+
+        Absolute paths are returned unchanged. With no argument, returns
+        ``app_dir`` itself.
+        """
+        candidate = Path(path)
+        return candidate if candidate.is_absolute() else Path(FileSystem.app_dir()) / candidate
+
+    @staticmethod
+    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 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 read_bytes(path: PathLike) -> bytes:
+        """Read a binary file."""
+        return FileSystem.path(path).read_bytes()
+
+    @staticmethod
+    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 exists(path: PathLike) -> bool:
+        """Return whether a file or directory exists."""
+        return FileSystem.path(path).exists()
+
+    @staticmethod
+    def delete(path: PathLike, *, missing_ok: bool = False) -> None:
+        """Delete a single file.
+
+        Args:
+            path: Absolute or ``app_dir``-relative path.
+            missing_ok: Ignore a missing file instead of raising
+                ``FileNotFoundError`` (same as ``Path.unlink``).
+        """
+        FileSystem.path(path).unlink(missing_ok=missing_ok)
+
+    @staticmethod
+    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 get_size(path: PathLike) -> int:
+        """Return a file's size in bytes."""
+        return FileSystem.path(path).stat().st_size
+
+    @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 with the OS separator (``os.path.join`` over ``str(part)``)."""
+        return os.path.join(*[str(p) for p in parts])

pythonnative/native_modules/haptics.py

@@ -0,0 +1,75 @@
+"""Haptic feedback and raw vibration.
+
+Two interfaces live here, both backed by the native ``Haptics`` module:
+
+- [`Haptics`][pythonnative.Haptics]: semantic, iOS-style feedback
+  (impact / notification / selection) backed by
+  ``UIFeedbackGenerator`` on iOS and ``VibrationEffect`` patterns on
+  Android.
+- [`Vibration`][pythonnative.Vibration]: a blunt "buzz for N
+  milliseconds" interface for cases where you want an explicit
+  duration.
+
+Every method is synchronous (the OS queues the effect and returns).
+Missing hardware is not an error: on a device without a Taptic Engine
+or vibrator, and off device the native module simply does nothing.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .registry import native_module
+
+ImpactStyle = str  # "light" | "medium" | "heavy" | "soft" | "rigid"
+NotificationType = str  # "success" | "warning" | "error"
+
+
+def _call(method: str, **args: Any) -> None:
+    native_module("Haptics").call(method, **args)
+
+
+class Haptics:
+    """Semantic haptic feedback (synchronous).
+
+    Raises:
+        NativeModuleError: If the native module fails.
+    """
+
+    @staticmethod
+    def impact(style: ImpactStyle = "medium") -> None:
+        """Play a physical "impact" tap of the given ``style``."""
+        _call("impact", style=style)
+
+    @staticmethod
+    def notification(type_: NotificationType = "success") -> None:
+        """Play a success / warning / error notification pattern."""
+        _call("notification", type=type_)
+
+    @staticmethod
+    def selection() -> None:
+        """Play the light "selection changed" tick."""
+        _call("selection")
+
+
+class Vibration:
+    """Raw vibration control (synchronous).
+
+    Raises:
+        NativeModuleError: If the native module fails.
+    """
+
+    @staticmethod
+    def vibrate(duration_ms: int = 400) -> None:
+        """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)."""
+        _call("cancel")