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

pythonnative/native_modules/camera.py

@@ -38,8 +38,12 @@ class Camera:
                 ``allow_editing``, ...). Unknown keys are ignored.
 
         Returns:
-            The saved image path, or ``None`` if the user cancelled or
-            no camera is available.
+            The saved image path, or ``None`` if the user cancelled (or
+            there is no camera to present, as on desktop).
+
+        Raises:
+            NativeModuleError: If the picker can't be presented, for
+                example because another picker is already open.
         """
         return await _launch("take_photo", options)
 
@@ -49,13 +53,13 @@ class Camera:
 
         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]:
-    try:
-        result = await native_module("Camera").call_async(method, **options)
-    except Exception:
-        return None
+    result = await native_module("Camera").call_async(method, **options)
     return str(result) if result else None

pythonnative/native_modules/clipboard.py

@@ -2,7 +2,8 @@
 
 [`Clipboard`][pythonnative.Clipboard] reads and writes the system
 pasteboard through the native ``Clipboard`` module (``UIPasteboard``
-on iOS, ``ClipboardManager`` on Android). All methods are synchronous.
+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.
@@ -18,28 +19,25 @@ Example:
 
 from __future__ import annotations
 
-from .. import diagnostics
 from .registry import native_module
 
 
 class Clipboard:
-    """System clipboard interface (synchronous)."""
+    """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."""
-        try:
-            native_module("Clipboard").call("set_string", text="" if text is None else str(text))
-        except Exception:
-            diagnostics.swallowed("clipboard.set_string")
+        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)."""
-        try:
-            value = native_module("Clipboard").call("get_string")
-        except Exception:
-            return ""
+        value = native_module("Clipboard").call("get_string")
         return "" if value is None else str(value)
 
     @staticmethod

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,36 +21,44 @@ 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
 
+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. The value comes from the native
+        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.
 
@@ -49,188 +67,79 @@ class FileSystem:
         """
         global _app_dir_cache
         if _app_dir_cache is None:
-            path: Optional[str] = None
-            try:
-                info = native_module("Device").call("info")
-                if isinstance(info, dict):
-                    path = info.get("app_dir")
-            except Exception:
-                path = 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.
+    def path(path: PathLike = "") -> Path:
+        """Resolve ``path`` against ``app_dir`` and return it as a ``pathlib.Path``.
 
-        Args:
-            path: Absolute path or path relative to
-                [`app_dir`][pythonnative.native_modules.file_system.FileSystem.app_dir].
-            encoding: Text encoding (default `"utf-8"`).
-
-        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])

pythonnative/native_modules/haptics.py

@@ -10,16 +10,15 @@ Two interfaces live here, both backed by the native ``Haptics`` module:
   milliseconds" interface for cases where you want an explicit
   duration.
 
-Every method is synchronous and best-effort: on a device that lacks a
-Taptic Engine / vibrator, or on desktop, calls are silent no-ops rather
-than errors.
+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 on desktop, the native module simply does nothing.
 """
 
 from __future__ import annotations
 
 from typing import Any
 
-from .. import diagnostics
 from .registry import native_module
 
 ImpactStyle = str  # "light" | "medium" | "heavy" | "soft" | "rigid"
@@ -27,14 +26,15 @@ NotificationType = str  # "success" | "warning" | "error"
 
 
 def _call(method: str, **args: Any) -> None:
-    try:
-        native_module("Haptics").call(method, **args)
-    except Exception:
-        diagnostics.swallowed(f"haptics.{method}")
+    native_module("Haptics").call(method, **args)
 
 
 class Haptics:
-    """Semantic haptic feedback (synchronous, best-effort)."""
+    """Semantic haptic feedback (synchronous).
+
+    Raises:
+        NativeModuleError: If the native module fails.
+    """
 
     @staticmethod
     def impact(style: ImpactStyle = "medium") -> None:
@@ -53,7 +53,11 @@ class Haptics:
 
 
 class Vibration:
-    """Raw vibration control (synchronous, best-effort)."""
+    """Raw vibration control (synchronous).
+
+    Raises:
+        NativeModuleError: If the native module fails.
+    """
 
     @staticmethod
     def vibrate(duration_ms: int = 400) -> None:

pythonnative/native_modules/linking.py

@@ -5,9 +5,9 @@
 app can hand a URL (``https:``, ``mailto:``, ``tel:``, a custom
 scheme, ...) to the OS.
 
-Outbound methods are synchronous and return a ``bool`` describing
-whether the platform accepted the request. On desktop they return
-``False``.
+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. On desktop they return ``False``.
 
 Inbound deep links flow the other way: declare your schemes in
 ``pythonnative.toml`` (``app.url_schemes``) and the native module
@@ -39,14 +39,15 @@ _url_listeners: List[Callable[[str], None]] = []
 
 
 def _call_bool(method: str, **args: Any) -> bool:
-    try:
-        return bool(native_module("Linking").call(method, **args))
-    except Exception:
-        return False
+    return bool(native_module("Linking").call(method, **args))
 
 
 class Linking:
-    """System URL / deep-link interface (synchronous)."""
+    """System URL / deep-link interface (synchronous).
+
+    Raises:
+        NativeModuleError: If the native module fails.
+    """
 
     @staticmethod
     def open_url(url: str) -> bool:

pythonnative/native_modules/location.py

@@ -2,7 +2,8 @@
 
 [`Location.get_current`][pythonnative.native_modules.location.Location.get_current]
 is a coroutine that resolves to a ``(latitude, longitude)`` tuple, or
-``None`` if no recent fix is available or the user denies permission.
+``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"}``.
@@ -29,7 +30,7 @@ from __future__ import annotations
 
 from typing import Any, Dict, Optional, Tuple
 
-from .registry import native_module
+from .registry import NativeModuleError, native_module
 
 Coords = Tuple[float, float]
 
@@ -48,6 +49,9 @@ class Location:
         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:
@@ -62,16 +66,10 @@ class Location:
         them ``accuracy`` (meters), ``altitude`` (meters), ``speed``
         (m/s), ``heading`` (degrees), ``timestamp`` (Unix seconds).
         """
