pythonnative 0.22.0__py3-none-any.whl → 0.23.0__py3-none-any.whl

pythonnative/events.py

@@ -10,7 +10,7 @@ the bridge. This module replaces that with a single dispatch channel:
 - Handlers wire their platform listener **once** at view creation; the
   listener calls [`dispatch_event`][pythonnative.events.dispatch_event]
   with the view's tag and the event name.
-- Re-renders only mutate this Python-side registry — no native call is
+- Re-renders only mutate this Python-side registry; no native call is
   made when just a callback identity changes.
 
 The set of event names present on an element is forwarded to handlers
@@ -78,7 +78,7 @@ class EventRegistry:
 
         Returns:
             ``True`` when a callback existed and was invoked (even if
-            it raised — exceptions are swallowed so a buggy app
+            it raised: exceptions are swallowed so a buggy app
             callback can't crash the platform's UI thread), ``False``
             when nothing is registered.
         """
@@ -115,7 +115,7 @@ def dispatch_event(tag: int, name: str, *args: Any) -> bool:
 
     Args:
         tag: The view's reconciler-assigned tag.
-        name: Event name — the original prop name (``"on_click"``,
+        name: Event name, the original prop name (``"on_click"``,
             ``"on_change"``, …) or a gesture channel (``"gesture:0"``).
         *args: Positional arguments forwarded to the user callback,
             preserving each prop's documented signature.
@@ -144,8 +144,8 @@ def extract_events(props: Dict[str, Any]) -> Tuple[Dict[str, Any], Dict[str, Cal
     - ``gestures`` lists of gesture descriptors are serialized to plain
       dicts (handlers wire recognizers from them) while their callbacks
       are folded into per-gesture ``"gesture:<i>"`` routers.
-    - The resulting payload carries ``_pn_events`` — a frozenset of the
-      event names present — so handlers can wire listeners
+    - The resulting payload carries ``_pn_events`` (a frozenset of the
+      event names present), so handlers can wire listeners
       conditionally and the prop differ can detect listener
       addition/removal without comparing closures.
 

pythonnative/gestures.py

@@ -351,7 +351,7 @@ def serialize_gestures(
 # guarantees identical semantics on both backends.
 
 EmitFn = Callable[[int, Dict[str, Any]], None]
-"""``emit(gesture_index, payload)`` — the arbiter's output channel."""
+"""``emit(gesture_index, payload)``: the arbiter's output channel."""
 
 
 class _VelocityTracker:
@@ -400,7 +400,7 @@ class _Recognizer:
     def kind(self) -> str:
         return str(self.config.get("kind", ""))
 
-    # Event hooks — ``pointers`` maps pointer id -> (x, y).
+    # Event hooks: ``pointers`` maps pointer id -> (x, y).
     def down(self, pointers: Dict[int, Tuple[float, float]], t: float) -> None:
         pass
 
@@ -805,7 +805,7 @@ class GestureArbiter:
 
     One arbiter serves one view. The host backend feeds it normalized
     pointer events (positions in the view's coordinate space, times in
-    seconds — any monotonic clock) and provides an ``emit`` callback
+    seconds, any monotonic clock) and provides an ``emit`` callback
     that forwards ``(gesture_index, payload)`` pairs to
     [`dispatch_event`][pythonnative.events.dispatch_event].
 

pythonnative/hooks.py

@@ -613,7 +613,7 @@ def use_query(
     Args:
         fetcher: Zero-arg ``async`` callable that resolves to the
             current data.
-        deps: Dependency list — refetches whenever any entry changes.
+        deps: Dependency list. Refetches whenever any entry changes.
         initial: Optional starting value for ``data`` before the
             first fetch completes.
 
@@ -698,7 +698,7 @@ class MutationCall(Generic[T]):
     Returned by the second element of the
     [`use_mutation`][pythonnative.use_mutation] tuple. Awaiting the
     handle resolves to the mutator's return value (or re-raises its
-    exception); discarding the handle is safe — Python won't warn
+    exception); discarding the handle is safe. Python won't warn
     about an unawaited coroutine because this is a plain object.
 
     Example:
@@ -899,6 +899,47 @@ def use_keyboard_height() -> float:
     return platform_metrics.get_keyboard_height()
 
 
