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

pythonnative/__init__.py

@@ -62,7 +62,7 @@ Example:
     ```
 """
 
-__version__ = "0.37.0"
+__version__ = "0.38.0"
 
 from . import appearance, diagnostics, gestures, images, runtime, sdk
 from .alerts import Alert
@@ -190,6 +190,7 @@ from .style import (
     AutoCapitalize,
     Color,
     Dimension,
+    Display,
     EdgeInsets,
     FlexDirection,
     FlexWrap,
@@ -198,6 +199,7 @@ from .style import (
     KeyboardType,
     LayoutDirection,
     Overflow,
+    PointerEvents,
     Position,
     ReturnKeyType,
     ScaleType,
@@ -207,6 +209,8 @@ from .style import (
     StyleSheet,
     TextAlign,
     TextDecoration,
+    TextTransform,
+    Theme,
     ThemeContext,
     TransformSpec,
     default_theme,
@@ -314,6 +318,7 @@ __all__ = [
     "DEFAULT_DARK_THEME",
     "DEFAULT_LIGHT_THEME",
     "Dimension",
+    "Display",
     "EdgeInsets",
     "FlexDirection",
     "FlexWrap",
@@ -322,6 +327,7 @@ __all__ = [
     "KeyboardType",
     "LayoutDirection",
     "Overflow",
+    "PointerEvents",
     "Position",
     "ReturnKeyType",
     "ScaleType",
@@ -331,6 +337,8 @@ __all__ = [
     "StyleSheet",
     "TextAlign",
     "TextDecoration",
+    "TextTransform",
+    "Theme",
     "ThemeContext",
     "TransformSpec",
     "default_theme",

pythonnative/alerts.py

@@ -56,12 +56,9 @@ async def _present(
     implementation records the call and answers from the queue set by
     [`Alert.set_test_response`][pythonnative.alerts.Alert.set_test_response].
     """
-    try:
-        result = await native_module("Alert").call_async(
-            "present", title=title, message=message, buttons=buttons, style=style
-        )
-    except Exception:
-        return -1
+    result = await native_module("Alert").call_async(
+        "present", title=title, message=message, buttons=buttons, style=style
+    )
     try:
         return int(result)
     except (TypeError, ValueError):
@@ -135,14 +132,9 @@ class Alert:
         [`choose`][pythonnative.alerts.Alert.choose] and ``await``
         the result.
         """
-        try:
-            native_module("Alert").call(
-                "show", title=title, message=message, buttons=[{"label": button, "style": "default"}], style="alert"
-            )
-        except Exception:
-            from . import diagnostics
-
-            diagnostics.swallowed("alerts.Alert.show")
+        native_module("Alert").call(
+            "show", title=title, message=message, buttons=[{"label": button, "style": "default"}], style="alert"
+        )
 
     @staticmethod
     async def confirm(

pythonnative/cli/pn.py

@@ -6,6 +6,9 @@ The console script `pn` (declared in `pyproject.toml`) dispatches to:
   ``app/``) into ``./name/``, or into the current directory when no name
   is given.
 - `pn doctor [platform]`: diagnose the local toolchain and config.
+- `pn deps [platform]`: resolve ``[requirements].packages`` for every
+  device target and report which wheels would be used (or why a package
+  can't be installed), without building anything.
 - `pn preview [component]`: render the app in a desktop (Tkinter) window
   with Fast Refresh, the fast inner dev loop, no device required.
 - `pn devices [platform]`: list connected devices, emulators, and
@@ -41,6 +44,7 @@ from pathlib import Path
 from typing import Any, Dict, List, Optional, TextIO
 
 from ..project import builder as builder_mod
+from ..project import deps as deps_mod
 from ..project import devices as devices_mod
 from ..project import doctor as doctor_mod
 from ..project.android import collect_logcat_filters
@@ -54,22 +58,29 @@ HOT_RELOAD_DEV_ROOT = "pythonnative_dev"
 # init
 # ======================================================================
 
-_MAIN_TEMPLATE = """import pythonnative as pn
+_MAIN_TEMPLATE = """from typing import TypedDict
+
+import pythonnative as pn
 
 Stack = pn.create_stack_navigator()
 
 
+class DetailParams(TypedDict):
+    count: int
+
+
 @pn.component
 def HomeScreen():
     count, set_count = pn.use_state(0)
     nav = pn.use_navigation()
+    theme = pn.use_theme()
     return pn.ScrollView(
         pn.Column(
-            pn.Text("Hello from PythonNative!", style={"font_size": 24, "bold": True}),
+            pn.Text("Hello from PythonNative!", style={"font_size": theme.font_size_title, "bold": True}),
             pn.Text(f"Tapped {count} times"),
             pn.Button("Tap me", on_press=lambda: set_count(count + 1)),
-            pn.Button("Open detail", on_press=lambda: nav.navigate("Detail", {"count": count})),
-            style={"spacing": 12, "padding": 16, "align_items": "stretch"},
+            pn.Button("Open detail", on_press=lambda: nav.navigate("Detail", count=count)),
+            style={"spacing": theme.spacing_large, "padding": 16, "align_items": "stretch"},
         )
     )
 
@@ -77,9 +88,9 @@ def HomeScreen():
 @pn.component
 def DetailScreen():
     nav = pn.use_navigation()
-    params = pn.use_route()
+    route = pn.use_route(DetailParams)
     return pn.Column(
-        pn.Text(f"Detail: count was {params.get('count', 0)}", style={"font_size": 20}),
+        pn.Text(f"Detail: count was {route.params['count']}", style={"font_size": 20}),
         pn.Button("Back", on_press=nav.go_back),
         style={"spacing": 12, "padding": 16},
     )
@@ -89,8 +100,8 @@ def DetailScreen():
 def App():
     return pn.NavigationContainer(
         Stack.Navigator(
-            Stack.Screen("Home", component=HomeScreen, options={"title": "Home"}),
-            Stack.Screen("Detail", component=DetailScreen, options={"title": "Detail"}),
+            Stack.Screen("Home", HomeScreen, title="Home"),
+            Stack.Screen("Detail", DetailScreen, title="Detail"),
         )
     )
 """
@@ -278,6 +289,56 @@ def app_id_command(args: argparse.Namespace) -> None:
     print(config.application_id if args.platform == "android" else config.bundle_id)
 
 
+# ======================================================================
+# deps
+# ======================================================================
+
+
+def deps_command(args: argparse.Namespace) -> None:
+    """Report how ``[requirements].packages`` resolve for each device target.
+
+    Runs pip in its cross-platform dry-run mode once per target (iOS
+    device, iOS Simulator, and one per Android ABI) and prints the
+    wheel each package would use, flagging binary wheels and their
+    source index. Exits non-zero when any target can't be satisfied,
+    so it doubles as a CI gate. ``--json`` emits the same data as a
+    machine-readable document.
+
+    Args:
+        args: Parsed namespace with optional ``platform``, ``json``, and
+            ``python`` (the interpreter to run pip with).
+    """
+    platform: Optional[str] = getattr(args, "platform", None)
+    as_json: bool = getattr(args, "json", False)
+    python: Optional[str] = getattr(args, "python", None)
+
+    config = _load_config_or_exit()
+    targets = deps_mod.targets_for(config, platform)
+    runner = builder_mod.SubprocessRunner()
+    if not as_json and config.requirements:
+        print(
+            f"Resolving {len(config.requirements)} requirement(s) for Python {config.python_version} "
+            f"across {len(targets)} target(s)...\n"
+        )
+    resolutions = deps_mod.resolve_all(config, targets, runner=runner, python=python)
+
+    if as_json:
+        print(
+            json.dumps(
+                {
+                    "python_version": config.python_version,
+                    "requirements": list(config.requirements),
+                    "targets": [res.to_dict() for res in resolutions],
+                },
+                indent=2,
+            )
+        )
+    else:
+        print(deps_mod.format_report(resolutions, requirements=config.requirements))
+    if any(not res.ok for res in resolutions):
+        sys.exit(1)
+
+
 # ======================================================================
 # preview
 # ======================================================================
@@ -426,8 +487,18 @@ def run_project(args: argparse.Namespace) -> None:
     config = _load_config_or_exit()
     builder = builder_mod.Builder(config, log=print)
 
+    # Resolve third-party packages only for the destination being built
+    # (device wheels and Simulator wheels differ); prepare-only keeps both
+    # slices so the staged project builds for either in Xcode.
+    if prepare_only:
+        ios_sdks: tuple = deps_mod.IOS_SDKS
+    elif device is not None and device.kind == "device":
+        ios_sdks = ("iphoneos",)
+    else:
+        ios_sdks = ("iphonesimulator",)
+
     try:
-        prepared = builder.prepare(platform)
+        prepared = builder.prepare(platform, ios_sdks=ios_sdks)
     except builder_mod.BuildError as exc:
         print(f"Error: {exc}")
         sys.exit(1)
@@ -593,7 +664,11 @@ def build_project(args: argparse.Namespace) -> None:
         sys.exit(1)
 
     try:
-        prepared = builder.prepare(platform, release=not debug)
+        prepared = builder.prepare(
+            platform,
+            release=not debug,
+            ios_sdks=("iphonesimulator",) if debug else ("iphoneos",),
+        )
         if platform == "android":
             artifacts = builder.build_android(prepared, debug=debug)
         else:
@@ -1020,6 +1095,17 @@ def _build_parser() -> argparse.ArgumentParser:
     parser_doctor.add_argument("platform", nargs="?", choices=["android", "ios"], help="Restrict checks to a platform")
     parser_doctor.set_defaults(func=doctor_command)
 
+    parser_deps = subparsers.add_parser(
+        "deps", help="Check which wheels [requirements].packages resolve to on each device target"
+    )
+    parser_deps.add_argument("platform", nargs="?", choices=["android", "ios"], help="Restrict to a platform")
+    parser_deps.add_argument("--json", action="store_true", help="Print a JSON report for scripting")
+    parser_deps.add_argument(
+        "--python",
+        help="Interpreter to run pip with (default: the one running pn; any version works, pip cross-resolves)",
+    )
+    parser_deps.set_defaults(func=deps_command)
+
     parser_preview = subparsers.add_parser("preview", help="Render the app in a desktop window")
     parser_preview.add_argument(
         "component",

pythonnative/components/_base.py

@@ -76,6 +76,37 @@ def _make_element(
     return Element(name, out, list(children), key=key)
 
 
+# ======================================================================
+# RefreshControl attachment
+# ======================================================================
+
+REFRESH_CONTROL_TYPE = "RefreshControl"
+"""Element type produced by [`RefreshControl`][pythonnative.RefreshControl]."""
+
+
+def _refresh_control_props(control: Optional[Element], *, owner: str) -> Optional[Dict[str, Any]]:
+    """Turn a ``RefreshControl`` element into the ``refresh_control`` wire prop.
+
+    Scroll containers hold their refresh control as a prop rather than
+    a child (the native side attaches a ``UIRefreshControl`` /
+    ``SwipeRefreshLayout`` to the scroll view itself), so the element
+    is unwrapped here into the flat dict the bridge and the event
+    extractor expect. Keeping it an element on the Python side means
+    users build it like every other piece of UI and get a clear error
+    if they pass the wrong thing.
+
+    Raises:
+        TypeError: If ``control`` is not a ``RefreshControl`` element.
+    """
+    if control is None:
+        return None
+    if not isinstance(control, Element) or control.type != REFRESH_CONTROL_TYPE:
+        raise TypeError(
+            f"{owner}(refresh_control=...) expects pn.RefreshControl(...), got {type(control).__name__}: {control!r}"
+        )
+    return dict(control.props)
+
+
 # ======================================================================
 # Rich text spans
 # ======================================================================

pythonnative/components/controls.py

@@ -2,7 +2,7 @@
 
 ``Switch``, ``Slider``, ``ProgressBar``, ``ActivityIndicator``,
 ``Checkbox``, ``SegmentedControl``, ``DatePicker``, ``Picker``, the
-``RefreshControl`` spec helper, and ``StatusBar``.
+``RefreshControl``, and ``StatusBar``.
 """
 
 from typing import Any, Callable, Dict, List, Literal, Optional
@@ -10,7 +10,7 @@ from typing import Any, Callable, Dict, List, Literal, Optional
 from ..element import Element
 from ..hooks import Ref
 from ..style import AccessibilityState, Color, StyleProp
-from ._base import _make_element
+from ._base import REFRESH_CONTROL_TYPE, _make_element
 
 
 def Switch(
@@ -426,13 +426,17 @@ def RefreshControl(
     refreshing: bool = False,
     on_refresh: Optional[Callable[[], Any]] = None,
     tint_color: Optional[Color] = None,
-) -> Dict[str, Any]:
-    """Pull-to-refresh spec for [`ScrollView`][pythonnative.ScrollView] / [`FlatList`][pythonnative.FlatList].
+) -> Element:
+    """Pull-to-refresh control for [`ScrollView`][pythonnative.ScrollView] and the list components.
 
-    Returns a plain dict that should be passed as the
-    ``refresh_control=`` prop. Modeled as a dict (not an
-    [`Element`][pythonnative.Element]) so the host scroll container can
-    hold one without it appearing as a child node.
+    Pass the result as the ``refresh_control=`` prop of a
+    [`ScrollView`][pythonnative.ScrollView],
+    [`FlatList`][pythonnative.FlatList], or
+    [`SectionList`][pythonnative.SectionList]. It is a regular
+    [`Element`][pythonnative.Element] (type ``"RefreshControl"``) built
+    like every other piece of UI; the scroll container attaches it to
+    its native scroll view rather than rendering it as a child, and
+    rejects anything else with a ``TypeError``.
 
     Args:
         refreshing: Drive the spinner's visibility from a use_state
@@ -443,8 +447,7 @@ def RefreshControl(
         tint_color: Color of the spinner.
 
     Returns:
-        Dict suitable for the ``refresh_control`` prop on a scroll
-        container.
+        An [`Element`][pythonnative.Element] of type ``"RefreshControl"``.
 
     Example:
         ```python