-        try:
-            result = await native_module("Location").call_async("get_current", **options)
-        except Exception:
-            return None
+        result = await native_module("Location").call_async("get_current", **options)
         if not isinstance(result, dict):
             return None
-        try:
-            fix: Dict[str, float] = {k: float(v) for k, v in result.items() if v is not None}
-            fix["latitude"]
-            fix["longitude"]
-        except (KeyError, TypeError, ValueError):
-            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

@@ -41,10 +41,7 @@ class NetInfo:
     def fetch() -> NetInfoState:
         """Return a fresh snapshot of connectivity state."""
         global _last_state
-        try:
-            snapshot = native_module("NetInfo").call("fetch")
-        except Exception:
-            snapshot = None
+        snapshot = native_module("NetInfo").call("fetch")
         if isinstance(snapshot, dict):
             _last_state = _normalize(snapshot)
         return dict(_last_state)

pythonnative/native_modules/notifications.py

@@ -39,7 +39,7 @@ from __future__ import annotations
 
 from typing import Any, Optional
 
-from .registry import NativeModuleError, native_module
+from .registry import native_module
 
 
 class Notifications:
@@ -55,13 +55,13 @@ class Notifications:
         is shown if the user hasn't decided yet.
 
         Returns:
-            ``True`` if granted (or no prompt is needed), ``False``
-            otherwise.
+            ``True`` if granted (or no prompt is needed), ``False`` if
+            the user declined (always ``False`` on desktop).
+
+        Raises:
+            NativeModuleError: If the native module fails.
         """
-        try:
-            return bool(await native_module("Notifications").call_async("request_permission"))
-        except Exception:
-            return False
+        return bool(await native_module("Notifications").call_async("request_permission"))
 
     @staticmethod
     async def schedule(
@@ -86,30 +86,26 @@ class Notifications:
                 ``badge``, ...). Unknown keys are ignored.
 
         Returns:
-            ``True`` on success, ``False`` if the underlying native
-            call failed or (on Android 13+) the user denied the
-            notification permission.
+            ``True`` once scheduled, ``False`` if the user has denied
+            notification permission (so nothing was scheduled).
+
+        Raises:
+            NativeModuleError: If the native module fails.
         """
-        try:
-            result = await native_module("Notifications").call_async(
-                "schedule",
-                title=title,
-                body=body,
-                delay_seconds=float(delay_seconds),
-                identifier=identifier,
-                **options,
-            )
-        except Exception:
-            return False
+        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."""
-        try:
-            await native_module("Notifications").call_async("cancel", identifier=identifier)
-        except Exception:
-            pass
+        """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]:
@@ -126,11 +122,8 @@ class Notifications:
             remote push support (Android and desktop).
 
         Raises:
-            RuntimeError: If APNs registration fails, with the native
-                error description.
+            NativeModuleError: If APNs registration fails; ``code`` is
+                ``"apns"`` and the message carries the system's error.
         """
-        try:
-            token = await native_module("Notifications").call_async("get_device_token")
-        except NativeModuleError as exc:
-            raise RuntimeError(f"APNs registration failed: {exc.message}") from exc
+        token = await native_module("Notifications").call_async("get_device_token")
         return str(token) if token else None