+def use_color_scheme() -> str:
+    """Return the effective color scheme and re-render when it changes.
+
+    Equivalent to React Native's ``useColorScheme``. The system value
+    is published by the screen host; an app-level override set through
+    [`appearance.set_color_scheme`][pythonnative.appearance.set_color_scheme]
+    takes precedence.
+
+    Returns:
+        ``"light"`` or ``"dark"``.
+
+    Raises:
+        RuntimeError: If called outside a `@component` function.
+
+    Example:
+        ```python
+        import pythonnative as pn
+
+        @pn.component
+        def Banner():
+            scheme = pn.use_color_scheme()
+            bg = "#000000" if scheme == "dark" else "#FFFFFF"
+            return pn.View(style=pn.style(background_color=bg))
+        ```
+    """
+    from . import appearance
+
+    ctx = _get_hook_state()
+    if ctx is None:
+        raise RuntimeError("use_color_scheme must be called inside a @component function")
+
+    _, set_tick = use_state(0)
+
+    def subscribe() -> Callable[[], None]:
+        return appearance.subscribe(lambda: set_tick(lambda n: n + 1))
+
+    use_effect(subscribe, [])
+
+    return appearance.get_color_scheme()
+
+
 # ======================================================================
 # Context
 # ======================================================================
@@ -1068,7 +1109,7 @@ class NavigationHandle:
     Wraps the host's push/pop primitives so screens can navigate
     without knowing the underlying native navigation stack. The
     typical user-facing surface is the declarative handle returned by
-    a [`Stack`][pythonnative.create_stack_navigator] — this class is
+    a [`Stack`][pythonnative.create_stack_navigator]; this class is
     the lower-level fallback used when no navigator is rendered (and
     as the bridge that declarative navigators delegate to when they
     need to push real native screens).

pythonnative/hot_reload.py

@@ -17,7 +17,7 @@ Two strategies share the device-side surface:
   the reconciler tree is walked and every component function whose
   module was reloaded is swapped in place. Hook state, navigation
   state, and even scroll positions survive because the underlying