@@ -467,12 +470,12 @@ def RefreshControl(
             )
         ```
     """
-    spec: Dict[str, Any] = {"refreshing": bool(refreshing)}
-    if on_refresh is not None:
-        spec["on_refresh"] = on_refresh
-    if tint_color is not None:
-        spec["tint_color"] = tint_color
-    return spec
+    return _make_element(
+        REFRESH_CONTROL_TYPE,
+        refreshing=bool(refreshing),
+        on_refresh=on_refresh,
+        tint_color=tint_color,
+    )
 
 
 def StatusBar(

pythonnative/components/layout.py

@@ -12,7 +12,7 @@ from ..component import component
 from ..element import Element
 from ..hooks import Ref, use_keyboard_height, use_safe_area_insets, use_state
 from ..style import AccessibilityState, StyleProp, resolve_style
-from ._base import _make_element
+from ._base import _make_element, _refresh_control_props
 
 
 def View(
@@ -281,7 +281,7 @@ def Spacer(
 
 def ScrollView(
     *children: Element,
-    refresh_control: Optional[Dict[str, Any]] = None,
+    refresh_control: Optional[Element] = None,
     scroll_axis: Optional[Literal["vertical", "horizontal"]] = None,
     on_scroll: Optional[Callable[[Dict[str, float]], None]] = None,
     shows_scroll_indicator: bool = True,
@@ -302,11 +302,8 @@ def ScrollView(
 
     Args:
         *children: Child elements to scroll.
-        refresh_control: Optional pull-to-refresh spec, typically
-            constructed via
-            [`RefreshControl`][pythonnative.RefreshControl]. The dict
-            must have ``refreshing`` (bool) and ``on_refresh``
-            (callable).
+        refresh_control: Optional [`RefreshControl`][pythonnative.RefreshControl]
+            element attached to the scroll view for pull-to-refresh.
         scroll_axis: ``"vertical"`` (default) or ``"horizontal"``.
         on_scroll: Callback invoked with ``{"x": …, "y": …}`` content
             offsets as the user scrolls.
@@ -333,7 +330,7 @@ def ScrollView(
         style=style,
         ref=ref,
         key=key,
-        refresh_control=refresh_control,
+        refresh_control=_refresh_control_props(refresh_control, owner="ScrollView"),
         scroll_axis=scroll_axis,
         on_scroll=on_scroll,
         shows_scroll_indicator=False if shows_scroll_indicator is False else None,

pythonnative/components/lists.py

@@ -124,7 +124,7 @@ def _VirtualizedList(
     header: Optional[Element] = None,
     footer: Optional[Element] = None,
     empty: Optional[Element] = None,
-    refresh_control: Optional[Dict[str, Any]] = None,
+    refresh_control: Optional[Element] = None,
     on_end_reached: Optional[Callable[[], Any]] = None,
     on_end_reached_threshold: Optional[float] = None,
     on_viewable_items_changed: Optional[Callable[[List[Dict[str, Any]]], None]] = None,
@@ -464,7 +464,7 @@ def FlatList(
     get_item_height: Optional[Callable[[Any, int], float]] = None,
     estimated_item_height: Optional[float] = None,
     separator_height: float = 0,
-    refresh_control: Optional[Dict[str, Any]] = None,
+    refresh_control: Optional[Element] = None,
     horizontal: bool = False,
     num_columns: int = 1,
     list_header: Optional[Element] = None,
@@ -509,8 +509,8 @@ def FlatList(
         estimated_item_height: Starting extent estimate for rows whose
             true size isn't known yet (default 44).
         separator_height: Gap below each row, in points.
-        refresh_control: Optional pull-to-refresh spec from
-            [`RefreshControl`][pythonnative.RefreshControl].
+        refresh_control: Optional [`RefreshControl`][pythonnative.RefreshControl]
+            element for pull-to-refresh.
         horizontal: Scroll horizontally (extents become widths).
         num_columns: Render items in a grid of this many columns.
         list_header: Element rendered once before all rows.
@@ -666,7 +666,7 @@ def SectionList(
     estimated_item_height: Optional[float] = None,
     section_header_height: Optional[float] = None,
     separator_height: float = 0,
-    refresh_control: Optional[Dict[str, Any]] = None,
+    refresh_control: Optional[Element] = None,
     list_header: Optional[Element] = None,
     list_footer: Optional[Element] = None,
     list_empty: Optional[Element] = None,
@@ -699,7 +699,7 @@ def SectionList(
         estimated_item_height: Starting estimate for unmeasured rows.
         section_header_height: Header extent in points, when known.
         separator_height: Gap below each item, in points.
-        refresh_control: Optional pull-to-refresh spec.
+        refresh_control: Optional [`RefreshControl`][pythonnative.RefreshControl] element.
         list_header: Element rendered once before everything.
         list_footer: Element rendered once after everything.
         list_empty: Element rendered when there are no sections.

pythonnative/gestures.py

@@ -78,6 +78,7 @@ from __future__ import annotations
 
 import math
 from dataclasses import dataclass, field
+from enum import Enum
 from typing import Any, Callable, Dict, List, Literal, Optional, Sequence, Set, Tuple
 
 __all__ = [
@@ -99,16 +100,30 @@ __all__ = [
 ]
 
 
-class GestureState:
-    """States reported on [`GestureEvent.state`][pythonnative.gestures.GestureEvent]."""
+class GestureState(str, Enum):
+    """Lifecycle states reported on [`GestureEvent.state`][pythonnative.gestures.GestureEvent].
+
+    A ``str`` enum, so members compare equal to their wire value
+    (``GestureState.ENDED == "ended"``) and serialize as plain strings
+    across the native bridge, while callers get exhaustive
+    ``match`` support and autocomplete.
+
+    Attributes:
+        BEGAN: The gesture activated (first callback).
+        CHANGED: A continuous gesture updated (pan, pinch, rotation).
+        ENDED: The gesture completed successfully.
+        CANCELLED: The gesture was interrupted (lost arbitration, view
+            unmounted, pointer left the window).
+    """
 
     BEGAN = "began"
     CHANGED = "changed"
     ENDED = "ended"
     CANCELLED = "cancelled"
 
+    def __str__(self) -> str:
+        return self.value
 
-GestureStateName = Literal["began", "changed", "ended", "cancelled"]
 
 GestureCallback = Callable[["GestureEvent"], Any]
 
@@ -141,7 +156,7 @@ class GestureEvent:
     """
 
     kind: str
-    state: GestureStateName
+    state: GestureState
     x: float = 0.0
     y: float = 0.0
     translation_x: float = 0.0
@@ -153,6 +168,12 @@ class GestureEvent:
     pointer_count: int = 1
     direction: Optional[str] = None
 
+    def __post_init__(self) -> None:
+        # Payloads from the native bridge carry plain strings; coerce
+        # so ``event.state`` is always a ``GestureState`` member.
+        if not isinstance(self.state, GestureState):
+            object.__setattr__(self, "state", GestureState(self.state))
+
 
 _EVENT_FIELDS = frozenset(
     {
@@ -576,8 +597,8 @@ class _Recognizer:
         self.config = config
         self._emit_fn = emit
 
-    def emit(self, state: str, **fields: Any) -> None:
-        payload: Dict[str, Any] = {"kind": self.kind(), "state": state}
+    def emit(self, state: GestureState, **fields: Any) -> None:
+        payload: Dict[str, Any] = {"kind": self.kind(), "state": state.value}
         payload.update(fields)
         self._emit_fn(self.index, payload)
 

pythonnative/native_modules/__init__.py

@@ -17,6 +17,25 @@ feedback), so the same code stays runnable off device. Third-party
 packages ship their own native modules the same way; see
 ``docs/guides/native-modules.md``.
 
+Two rules hold across every facade, so you never have to look one up:
+
+1. **Sync or async is decided by what the OS has to do.** A method is
+   a plain function when the answer is already on the device and
+   returns on the calling thread (read the pasteboard, check a
+   permission, read the battery level, Keychain get/set, file I/O).
+   It is a coroutine when the OS has to prompt the user, drive
+   hardware, or hand off to another process (camera and gallery
+   pickers, biometric prompts, permission requests, the share sheet,
+   GPS fixes, notification scheduling, remote push registration).
+2. **Failures raise; "nothing happened" returns a value.** A native
+   error (a rejected promise, a missing module, a bad argument) is a
+   [`NativeModuleError`][pythonnative.native_modules.NativeModuleError]
+   and propagates to the caller like any other Python exception. Outcomes
+   that are not errors, such as the user cancelling a picker, denying a
+   permission, or dismissing the share sheet, come back as ``None``,
+   ``False``, or a status string, and are documented per method. No
+   facade converts an exception into a default value.
+
 Hardware / media:
 
 - [`Camera`][pythonnative.native_modules.Camera]: photo capture and

pythonnative/native_modules/battery.py

@@ -1,10 +1,11 @@
 """Battery level and charging state.
 
 [`Battery`][pythonnative.Battery] reports the current charge fraction
-(``0.0``–``1.0``, or ``-1.0`` when unknown) and charging state, and
-lets you subscribe to changes. The native ``Battery`` module pushes a
-``change`` event with ``{"level", "state"}``; off device, tests drive
-the same path through
+(``0.0`` to ``1.0``, or ``-1.0`` when the platform doesn't know) and
+charging state, and lets you subscribe to changes. Both getters read a
+value the OS already holds, so they are synchronous. The native
+``Battery`` module pushes a ``change`` event with ``{"level", "state"}``;
+off device, tests drive the same path through
 [`dispatch_battery`][pythonnative.native_modules.battery.dispatch_battery].
 """
 
@@ -21,24 +22,22 @@ _listeners: List[Callable[[Dict[str, object]], None]] = []
 
 
 class Battery:
-    """Battery interface (synchronous getters + change listener)."""
+    """Battery interface (synchronous getters + change listener).
+
+    Raises:
+        NativeModuleError: If the native module fails.
+    """
 
     @staticmethod
     def get_level() -> float:
-        """Return the charge fraction in ``[0, 1]`` (``-1.0`` if unknown)."""
-        try:
-            level = float(native_module("Battery").call("get_level"))
-        except Exception:
-            return -1.0
+        """Return the charge fraction in ``[0, 1]``, or ``-1.0`` when the platform can't report it."""
+        level = float(native_module("Battery").call("get_level"))
         return level if 0.0 <= level <= 1.0 else -1.0
 
     @staticmethod
     def get_state() -> BatteryState:
         """Return ``"charging"`` / ``"full"`` / ``"unplugged"`` / ``"unknown"``."""
-        try:
-            state = str(native_module("Battery").call("get_state") or "unknown")
-        except Exception:
-            return "unknown"
+        state = str(native_module("Battery").call("get_state") or "unknown")
         return state if state in ("unknown", "unplugged", "charging", "full") else "unknown"
 
     @staticmethod

pythonnative/native_modules/biometrics.py

@@ -5,9 +5,9 @@ device's biometric hardware via ``LAContext`` (iOS) and
 ``BiometricPrompt`` (Android), both implemented in the native
 ``Biometrics`` module.
 
-``is_available`` is synchronous; ``authenticate`` is a coroutine that
-presents the system prompt and resolves to ``True`` on success or
-``False`` on failure / cancellation.
+``is_available`` is synchronous (a capability lookup); ``authenticate``
+is a coroutine that presents the system prompt and resolves to ``True``
+on success or ``False`` when the user fails or cancels the prompt.
 
 Example:
     ```python
@@ -25,20 +25,18 @@ from .registry import native_module
 
 
 class Biometrics:
-    """Biometric authentication interface."""
+    """Biometric authentication interface.
+
+    Raises:
+        NativeModuleError: If the native module fails.
+    """
 
     @staticmethod
     def is_available() -> bool:
-        """Return ``True`` when biometric auth can be attempted."""
-        try:
-            return bool(native_module("Biometrics").call("is_available"))
-        except Exception:
-            return False
+        """Return ``True`` when biometric auth can be attempted (enrolled hardware; ``False`` on desktop)."""
+        return bool(native_module("Biometrics").call("is_available"))
 
     @staticmethod
     async def authenticate(reason: str = "Authenticate") -> bool:
-        """Present the biometric prompt; resolve ``True`` on success."""
-        try:
-            return bool(await native_module("Biometrics").call_async("authenticate", reason=reason))
-        except Exception:
-            return False
+        """Present the biometric prompt; resolve ``True`` on success, ``False`` on failure or cancel."""
+        return bool(await native_module("Biometrics").call_async("authenticate", reason=reason))