pythonnative 0.47.0__tar.gz → 0.49.0__tar.gz

{pythonnative-0.47.0/src/pythonnative.egg-info → pythonnative-0.49.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythonnative
-Version: 0.47.0
+Version: 0.49.0
 Summary: Cross-platform native UI toolkit for Android and iOS
 Author: Owen Carey
 License: MIT License
@@ -81,7 +81,8 @@ PythonNative is a cross-platform toolkit for building native Android and iOS app
 - **Native widgets and layout:** Swift and Kotlin component managers own UIKit and Android widgets. The shared Yoga C++ engine computes layout beside the controls, using platform measurements for text and intrinsic sizes.
 - **Standard asyncio:** Components, effects, event handlers, and tasks run on a dedicated Python application thread. Native UI threads handle widgets, scrolling, and animation frames. Component-owned tasks are canceled on unmount.
 - **Incremental reconciliation:** State changes update affected component subtrees. Versioned bridge commits validate operations and acknowledge revisions; events and controlled text inputs carry identities that prevent stale updates.
-- **Native lists and navigation:** UIKit collection views and Android recycler views recycle cells for fixed or variable row sizes, grids, sections, and horizontal lists. Native navigation containers present logical screen roots at every nesting level while providers and component state remain in the shared Python tree; navigators take screen options, groups, themes, tab-bar styles, and a navigation ref usable outside components.
+- **Typed, Pythonic authoring:** Components return `pn.Node` and their signatures are their props, so a strict type checker verifies element trees and conditional children. Screens are components whose parameters are their route params (`nav.push(ItemScreen(id=42))`), navigators are module-level values with deep links derived from each screen's `path`, one `Theme` dataclass styles the app and its navigators, `StyleSheet` namespaces give styles typed names, and `pn.Store` holds app state with selector-based re-renders. `pn lint` checks the rules of hooks.
+- **Native lists and navigation:** UIKit collection views and Android recycler views recycle cells for fixed or variable row sizes, grids, sections, and horizontal lists. Native navigation containers present logical screen roots at every nesting level while providers and component state remain in the shared Python tree; navigators take screen options, groups, tab-bar styles, and a navigation ref usable outside components.
 - **Animation and gestures:** Serialized animation graphs support timing with named or bezier easing, springs, React Native's decay model, arithmetic, interpolation, and native scroll and gesture bindings. Swift and Kotlin recognize mobile gestures with Gesture Handler-style activation offsets and update supported animation bindings without Python work on every frame.
 - **Assets and graphics:** Drop images, fonts, and SVGs under `app/assets/` and reference them by path. Density variants, bundled fonts, a vector `Icon` set, `Svg` drawing, gradients, and blur render natively on both platforms and in the browser preview.
 - **Device APIs:** Python facades expose camera, location, notifications, storage, permissions, keyboard, dimensions and pixel ratio, device info, localization, accessibility settings, and other native services, with a Python fallback for headless tests. Test permissions and platform behavior on your deployment targets.
@@ -108,7 +109,7 @@ import pythonnative as pn
 
 
 @pn.component
-def App():
+def App() -> pn.Node:
     count, set_count = pn.use_state(0)
     return pn.Column(
         pn.Text(f"Count: {count}", style=pn.style(font_size=24, bold=True)),
@@ -116,7 +117,7 @@ def App():
             "Tap me",
             on_press=lambda: set_count(count + 1),
         ),
-        style=pn.style(spacing=12, padding=16),
+        style=pn.style(gap=12, padding=16),
     )
 ```
 

{pythonnative-0.47.0 → pythonnative-0.49.0}/README.md

@@ -35,7 +35,8 @@ PythonNative is a cross-platform toolkit for building native Android and iOS app
 - **Native widgets and layout:** Swift and Kotlin component managers own UIKit and Android widgets. The shared Yoga C++ engine computes layout beside the controls, using platform measurements for text and intrinsic sizes.
 - **Standard asyncio:** Components, effects, event handlers, and tasks run on a dedicated Python application thread. Native UI threads handle widgets, scrolling, and animation frames. Component-owned tasks are canceled on unmount.
 - **Incremental reconciliation:** State changes update affected component subtrees. Versioned bridge commits validate operations and acknowledge revisions; events and controlled text inputs carry identities that prevent stale updates.
-- **Native lists and navigation:** UIKit collection views and Android recycler views recycle cells for fixed or variable row sizes, grids, sections, and horizontal lists. Native navigation containers present logical screen roots at every nesting level while providers and component state remain in the shared Python tree; navigators take screen options, groups, themes, tab-bar styles, and a navigation ref usable outside components.
+- **Typed, Pythonic authoring:** Components return `pn.Node` and their signatures are their props, so a strict type checker verifies element trees and conditional children. Screens are components whose parameters are their route params (`nav.push(ItemScreen(id=42))`), navigators are module-level values with deep links derived from each screen's `path`, one `Theme` dataclass styles the app and its navigators, `StyleSheet` namespaces give styles typed names, and `pn.Store` holds app state with selector-based re-renders. `pn lint` checks the rules of hooks.
+- **Native lists and navigation:** UIKit collection views and Android recycler views recycle cells for fixed or variable row sizes, grids, sections, and horizontal lists. Native navigation containers present logical screen roots at every nesting level while providers and component state remain in the shared Python tree; navigators take screen options, groups, tab-bar styles, and a navigation ref usable outside components.
 - **Animation and gestures:** Serialized animation graphs support timing with named or bezier easing, springs, React Native's decay model, arithmetic, interpolation, and native scroll and gesture bindings. Swift and Kotlin recognize mobile gestures with Gesture Handler-style activation offsets and update supported animation bindings without Python work on every frame.
 - **Assets and graphics:** Drop images, fonts, and SVGs under `app/assets/` and reference them by path. Density variants, bundled fonts, a vector `Icon` set, `Svg` drawing, gradients, and blur render natively on both platforms and in the browser preview.
 - **Device APIs:** Python facades expose camera, location, notifications, storage, permissions, keyboard, dimensions and pixel ratio, device info, localization, accessibility settings, and other native services, with a Python fallback for headless tests. Test permissions and platform behavior on your deployment targets.
@@ -62,7 +63,7 @@ import pythonnative as pn
 
 
 @pn.component
-def App():
+def App() -> pn.Node:
     count, set_count = pn.use_state(0)
     return pn.Column(
         pn.Text(f"Count: {count}", style=pn.style(font_size=24, bold=True)),
@@ -70,7 +71,7 @@ def App():
             "Tap me",
             on_press=lambda: set_count(count + 1),
         ),
-        style=pn.style(spacing=12, padding=16),
+        style=pn.style(gap=12, padding=16),
     )
 ```
 