-  ``VNode`` objects are reused — the next render simply calls the
+  ``VNode`` objects are reused; the next render simply calls the
   new function bodies through the old slots.
 - **Full remount**: when the in-place swap fails (e.g. the new
   module raised at import time, or a render exception bubbled out
@@ -197,8 +197,8 @@ class ModuleReloader:
 
     Designed to be invoked from device-side glue when a hot-reload
     push completes. All public methods are static; the class holds a
-    single piece of process-wide state — the manifest version that
-    has most recently been applied to ``sys.modules`` — so that
+    single piece of process-wide state (the manifest version that
+    has most recently been applied to ``sys.modules``) so that
     multiple screen hosts polling the same manifest do not each
     re-execute the user-app modules. The first host to see a new
     version pays the ``reload_modules`` cost; subsequent hosts on the
@@ -302,7 +302,7 @@ class ModuleReloader:
 
         Returns:
             The list of module names that are currently fresh in
-            ``sys.modules`` — either freshly reloaded by this call, or
+            ``sys.modules``, either freshly reloaded by this call, or
             already reloaded by an earlier host for the same version.
         """
         with ModuleReloader._reload_lock:

pythonnative/images.py

@@ -0,0 +1,196 @@
+"""Shared image pipeline: async fetch with memory and disk caching.
+
+Every platform's ``Image`` handler routes remote sources through this
+module. The pipeline downloads on a daemon thread (never blocking the
+UI), stores the raw bytes in a platform-appropriate disk cache keyed
+by URL hash, deduplicates concurrent requests for the same URL, and
+keeps a small in-memory LRU of recently fetched byte payloads so
+scrolling back to an image doesn't touch the filesystem again.
+
+Decoding stays platform-native (``BitmapFactory`` / ``UIImage`` /
+``PhotoImage``): callbacks receive a *local file path*, which each
+handler decodes with its platform's downsampling facilities.
+
+Callbacks are delivered on the platform main thread via
+[`call_on_main_thread`][pythonnative.runtime.call_on_main_thread], so
+handlers can touch native views directly.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import tempfile
+import threading
+import urllib.request
+from collections import OrderedDict
+from typing import Callable, Dict, List, Optional, Tuple
+
+_DOWNLOAD_TIMEOUT_S = 30.0
+_MEMORY_CACHE_MAX_BYTES = 16 * 1024 * 1024
+
+
+def _default_cache_dir() -> str:
+    """Resolve the on-disk cache directory for the current platform.
+
+    Android: the app's ``Context.getCacheDir()`` (purged by the OS
+    under storage pressure). iOS: ``~/Library/Caches`` (excluded from
+    backups). Desktop: a per-user directory under the system temp dir.
+    """
+    try:
+        from .utils import IS_ANDROID
+
+        if IS_ANDROID:
+            from .utils import get_android_context
+
+            base = str(get_android_context().getCacheDir().getAbsolutePath())
+            return os.path.join(base, "pn_images")
+    except Exception:
+        pass
+    home = os.path.expanduser("~")
+    caches = os.path.join(home, "Library", "Caches")
+    if os.path.isdir(caches):  # iOS / macOS
+        return os.path.join(caches, "pn_images")
+    return os.path.join(tempfile.gettempdir(), "pn_images")
+
+
+class _ByteLru:
+    """Tiny thread-safe LRU for raw image bytes."""
+
+    def __init__(self, max_bytes: int) -> None:
+        self._max = max_bytes
+        self._size = 0
+        self._items: "OrderedDict[str, bytes]" = OrderedDict()
+        self._lock = threading.Lock()
+
+    def get(self, key: str) -> Optional[bytes]:
+        with self._lock:
+            data = self._items.get(key)
+            if data is not None:
+                self._items.move_to_end(key)
+            return data
+
+    def put(self, key: str, data: bytes) -> None:
+        if len(data) > self._max:
+            return
+        with self._lock:
+            old = self._items.pop(key, None)
+            if old is not None:
+                self._size -= len(old)
+            self._items[key] = data
+            self._size += len(data)
+            while self._size > self._max and self._items:
+                _, evicted = self._items.popitem(last=False)
+                self._size -= len(evicted)
+
+    def clear(self) -> None:
+        with self._lock:
+            self._items.clear()
+            self._size = 0
+
+
+_memory_cache = _ByteLru(_MEMORY_CACHE_MAX_BYTES)
+_cache_dir: Optional[str] = None
+# URL -> callbacks waiting on an in-flight download.
+_in_flight: Dict[str, List[Tuple[Callable[[str], None], Callable[[str], None]]]] = {}
+_in_flight_lock = threading.Lock()
+
+
+def _get_cache_dir() -> str:
+    global _cache_dir
+    if _cache_dir is None:
+        _cache_dir = _default_cache_dir()
+        os.makedirs(_cache_dir, exist_ok=True)
+    return _cache_dir
+
+
+def _cache_path(url: str) -> str:
+    digest = hashlib.sha256(url.encode("utf-8")).hexdigest()
+    ext = os.path.splitext(url.split("?", 1)[0])[1]
+    if len(ext) > 8 or "/" in ext:
+        ext = ""
+    return os.path.join(_get_cache_dir(), digest + ext)
+
+
+def _dispatch_main(fn: Callable[[], None]) -> None:
+    try:
+        from .runtime import call_on_main_thread
+
+        call_on_main_thread(fn)
+    except Exception:
+        try:
+            fn()
+        except Exception:
+            pass
+
+
+def fetch(
+    url: str,
+    on_ready: Callable[[str], None],
+    on_error: Optional[Callable[[str], None]] = None,
+) -> None:
+    """Fetch ``url`` into the cache and deliver a local file path.
+
+    Cache hits (memory or disk) still deliver asynchronously-consistent
+    behavior but resolve without a network round trip. Concurrent
+    requests for the same URL share one download. Callbacks run on the
+    platform main thread.
+
+    Args:
+        url: The ``http(s)`` image URL.
+        on_ready: Called with the local file path once available.
+        on_error: Called with an error message if the download fails.
+    """
+    path = _cache_path(url)
+    if _memory_cache.get(url) is not None or os.path.isfile(path):
+        _dispatch_main(lambda: on_ready(path))
+        return
+
+    err = on_error or (lambda _msg: None)
+    with _in_flight_lock:
+        waiters = _in_flight.get(url)
+        if waiters is not None:
+            waiters.append((on_ready, err))
+            return
+        _in_flight[url] = [(on_ready, err)]
+
+    def _worker() -> None:
+        error_msg: Optional[str] = None
+        try:
+            req = urllib.request.Request(url, headers={"User-Agent": "PythonNative"})
+            with urllib.request.urlopen(req, timeout=_DOWNLOAD_TIMEOUT_S) as resp:
+                data = resp.read()
+            _memory_cache.put(url, data)
+            tmp = path + ".part"
+            with open(tmp, "wb") as fh:
+                fh.write(data)
+            os.replace(tmp, path)
+        except Exception as exc:
+            error_msg = str(exc)
+        with _in_flight_lock:
+            callbacks = _in_flight.pop(url, [])
+
+        def _notify(ready_cb: Callable[[str], None], error_cb: Callable[[str], None], msg: Optional[str]) -> None:
+            if msg is None:
+                _dispatch_main(lambda: ready_cb(path))
+            else:
+                _dispatch_main(lambda: error_cb(msg))
+
+        for ready_cb, error_cb in callbacks:
+            _notify(ready_cb, error_cb, error_msg)
+
+    threading.Thread(target=_worker, name=f"pn-image-{path[-12:]}", daemon=True).start()
+
+
+def clear_cache() -> None:
+    """Empty the memory cache and delete all cached image files."""
+    _memory_cache.clear()
+    try:
+        directory = _get_cache_dir()
+        for name in os.listdir(directory):
+            try:
+                os.remove(os.path.join(directory, name))
+            except OSError:
+                pass
+    except OSError:
+        pass

pythonnative/layout.py

@@ -9,7 +9,7 @@ The engine is invoked by the reconciler after each commit pass:
 
 1. The reconciler maintains a parallel
    [`LayoutNode`][pythonnative.layout.LayoutNode] tree (cached across
-   passes — clean subtrees keep their nodes, dirty ones are rebuilt).
+   passes: clean subtrees keep their nodes, dirty ones are rebuilt).
 2. [`calculate_layout`][pythonnative.layout.calculate_layout] is called
    with the viewport size; it recursively determines each node's
    ``(x, y, width, height)`` relative to its parent's coordinate space.
