pythonnative 0.5.0__py3-none-any.whl → 0.7.0__py3-none-any.whl

pythonnative/hooks.py

@@ -0,0 +1,334 @@
+"""Hook primitives for function components.
+
+Provides React-like hooks for managing state, effects, memoisation,
+context, and navigation within function components decorated with
+:func:`component`.
+
+Usage::
+
+    import pythonnative as pn
+
+    @pn.component
+    def counter(initial=0):
+        count, set_count = pn.use_state(initial)
+        return pn.Column(
+            pn.Text(f"Count: {count}"),
+            pn.Button("+", on_click=lambda: set_count(count + 1)),
+        )
+"""
+
+import inspect
+import threading
+from typing import Any, Callable, Dict, List, Optional, Tuple, TypeVar
+
+from .element import Element
+
+T = TypeVar("T")
+
+_SENTINEL = object()
+
+_hook_context: threading.local = threading.local()
+
+
+# ======================================================================
+# Hook state container
+# ======================================================================
+
+
+class HookState:
+    """Stores all hook data for a single function component instance."""
+
+    __slots__ = ("states", "effects", "memos", "refs", "hook_index", "_trigger_render")
+
+    def __init__(self) -> None:
+        self.states: List[Any] = []
+        self.effects: List[Tuple[Any, Any]] = []
+        self.memos: List[Tuple[Any, Any]] = []
+        self.refs: List[dict] = []
+        self.hook_index: int = 0
+        self._trigger_render: Optional[Callable[[], None]] = None
+
+    def reset_index(self) -> None:
+        self.hook_index = 0
+
+    def run_pending_effects(self) -> None:
+        """Execute effects whose deps changed during the last render pass."""
+        for i, (deps, cleanup) in enumerate(self.effects):
+            if deps is _SENTINEL:
+                continue
+
+    def cleanup_all_effects(self) -> None:
+        """Run all outstanding cleanup functions (called on unmount)."""
+        for i, (deps, cleanup) in enumerate(self.effects):
+            if callable(cleanup):
+                try:
+                    cleanup()
+                except Exception:
+                    pass
+            self.effects[i] = (_SENTINEL, None)
+
+
+# ======================================================================
+# Thread-local context helpers
+# ======================================================================
+
+
+def _get_hook_state() -> Optional[HookState]:
+    return getattr(_hook_context, "current", None)
+
+
+def _set_hook_state(state: Optional[HookState]) -> None:
+    _hook_context.current = state
+
+
+def _deps_changed(prev: Any, current: Any) -> bool:
+    if prev is _SENTINEL:
+        return True
+    if prev is None or current is None:
+        return True
+    if len(prev) != len(current):
+        return True
+    return any(p is not c and p != c for p, c in zip(prev, current))
+
+
+# ======================================================================
+# Public hooks
+# ======================================================================
+
+
+def use_state(initial: Any = None) -> Tuple[Any, Callable]:
+    """Return ``(value, setter)`` for component-local state.
+
+    If *initial* is callable it is invoked once (lazy initialisation).
+    The setter accepts a value **or** a ``current -> new`` callable.
+    """
+    ctx = _get_hook_state()
+    if ctx is None:
+        raise RuntimeError("use_state must be called inside a @component function")
+
+    idx = ctx.hook_index
+    ctx.hook_index += 1
+
+    if idx >= len(ctx.states):
+        val = initial() if callable(initial) else initial
+        ctx.states.append(val)
+
+    current = ctx.states[idx]
+
+    def setter(new_value: Any) -> None:
+        if callable(new_value):
+            new_value = new_value(ctx.states[idx])
+        if ctx.states[idx] is not new_value and ctx.states[idx] != new_value:
+            ctx.states[idx] = new_value
+            if ctx._trigger_render:
+                ctx._trigger_render()
+
+    return current, setter
+
+
+def use_effect(effect: Callable, deps: Optional[list] = None) -> None:
+    """Schedule *effect* to run after render.
+
+    *deps* controls when the effect re-runs:
+
+    - ``None``  -> every render
+    - ``[]``    -> mount only
+    - ``[a, b]``-> when *a* or *b* change
+
+    *effect* may return a cleanup callable.
+    """
+    ctx = _get_hook_state()
+    if ctx is None:
+        raise RuntimeError("use_effect must be called inside a @component function")
+
+    idx = ctx.hook_index
+    ctx.hook_index += 1
+
+    if idx >= len(ctx.effects):
+        ctx.effects.append((_SENTINEL, None))
+
+    prev_deps, prev_cleanup = ctx.effects[idx]
+    if _deps_changed(prev_deps, deps):
+        if callable(prev_cleanup):
+            try:
+                prev_cleanup()
+            except Exception:
+                pass
+        cleanup = effect()
+        ctx.effects[idx] = (list(deps) if deps is not None else None, cleanup)
+    else:
+        ctx.effects[idx] = (prev_deps, prev_cleanup)
+
+
+def use_memo(factory: Callable[[], T], deps: list) -> T:
+    """Return a memoised value, recomputed only when *deps* change."""
+    ctx = _get_hook_state()
+    if ctx is None:
+        raise RuntimeError("use_memo must be called inside a @component function")
+
+    idx = ctx.hook_index
+    ctx.hook_index += 1
+
+    if idx >= len(ctx.memos):
+        value = factory()
+        ctx.memos.append((list(deps), value))
+        return value
+
+    prev_deps, prev_value = ctx.memos[idx]
+    if not _deps_changed(prev_deps, deps):
+        return prev_value
+
+    value = factory()
+    ctx.memos[idx] = (list(deps), value)
+    return value
+
+
+def use_callback(callback: Callable, deps: list) -> Callable:
+    """Return a stable reference to *callback*, updated only when *deps* change."""
+    return use_memo(lambda: callback, deps)
+
+
+def use_ref(initial: Any = None) -> dict:
+    """Return a mutable ref dict ``{"current": initial}`` that persists across renders."""
+    ctx = _get_hook_state()
+    if ctx is None:
+        raise RuntimeError("use_ref must be called inside a @component function")
+
+    idx = ctx.hook_index
+    ctx.hook_index += 1
+
+    if idx >= len(ctx.refs):
+        ref: dict = {"current": initial}
+        ctx.refs.append(ref)
+        return ref
+
+    return ctx.refs[idx]
+
+
+# ======================================================================
+# Context
+# ======================================================================
+
+
+class Context:
+    """A context object created by :func:`create_context`."""
+
+    def __init__(self, default: Any = None) -> None:
+        self.default = default
+        self._stack: List[Any] = []
+
+    def _current(self) -> Any:
+        return self._stack[-1] if self._stack else self.default
+
+
+def create_context(default: Any = None) -> Context:
+    """Create a new context with an optional default value."""
+    return Context(default)
+
+
+def use_context(context: Context) -> Any:
+    """Read the current value of *context* from the nearest ``Provider`` ancestor."""
+    ctx = _get_hook_state()
+    if ctx is None:
+        raise RuntimeError("use_context must be called inside a @component function")
+    return context._current()
+
+
+# ======================================================================
+# Provider element helper
+# ======================================================================
+
+
+def Provider(context: Context, value: Any, child: Element) -> Element:
+    """Create a context provider element.
+
+    All descendants of *child* will read *value* via ``use_context(context)``.
+    """
+    return Element("__Provider__", {"__context__": context, "__value__": value}, [child])
+
+
+# ======================================================================
+# Navigation
+# ======================================================================
+
+_NavigationContext: Context = create_context(None)
+
+
+class NavigationHandle:
+    """Object returned by :func:`use_navigation` providing push/pop/get_args.
+
+    Navigates by component reference rather than string path, e.g.::
+
+        nav = pn.use_navigation()
+        nav.push(DetailScreen, args={"id": 42})
+    """
+
+    def __init__(self, host: Any) -> None:
+        self._host = host
+
+    def push(self, page: Any, args: Optional[Dict[str, Any]] = None) -> None:
+        """Navigate forward to *page* (a ``@component`` function or class)."""
+        self._host._push(page, args)
+
+    def pop(self) -> None:
+        """Navigate back to the previous screen."""
+        self._host._pop()
+
+    def get_args(self) -> Dict[str, Any]:
+        """Return arguments passed from the previous screen."""
+        return self._host._get_nav_args()
+
+
+def use_navigation() -> NavigationHandle:
+    """Return a :class:`NavigationHandle` for the current screen.
+
+    Must be called inside a ``@component`` function rendered by PythonNative.
+    """
+    handle = use_context(_NavigationContext)
+    if handle is None:
+        raise RuntimeError(
+            "use_navigation() called outside a PythonNative page. "
+            "Ensure your component is rendered via create_page()."
+        )
+    return handle
+
+
+# ======================================================================
+# @component decorator
+# ======================================================================
+
+
+def component(func: Callable) -> Callable[..., Element]:
+    """Decorator that turns a Python function into a PythonNative component.
+
+    The decorated function can use hooks (``use_state``, ``use_effect``, etc.)
+    and returns an ``Element`` tree.  Each call site creates an independent
+    component instance with its own hook state.
+    """
+    sig = inspect.signature(func)
+    positional_params = [
+        name
+        for name, p in sig.parameters.items()
+        if p.kind in (inspect.Parameter.POSITIONAL_ONLY, inspect.Parameter.POSITIONAL_OR_KEYWORD)
+    ]
+    has_var_positional = any(p.kind == inspect.Parameter.VAR_POSITIONAL for p in sig.parameters.values())
+
+    def wrapper(*args: Any, **kwargs: Any) -> Element:
+        props: dict = dict(kwargs)
+
+        if args:
+            if has_var_positional:
+                props["children"] = list(args)
+            else:
+                for i, arg in enumerate(args):
+                    if i < len(positional_params):
+                        props[positional_params[i]] = arg
+
+        key = props.pop("key", None)
+        return Element(func, props, [], key=key)
+
+    wrapper.__wrapped__ = func  # noqa: B010
+    wrapper.__name__ = func.__name__
+    wrapper.__qualname__ = func.__qualname__
+    wrapper._pn_component = True  # noqa: B010
+    return wrapper

pythonnative/hot_reload.py

@@ -0,0 +1,143 @@
+"""Hot-reload support for PythonNative development.
+
+Host-side
+~~~~~~~~~
+:class:`FileWatcher` monitors the ``app/`` directory for changes and
+triggers a push-and-reload cycle via ``adb push`` (Android) or
+``simctl`` file copy (iOS).
+
+Device-side
+~~~~~~~~~~~
+:class:`ModuleReloader` reloads changed Python modules using
+``importlib.reload`` and triggers a page re-render.
+
+Usage (host-side, integrated into ``pn run --hot-reload``)::
+
+    watcher = FileWatcher("app/", on_change=push_files)
+    watcher.start()
+"""
+
+import importlib
+import os
+import sys
+import threading
+import time
+from typing import Any, Callable, Dict, List, Optional
+
+# ======================================================================
+# Host-side file watcher
+# ======================================================================
+
+
+class FileWatcher:
+    """Watch a directory tree for ``.py`` file changes.
+
+    Parameters
+    ----------
+    watch_dir:
+        Directory to watch.
+    on_change:
+        Called with a list of changed file paths when modifications are detected.
+    interval:
+        Polling interval in seconds.
+    """
+
+    def __init__(self, watch_dir: str, on_change: Callable[[List[str]], None], interval: float = 1.0) -> None:
+        self.watch_dir = watch_dir
+        self.on_change = on_change
+        self.interval = interval
+        self._running = False
+        self._thread: Optional[threading.Thread] = None
+        self._mtimes: Dict[str, float] = {}
+
+    def start(self) -> None:
+        """Begin watching in a background daemon thread."""
+        self._running = True
+        self._scan()
+        self._thread = threading.Thread(target=self._loop, daemon=True)
+        self._thread.start()
+
+    def stop(self) -> None:
+        """Stop the watcher."""
+        self._running = False
+        if self._thread is not None:
+            self._thread.join(timeout=self.interval * 2)
+            self._thread = None
+
+    def _scan(self) -> List[str]:
+        changed: List[str] = []
+        current_files: set = set()
+
+        for root, _dirs, files in os.walk(self.watch_dir):
+            for fname in files:
+                if not fname.endswith(".py"):
+                    continue
+                fpath = os.path.join(root, fname)
+                current_files.add(fpath)
+                try:
+                    mtime = os.path.getmtime(fpath)
+                except OSError:
+                    continue
+                if fpath in self._mtimes:
+                    if mtime > self._mtimes[fpath]:
+                        changed.append(fpath)
+                self._mtimes[fpath] = mtime
+
+        for old in list(self._mtimes):
+            if old not in current_files:
+                del self._mtimes[old]
+
+        return changed
+
+    def _loop(self) -> None:
+        while self._running:
+            time.sleep(self.interval)
+            changed = self._scan()
+            if changed:
+                try:
+                    self.on_change(changed)
+                except Exception:
+                    pass
+
+
+# ======================================================================
+# Device-side module reloader
+# ======================================================================
+
+
+class ModuleReloader:
+    """Reload changed Python modules on device and trigger re-render."""
+
+    @staticmethod
+    def reload_module(module_name: str) -> bool:
+        """Reload a single module by its dotted name.
+
+        Returns ``True`` if the module was found and reloaded successfully.
+        """
+        mod = sys.modules.get(module_name)
+        if mod is None:
+            return False
+        try:
+            importlib.reload(mod)
+            return True
+        except Exception:
+            return False
+
+    @staticmethod
+    def file_to_module(file_path: str, base_dir: str = "") -> Optional[str]:
+        """Convert a file path to a dotted module name relative to *base_dir*."""
+        rel = os.path.relpath(file_path, base_dir) if base_dir else file_path
+        if rel.endswith(".py"):
+            rel = rel[:-3]
+        parts = rel.replace(os.sep, ".").split(".")
+        if parts[-1] == "__init__":
+            parts = parts[:-1]
+        return ".".join(parts) if parts else None
+
+    @staticmethod
+    def reload_page(page_instance: Any) -> None:
+        """Force a page re-render after module reload."""
+        from .page import _re_render
+
+        if hasattr(page_instance, "_reconciler") and page_instance._reconciler is not None:
+            _re_render(page_instance)

pythonnative/native_modules/__init__.py

@@ -0,0 +1,19 @@
+"""Native API modules for device capabilities.
+
+Provides cross-platform Python interfaces to common device APIs:
+
+- :mod:`~.camera` — photo capture and gallery picking
+- :mod:`~.location` — GPS / location services
+- :mod:`~.file_system` — app-scoped file I/O
+- :mod:`~.notifications` — local push notifications
+
+Each module auto-detects the platform and calls the appropriate native
+APIs via Chaquopy (Android) or rubicon-objc (iOS).
+"""
+
+from .camera import Camera
+from .file_system import FileSystem
+from .location import Location
+from .notifications import Notifications
+
+__all__ = ["Camera", "FileSystem", "Location", "Notifications"]

pythonnative/native_modules/camera.py

@@ -0,0 +1,105 @@
+"""Cross-platform camera access.
+
+Provides methods for capturing photos and picking images from the gallery.
+Uses Android's ``Intent``/``MediaStore`` or iOS's ``UIImagePickerController``.
+"""
+
+from typing import Any, Callable, Optional
+
+from ..utils import IS_ANDROID
+
+
+class Camera:
+    """Camera and image picker interface.
+
+    All methods accept an ``on_result`` callback that receives the image
+    file path (or ``None`` on cancellation).
+    """
+
+    @staticmethod
+    def take_photo(on_result: Optional[Callable[[Optional[str]], None]] = None, **options: Any) -> None:
+        """Launch the device camera to capture a photo.
+
+        Parameters
+        ----------
+        on_result:
+            ``(path_or_none) -> None`` called with the saved image path,
+            or ``None`` if the user cancelled.
+        """
+        if IS_ANDROID:
+            Camera._android_take_photo(on_result, **options)
+        else:
+            Camera._ios_take_photo(on_result, **options)
+
+    @staticmethod
+    def pick_from_gallery(on_result: Optional[Callable[[Optional[str]], None]] = None, **options: Any) -> None:
+        """Open the system gallery picker.
+
+        Parameters
+        ----------
+        on_result:
+            ``(path_or_none) -> None`` called with the selected image path,
+            or ``None`` if the user cancelled.
+        """
+        if IS_ANDROID:
+            Camera._android_pick_gallery(on_result, **options)
+        else:
+            Camera._ios_pick_gallery(on_result, **options)
+
+    # -- Android implementations -----------------------------------------
+
+    @staticmethod
+    def _android_take_photo(on_result: Optional[Callable] = None, **options: Any) -> None:
+        try:
+            from java import jclass
+
+            Intent = jclass("android.content.Intent")
+            MediaStore = jclass("android.provider.MediaStore")
+            intent = Intent(MediaStore.ACTION_IMAGE_CAPTURE)
+            from ..utils import get_android_context
+
+            ctx = get_android_context()
+            ctx.startActivity(intent)
+        except Exception:
+            if on_result:
+                on_result(None)
+
+    @staticmethod
+    def _android_pick_gallery(on_result: Optional[Callable] = None, **options: Any) -> None:
+        try:
+            from java import jclass
+
+            Intent = jclass("android.content.Intent")
+            intent = Intent(Intent.ACTION_PICK)
+            intent.setType("image/*")
+            from ..utils import get_android_context
+
+            ctx = get_android_context()
+            ctx.startActivity(intent)
+        except Exception:
+            if on_result:
+                on_result(None)
+
+    # -- iOS implementations ---------------------------------------------
+
+    @staticmethod
+    def _ios_take_photo(on_result: Optional[Callable] = None, **options: Any) -> None:
+        try:
+            from rubicon.objc import ObjCClass
+
+            picker = ObjCClass("UIImagePickerController").alloc().init()
+            picker.setSourceType_(1)  # UIImagePickerControllerSourceTypeCamera
+        except Exception:
+            if on_result:
+                on_result(None)
+
+    @staticmethod
+    def _ios_pick_gallery(on_result: Optional[Callable] = None, **options: Any) -> None:
+        try:
+            from rubicon.objc import ObjCClass
+
+            picker = ObjCClass("UIImagePickerController").alloc().init()
+            picker.setSourceType_(0)  # PhotoLibrary
+        except Exception:
+            if on_result:
+                on_result(None)