{pythonnative-0.47.0 → pythonnative-0.49.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pythonnative"
-version = "0.47.0"
+version = "0.49.0"
 description = "Cross-platform native UI toolkit for Android and iOS"
 authors = [
   { name = "Owen Carey" }
@@ -99,6 +99,7 @@ pythonnative = [
   "templates/**", "native/**", "sdk/templates/**",
   "devserver/static/**",
   "icons/_lucide.json", "icons/LICENSE-lucide.txt",
+  "sdk/_builtin_contracts.json",
 ]
 
 [tool.setuptools.exclude-package-data]

{pythonnative-0.47.0 → pythonnative-0.49.0}/src/pythonnative/__init__.py

@@ -18,16 +18,20 @@ Key building blocks:
   [`use_effect`][pythonnative.use_effect],
   [`use_reducer`][pythonnative.use_reducer], etc.) manage state, side
   effects, and context inside `@component` functions.
-- **Navigation** is built from
-  [`NavigationContainer`][pythonnative.NavigationContainer] plus one of
-  the [`create_stack_navigator`][pythonnative.create_stack_navigator],
-  [`create_tab_navigator`][pythonnative.create_tab_navigator], or
-  [`create_drawer_navigator`][pythonnative.create_drawer_navigator]
-  factories.
-- **Styling** uses a single ``style`` dict per element (or a list of
-  dicts), composable via [`StyleSheet`][pythonnative.StyleSheet].
-  PythonNative ships a fully-typed [`Style`][pythonnative.style.Style]
-  TypedDict so editors and ``mypy`` validate every key as you type.
+- **Navigation**: screens are components whose parameters are their
+  route params, listed in module-level
+  [`StackNavigator`][pythonnative.StackNavigator],
+  [`TabNavigator`][pythonnative.TabNavigator], or
+  [`DrawerNavigator`][pythonnative.DrawerNavigator] values and rendered
+  by [`NavigationContainer`][pythonnative.NavigationContainer].
+  ``nav.push(ItemScreen(id=42))`` is checked by the type checker.
+- **Styling** uses a ``style`` dict per element (or a list of dicts),
+  typed by the [`Style`][pythonnative.style.Style] ``TypedDict``.
+  [`StyleSheet`][pythonnative.StyleSheet] namespaces group named
+  styles, and one [`Theme`][pythonnative.Theme] styles the app and
+  its navigators.
+- **State** lives in hooks for a component and in a typed
+  [`Store`][pythonnative.Store] for the app.
 - **Animations** use the ``Animated`` namespace. Serialized graphs
   connect values, arithmetic, interpolation, and style bindings.
   Native timing, spring, decay, scroll, and gesture drivers update
@@ -52,21 +56,23 @@ Example:
     import pythonnative as pn
 
     @pn.component
-    def App():
+    def App() -> pn.Node:
         count, set_count = pn.use_state(0)
         return pn.Column(
             pn.Text(f"Count: {count}", style=pn.style(font_size=24)),
             pn.Button("+", on_press=lambda: set_count(count + 1)),
-            style=pn.style(spacing=12),
+            style=pn.style(gap=12),
         )
     ```
 """
 
-__version__ = "0.47.0"
+__version__ = "0.49.0"
 
-from . import appearance, diagnostics, gestures, icons, runtime, sdk, svg
+import importlib
+from typing import TYPE_CHECKING, Any
+
+from . import appearance, diagnostics, runtime, sdk, svg
 from .alerts import Alert
-from .animated import ANIMATABLE_PROPS, Animated, AnimatedValue, AnimationResult, Easing, EasingSpec, use_animated_value
 from .assets import Asset, asset
 from .component import Component, component, memo
 from .components import (
@@ -117,9 +123,9 @@ from .components import (
     WebNavigationEvent,
     WebView,
 )
+from .components.props import AccessibilityProps, ViewProps
 from .diagnostics import HookOrderError
-from .element import Element
-from .gestures import GestureSpec, SwipeDirection
+from .element import Element, Node
 from .handles import ScrollOffset, ScrollViewHandle, TextInputHandle, ViewHandle, WebViewHandle
 from .hooks import (
     ColorScheme,
@@ -152,7 +158,6 @@ from .hooks import (
     use_window_dimensions,
 )
 from .hosts import create_screen
-from .icons import Icon, IconName
 from .mutations import UNSET, UnsetType
 from .native_modules import (
     AccessibilityEvent,
@@ -189,40 +194,15 @@ from .native_modules import (
     use_reduce_motion,
     use_screen_reader_enabled,
 )
-from .navigation import (
-    DARK_NAVIGATION_THEME,
-    DEFAULT_NAVIGATION_THEME,
-    LinkingConfig,
-    Navigation,
-    NavigationColors,
-    NavigationContainer,
-    NavigationRef,
-    NavigationState,
-    NavigationTheme,
-    Route,
-    ScreenGroup,
-    ScreenOptions,
-    TabBarStyle,
-    create_drawer_navigator,
-    create_navigation_ref,
-    create_stack_navigator,
-    create_tab_navigator,
-    use_focus_effect,
-    use_is_focused,
-    use_navigation,
-    use_navigation_theme,
-    use_route,
-)
-from .net import HTTPError, Response, fetch
 from .platform import Platform, get_platform
 from .platform_metrics import WindowDimensions
 from .runtime import run_async, run_blocking
 from .scheduler import batch_updates
 from .sdk import Props, define_component, element_factory
 from .storage import AsyncStorage, use_persisted_state
+from .store import Store, use_store
 from .style import (
-    DEFAULT_DARK_THEME,
-    DEFAULT_LIGHT_THEME,
+    ABSOLUTE_FILL,
     AccessibilityAction,
     AccessibilityState,
     AccessibilityValue,
@@ -254,15 +234,23 @@ from .style import (
     TextAlign,
     TextDecoration,
     TextTransform,
-    Theme,
-    ThemeContext,
     TransformSpec,
-    default_theme,
     resolve_style,
     style,
-    use_theme,
 )
 from .suspense import Resource, lazy, start_resource
+from .theme import (
+    DARK_THEME,
+    LIGHT_THEME,
+    Colors,
+    Radii,
+    Spacing,
+    Theme,
+    ThemeProvider,
+    Typography,
+    use_styles,
+    use_theme,
+)
 
 __all__ = [
     "UNSET",
@@ -314,6 +302,9 @@ __all__ = [
     "TouchableOpacity",
     "View",
     "WebView",
+    # Shared props
+    "AccessibilityProps",
+    "ViewProps",
     # Typed events
     "ContentSizeEvent",
     "KeyPressEvent",
@@ -334,6 +325,7 @@ __all__ = [
     # Core
     "Component",
     "Element",
+    "Node",
     "component",
     "create_screen",
     "memo",
@@ -373,28 +365,24 @@ __all__ = [
     "lazy",
     "start_resource",
     # Navigation
-    "DARK_NAVIGATION_THEME",
-    "DEFAULT_NAVIGATION_THEME",
-    "LinkingConfig",
+    "DrawerNavigator",
+    "Group",
     "Navigation",
-    "NavigationColors",
     "NavigationContainer",
     "NavigationRef",
     "NavigationState",
-    "NavigationTheme",
+    "Navigator",
     "Route",
-    "ScreenGroup",
+    "Screen",
     "ScreenOptions",
+    "StackNavigator",
     "TabBarStyle",
-    "create_navigation_ref",
-    "use_navigation_theme",
-    "create_drawer_navigator",
-    "create_stack_navigator",
-    "create_tab_navigator",
+    "TabNavigator",
     "use_focus_effect",
     "use_is_focused",
     "use_navigation",
     "use_route",
+    "use_screen_options",
     # Styling - typed primitives
     "AccessibilityAction",
     "AccessibilityState",
@@ -405,8 +393,6 @@ __all__ = [
     "AutoCapitalize",
     "BorderStyle",
     "Color",
-    "DEFAULT_DARK_THEME",
-    "DEFAULT_LIGHT_THEME",
     "Dimension",
     "Display",
     "DynamicColor",
@@ -430,9 +416,16 @@ __all__ = [
     "TextDecoration",
     "TextTransform",
     "Theme",
-    "ThemeContext",
+    "ThemeProvider",
+    "Colors",
+    "Typography",
+    "Spacing",
+    "Radii",
+    "LIGHT_THEME",
+    "DARK_THEME",
+    "ABSOLUTE_FILL",
+    "use_styles",
     "TransformSpec",
-    "default_theme",
     "resolve_style",
     "style",
     "use_theme",
@@ -487,6 +480,9 @@ __all__ = [
     "Vibration",
     "use_app_state",
     "use_net_info",
+    # Stores
+    "Store",
+    "use_store",
     # Networking + persistence
     "AsyncStorage",
     "fetch",
@@ -510,3 +506,92 @@ __all__ = [
 ]
 
 from .list_data import ListData, Section, ViewableItem
+
+# Subsystems an app may never touch load on first use (PEP 562), so
+# ``import pythonnative`` stays fast on a phone. Names, ``__all__``, and
+# documentation are unchanged, and type checkers see ordinary imports.
+_LAZY_GROUPS: dict[str, tuple[str, ...]] = {
+    "animated": (
+        "ANIMATABLE_PROPS",
+        "Animated",
+        "AnimatedValue",
+        "AnimationResult",
+        "Easing",
+        "EasingSpec",
+        "use_animated_value",
+    ),
+    "gestures": ("GestureSpec", "SwipeDirection"),
+    "icons": ("Icon", "IconName"),
+    "navigation": (
+        "DrawerNavigator",
+        "Group",
+        "Navigation",
+        "NavigationContainer",
+        "NavigationRef",
+        "NavigationState",
+        "Navigator",
+        "Route",
+        "Screen",
+        "ScreenOptions",
+        "StackNavigator",
+        "TabBarStyle",
+        "TabNavigator",
+        "use_focus_effect",
+        "use_is_focused",
+        "use_navigation",
+        "use_route",
+        "use_screen_options",
+    ),
+    "net": ("HTTPError", "Response", "fetch"),
+}
+_LAZY = {name: module for module, names in _LAZY_GROUPS.items() for name in names}
+_LAZY_MODULES = frozenset({"gestures", "icons"})
+
+if TYPE_CHECKING:
+    from . import gestures, icons
+    from .animated import (
+        ANIMATABLE_PROPS,
+        Animated,
+        AnimatedValue,
+        AnimationResult,
+        Easing,
+        EasingSpec,
+        use_animated_value,
+    )
+    from .gestures import GestureSpec, SwipeDirection
+    from .icons import Icon, IconName
+    from .navigation import (
+        DrawerNavigator,
+        Group,
+        Navigation,
+        NavigationContainer,
+        NavigationRef,
+        NavigationState,
+        Navigator,
+        Route,
+        Screen,
+        ScreenOptions,
+        StackNavigator,
+        TabBarStyle,
+        TabNavigator,
+        use_focus_effect,
+        use_is_focused,
+        use_navigation,
+        use_route,
+        use_screen_options,
+    )
+    from .net import HTTPError, Response, fetch
+
+
+def __getattr__(name: str) -> Any:
+    module = _LAZY.get(name)
+    if module is None and name not in _LAZY_MODULES:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    imported = importlib.import_module(f".{module or name}", __name__)
+    value = imported if module is None else getattr(imported, name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted(set(globals()) | _LAZY.keys() | _LAZY_MODULES)

{pythonnative-0.47.0 → pythonnative-0.49.0}/src/pythonnative/animated.py

@@ -2180,7 +2180,10 @@ def use_animated_value(initial: float = 0.0) -> AnimatedValue:
     """
     from .hooks import use_memo
 
-    return use_memo(lambda: AnimatedValue(initial), [])
+    return use_memo(
+        lambda: AnimatedValue(initial),
+        [],  # pn: ignore[PN103] the initial value is read once, like use_state
+    )
 
 
 __all__ = [

{pythonnative-0.47.0 → pythonnative-0.49.0}/src/pythonnative/appearance.py

@@ -120,5 +120,8 @@ def get_system_color_scheme() -> str:
 def reset_color_scheme() -> None:
     """Reset to system ``"light"`` with no override. Intended for tests."""
     global _system_scheme, _override_scheme
+    changed = get_color_scheme() != "light"
     _system_scheme = "light"
     _override_scheme = None
+    if changed:
+        _notify_subscribers()

{pythonnative-0.47.0 → pythonnative-0.49.0}/src/pythonnative/assets/__init__.py

@@ -44,6 +44,7 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any, Dict, Iterable, List, Mapping, Optional, Sequence, Tuple, Union
 
+from ..utils import overlay_root
 from .fonts import FontFace, FontParseError, read_font_face, weight_from_name
 
 __all__ = [
@@ -437,8 +438,6 @@ def assets_roots() -> List[Path]:
     back to the native ``Assets`` module.
     """
     roots: List[Path] = []
-    from ..hot_reload import overlay_root
-
     overlay = overlay_root()
     if overlay:
         roots.append(Path(overlay) / "app" / ASSETS_DIR)
@@ -560,7 +559,6 @@ def configure_native(paths: Optional[Iterable[str]] = None) -> bool:
     if paths is not None and not any(_is_asset_path(path) for path in paths):
         return False
     from ..bridge import has_transport
-    from ..hot_reload import overlay_root
 
     overlay = overlay_root()
     if not overlay or not has_transport():

{pythonnative-0.47.0 → pythonnative-0.49.0}/src/pythonnative/bootstrap.py

@@ -1,16 +1,17 @@
 """Entry point the native app templates run right after Python starts.
 
-Both templates execute one line of Python once the interpreter is up:
+Both templates call [`start`][pythonnative.bootstrap.start] once the
+interpreter is up, on a background thread at launch:
 
 ```python
-import pythonnative.bootstrap; pythonnative.bootstrap.start()
+pythonnative.bootstrap.start(dev, True, "app.main")
 ```
 
-[`start`][pythonnative.bootstrap.start] connects the two halves of the
-bridge (installing the native -> Python callback on iOS), verifies the
-protocol version, routes ``print()`` to the console on iOS, warms the
-asyncio runtime, and, in debug builds, starts the dev client that syncs
-sources from ``pn start``. From then on the native runtime drives
+It connects the two halves of the bridge (installing the native -> Python
+callback on iOS), verifies the protocol version, routes ``print()`` to the
+console on iOS, warms the asyncio runtime, in debug builds starts the dev
+client that syncs sources from ``pn start``, and imports the entry module,
+so the first screen only has to render. From then on the native runtime drives
 everything through ``callback("host", ...)``; see ``docs/concepts/bridge.md``.
 """
 
@@ -19,14 +20,14 @@ from __future__ import annotations
 import os
 import sys
 import traceback
-from typing import Any, Dict
+from typing import Any, Dict, Optional
 
 __all__ = ["start", "status"]
 
 _started: Dict[str, Any] = {}
 
 
-def start(dev: bool = False, strict: bool = False) -> Dict[str, Any]:
+def start(dev: bool = False, strict: bool = False, entry: Optional[str] = None) -> Dict[str, Any]:
     """Connect the bridge and prepare the runtime.
 
     Args:
@@ -35,6 +36,9 @@ def start(dev: bool = False, strict: bool = False) -> Dict[str, Any]:
         strict: Re-raise the failure after recording it. The templates
             pass ``True`` so a broken bridge surfaces as a bootstrap
             error screen with the full traceback.
+        entry: The app's entry module, imported last so a broken app
+            fails here with its traceback, and so the first screen
+            doesn't pay for the import.
 
     Returns:
         A status dict (``{"protocol": 2, "platform": "ios"}``) that the
@@ -79,15 +83,20 @@ def start(dev: bool = False, strict: bool = False) -> Dict[str, Any]:
         if dev_mode:
             # Debug builds are dev clients: connect to `pn start` when
             # the build (or a remembered connection) names a server.
+            # Release bundles omit this module; they never pass dev=True.
             from . import devclient
 
             client = devclient.start_if_configured()
-            status_["dev_server"] = client.url if client is not None else None
+            status_["dev_server"] = client.server_label if client is not None else None
             # An overlay from the last session may already hold assets the
             # bundle doesn't; point the native resolver at it right away.
             from .assets import configure_native
 
             configure_native()
+        if entry:
+            import importlib
+
+            importlib.import_module(entry)
     except Exception as exc:
         status_["error"] = f"{type(exc).__name__}: {exc}"
         print(f"[pn.bootstrap] start failed: {exc!r}", file=sys.stderr)