@@ -618,7 +618,7 @@ def _measure_node(
     resolved_direction = _resolve_direction(style, direction)
 
     # Incremental-layout memo: a clean node measured under identical
-    # inputs reuses its previous result without recursing — its whole
+    # inputs reuses its previous result without recursing; its whole
     # subtree keeps the sizes from the prior pass.
     memo = node._measure_memo
     if (
@@ -863,7 +863,7 @@ def _layout_flex_children(
     their line's cross size. The computed line structure is stored on
     ``parent._lines`` for the positioning pass.
 
-    Returns ``(used_main, used_cross)`` — the total content size used
+    Returns ``(used_main, used_cross)``, the total content size used
     by the in-flow children, including inter-child gaps but excluding
     the parent's own padding. The caller adds padding back in for the
     container's outer size.

pythonnative/mutations.py

@@ -22,8 +22,8 @@ Op ordering rules (the reconciler guarantees these):
 
 1. A `CreateOp` for a tag precedes any other op referencing that tag.
 2. `InsertOp` ops appear after both the parent and child exist.
-3. `DestroyOp` ops appear after the corresponding `RemoveOp` (if the
-   node was attached) and are emitted children-first.
+3. `DestroyOp` ops are emitted children-first; handlers detach the view
+   from its parent as part of destruction.
 4. `SetFrameOp` ops are only emitted for frames that actually changed
    since the last layout pass (frame diffing).
 """
@@ -35,7 +35,6 @@ __all__ = [
     "CreateOp",
     "UpdateOp",
     "InsertOp",
-    "RemoveOp",
     "DestroyOp",
     "SetFrameOp",
     "Mutation",
@@ -49,7 +48,7 @@ class CreateOp:
     Attributes:
         tag: Unique integer identity assigned by the reconciler.
         type_name: Element type name (e.g. ``"Text"``).
-        props: Initial *clean* props — callables have already been
+        props: Initial *clean* props; callables have already been
             routed to the [`EventRegistry`][pythonnative.events.EventRegistry]
             and replaced by the ``_pn_events`` name set.
     """
@@ -86,14 +85,6 @@ class InsertOp:
     index: int
 
 
-@dataclass(frozen=True)
-class RemoveOp:
-    """Detach the child view from the parent view (without destroying it)."""
-
-    parent_tag: int
-    child_tag: int
-
-
 @dataclass(frozen=True)
 class DestroyOp:
     """Release the native view registered under ``tag``.
@@ -126,5 +117,5 @@ class SetFrameOp:
         return (self.x, self.y, self.width, self.height)
 
 
-Mutation = Union[CreateOp, UpdateOp, InsertOp, RemoveOp, DestroyOp, SetFrameOp]
+Mutation = Union[CreateOp, UpdateOp, InsertOp, DestroyOp, SetFrameOp]
 """Union of every op type carried by a commit transaction."""

pythonnative/native_modules/camera.py

@@ -152,7 +152,7 @@ def _ios_launch_picker(on_result: Callable[[Optional[str]], None], source: str)
             _pending_delegates.pop(id(delegate), None)
             on_result(None)
 
-        # Reference SEL/objc_method so the lint pass keeps the import —
+        # Reference SEL/objc_method so the lint pass keeps the import;
         # they're needed for the delegate class above.
         _ = (SEL, objc_method)
     except Exception:

pythonnative/native_modules/haptics.py

@@ -2,11 +2,11 @@
 
 Two interfaces live here:
 
-- [`Haptics`][pythonnative.Haptics] — semantic, iOS-style feedback
+- [`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
+- [`Vibration`][pythonnative.Vibration]: a blunt "buzz for N
   milliseconds" interface for cases where you want an explicit
   duration.
 

pythonnative/native_modules/location.py

@@ -167,7 +167,7 @@ def _android_get(on_result: Callable[[Optional[Coords]], None]) -> None:
         Context = jclass("android.content.Context")
         lm = ctx.getSystemService(Context.LOCATION_SERVICE)
 
-        # Try the most recent known fix first — it's instant and avoids
+        # Try the most recent known fix first; it's instant and avoids
         # the GPS warm-up delay.
         try:
             for provider in ("gps", "network", "passive"):

pythonnative/native_modules/permissions.py

@@ -3,9 +3,9 @@
 [`Permissions`][pythonnative.Permissions] normalizes the very different
 iOS and Android permission models behind two calls:
 
-- ``check(permission)`` — synchronous, returns a status string without
+- ``check(permission)``: synchronous, returns a status string without
   prompting.
-- ``request(permission)`` — a coroutine that shows the system prompt
+- ``request(permission)``: a coroutine that shows the system prompt
   (if needed) and resolves to the resulting status.
 
 Statuses are ``"granted"``, ``"denied"``, ``"blocked"`` (denied with

pythonnative/native_modules/secure_store.py

@@ -1,7 +1,7 @@
 """Encrypted key/value storage for secrets (tokens, credentials).
 
 [`SecureStore`][pythonnative.SecureStore] persists small string values
-in the iOS Keychain and Android ``EncryptedSharedPreferences`` — the
+in the iOS Keychain and Android ``EncryptedSharedPreferences``, the
 right place for auth tokens and other secrets that
 [`AsyncStorage`][pythonnative.AsyncStorage] (plain, unencrypted) should
 never hold.

pythonnative/native_views/__init__.py

@@ -37,7 +37,7 @@ import threading
 import time
 from typing import Any, Dict, Optional, Sequence, Tuple
 
-from ..mutations import CreateOp, DestroyOp, InsertOp, Mutation, RemoveOp, SetFrameOp, UpdateOp
+from ..mutations import CreateOp, DestroyOp, InsertOp, Mutation, SetFrameOp, UpdateOp
 from .base import ViewHandler
 
 # ======================================================================
@@ -192,12 +192,6 @@ class NativeViewRegistry:
             if parent is not None and child is not None:
                 parent.handler.insert_child(parent.view, child.view, op.index)
             return
-        if isinstance(op, RemoveOp):
-            parent = self._records.get(op.parent_tag)
-            child = self._records.get(op.child_tag)
-            if parent is not None and child is not None:
-                parent.handler.remove_child(parent.view, child.view)
-            return
         if isinstance(op, DestroyOp):
             record = self._records.pop(op.tag, None)
             if record is not None: