pythonnative 0.13.1__py3-none-any.whl → 0.15.0__py3-none-any.whl

pythonnative/__init__.py

@@ -23,8 +23,18 @@ Key building blocks:
   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.
 - **Animations** use the ``Animated`` namespace, modeled on React
   Native's animation API.
+- **Custom native components** can be authored with the
+  ``pythonnative.sdk`` package: define a typed
+  [`Props`][pythonnative.sdk.Props] dataclass, implement a
+  [`ViewHandler`][pythonnative.native_views.base.ViewHandler] for each
+  platform, and register it via
+  [`@native_component`][pythonnative.sdk.native_component] (or expose
+  it from a PyPI package via the ``pythonnative.handlers`` entry-point
+  group).
 
 Example:
     ```python
@@ -34,15 +44,16 @@ Example:
     def App():
         count, set_count = pn.use_state(0)
         return pn.Column(
-            pn.Text(f"Count: {count}", style={"font_size": 24}),
+            pn.Text(f"Count: {count}", style=pn.style(font_size=24)),
             pn.Button("+", on_click=lambda: set_count(count + 1)),
-            style={"spacing": 12},
+            style=pn.style(spacing=12),
         )
     ```
 """
 
-__version__ = "0.13.1"
+__version__ = "0.15.0"
 
+from . import sdk
 from .alerts import Alert
 from .animated import Animated, AnimatedValue
 from .components import (
@@ -100,7 +111,39 @@ from .navigation import (
 )
 from .platform import Platform
 from .screen import create_screen
-from .style import StyleSheet, ThemeContext
+from .sdk import (
+    Props,
+    ViewHandler,
+    element_factory,
+    native_component,
+    register_component,
+)
+from .style import (
+    AlignItems,
+    AlignSelf,
+    AutoCapitalize,
+    Color,
+    Dimension,
+    EdgeInsets,
+    FlexDirection,
+    FontWeight,
+    JustifyContent,
+    KeyboardType,
+    Overflow,
+    Position,
+    ReturnKeyType,
+    ScaleType,
+    ShadowOffset,
+    Style,
+    StyleProp,
+    StyleSheet,
+    TextAlign,
+    TextDecoration,
+    ThemeContext,
+    TransformSpec,
+    resolve_style,
+    style,
+)
 
 __all__ = [
     # Components
@@ -154,9 +197,31 @@ __all__ = [
     "create_drawer_navigator",
     "create_stack_navigator",
     "create_tab_navigator",
-    # Styling
+    # Styling - typed primitives
+    "AlignItems",
+    "AlignSelf",
+    "AutoCapitalize",
+    "Color",
+    "Dimension",
+    "EdgeInsets",
+    "FlexDirection",
+    "FontWeight",
+    "JustifyContent",
+    "KeyboardType",
+    "Overflow",
+    "Position",
+    "ReturnKeyType",
+    "ScaleType",
+    "ShadowOffset",
+    "Style",
+    "StyleProp",
     "StyleSheet",
+    "TextAlign",
+    "TextDecoration",
     "ThemeContext",
+    "TransformSpec",
+    "resolve_style",
+    "style",
     # Animation
     "Animated",
     "AnimatedValue",
@@ -169,4 +234,11 @@ __all__ = [
     "Notifications",
     # Platform
     "Platform",
+    # Custom-component SDK
+    "Props",
+    "ViewHandler",
+    "element_factory",
+    "native_component",
+    "register_component",
+    "sdk",
 ]

pythonnative/animated.py

@@ -58,7 +58,7 @@ from typing import Any, Callable, Dict, List, Optional, Tuple
 
 from .element import Element
 from .hooks import use_effect, use_ref
-from .style import StyleValue, resolve_style
+from .style import StyleProp, resolve_style
 
 # Maximum frame rate at which the Python ticker drives animations.
 # We aim for 60 Hz but back off when no animation is active.
@@ -433,7 +433,7 @@ class _AnimationHandle:
 # ======================================================================
 
 
-def _resolve_style_with_values(style: StyleValue) -> Tuple[Dict[str, Any], Dict[str, AnimatedValue]]:
+def _resolve_style_with_values(style: StyleProp) -> Tuple[Dict[str, Any], Dict[str, AnimatedValue]]:
     """Return ``(plain_style, animated_bindings)``.
 
     AnimatedValue entries in the style are replaced with their

pythonnative/components.py

@@ -35,10 +35,18 @@ Example:
     ```
 """
 
-from typing import Any, Callable, Dict, List, Optional
+from typing import Any, Callable, Dict, List, Literal, Optional
 
 from .element import Element
-from .style import StyleValue, resolve_style
+from .style import (
+    AutoCapitalize,
+    Color,
+    KeyboardType,
+    ReturnKeyType,
+    ScaleType,
+    StyleProp,
+    resolve_style,
+)
 
 # ======================================================================
 # Leaf components
@@ -73,7 +81,7 @@ def _accessibility_props(
 def Text(
     text: str = "",
     *,
-    style: StyleValue = None,
+    style: StyleProp = None,
     accessibility_label: Optional[str] = None,
     accessibility_hint: Optional[str] = None,
     accessibility_role: Optional[str] = None,
@@ -118,7 +126,7 @@ def Button(
     *,
     on_click: Optional[Callable[[], None]] = None,
     enabled: bool = True,
-    style: StyleValue = None,
+    style: StyleProp = None,
     accessibility_label: Optional[str] = None,
     accessibility_hint: Optional[str] = None,
     accessible: Optional[bool] = None,
@@ -174,14 +182,14 @@ def TextInput(
     on_submit: Optional[Callable[[str], None]] = None,
     secure: bool = False,
     multiline: bool = False,
-    keyboard_type: Optional[str] = None,
-    auto_capitalize: Optional[str] = None,
+    keyboard_type: Optional[KeyboardType] = None,
+    auto_capitalize: Optional[AutoCapitalize] = None,
     auto_correct: Optional[bool] = None,
     auto_focus: bool = False,
-    return_key_type: Optional[str] = None,
+    return_key_type: Optional[ReturnKeyType] = None,
     max_length: Optional[int] = None,
-    placeholder_color: Optional[str] = None,
-    style: StyleValue = None,
+    placeholder_color: Optional[Color] = None,
+    style: StyleProp = None,
     accessibility_label: Optional[str] = None,
     accessibility_hint: Optional[str] = None,
     accessible: Optional[bool] = None,
@@ -257,9 +265,9 @@ def TextInput(
 def Image(
     source: str = "",
     *,
-    scale_type: Optional[str] = None,
-    tint_color: Optional[str] = None,
-    style: StyleValue = None,
+    scale_type: Optional[ScaleType] = None,
+    tint_color: Optional[Color] = None,
+    style: StyleProp = None,
     accessibility_label: Optional[str] = None,
     accessible: Optional[bool] = None,
     ref: Optional[Dict[str, Any]] = None,
@@ -307,7 +315,7 @@ def Switch(
     *,
     value: bool = False,
     on_change: Optional[Callable[[bool], None]] = None,
-    style: StyleValue = None,
+    style: StyleProp = None,
     key: Optional[str] = None,
 ) -> Element:
     """Display a toggle switch.
@@ -331,7 +339,7 @@ def Switch(
 def ProgressBar(
     *,
     value: float = 0.0,
-    style: StyleValue = None,
+    style: StyleProp = None,
     key: Optional[str] = None,
 ) -> Element:
     """Show determinate progress as a value between 0.0 and 1.0.
@@ -356,7 +364,7 @@ def ProgressBar(
 def ActivityIndicator(
     *,
     animating: bool = True,
-    style: StyleValue = None,
+    style: StyleProp = None,
     key: Optional[str] = None,
 ) -> Element:
     """Show an indeterminate loading spinner.
@@ -378,7 +386,7 @@ def ActivityIndicator(
 def WebView(
     *,
     url: str = "",
-    style: StyleValue = None,
+    style: StyleProp = None,
     key: Optional[str] = None,
 ) -> Element:
     """Embed web content from a URL.
@@ -440,7 +448,7 @@ def Slider(
     min_value: float = 0.0,
     max_value: float = 1.0,
     on_change: Optional[Callable[[float], None]] = None,
-    style: StyleValue = None,
+    style: StyleProp = None,
     key: Optional[str] = None,
 ) -> Element:
     """Continuous-value slider between `min_value` and `max_value`.
@@ -475,7 +483,7 @@ def Slider(
 
 def View(
     *children: Element,
-    style: StyleValue = None,
+    style: StyleProp = None,
     accessibility_label: Optional[str] = None,
     accessibility_hint: Optional[str] = None,
     accessibility_role: Optional[str] = None,
@@ -530,7 +538,7 @@ def View(
 
 def Column(
     *children: Element,
-    style: StyleValue = None,
+    style: StyleProp = None,
     ref: Optional[Dict[str, Any]] = None,
     key: Optional[str] = None,
 ) -> Element:
@@ -571,7 +579,7 @@ def Column(
 
 def Row(
     *children: Element,
-    style: StyleValue = None,
+    style: StyleProp = None,
     ref: Optional[Dict[str, Any]] = None,
     key: Optional[str] = None,
 ) -> Element:
@@ -614,7 +622,7 @@ def ScrollView(
     child: Optional[Element] = None,
     *,
     refresh_control: Optional[Dict[str, Any]] = None,
-    style: StyleValue = None,
+    style: StyleProp = None,
     ref: Optional[Dict[str, Any]] = None,
     key: Optional[str] = None,
 ) -> Element:
@@ -647,7 +655,7 @@ def ScrollView(
 
 def SafeAreaView(
     *children: Element,
-    style: StyleValue = None,
+    style: StyleProp = None,
     key: Optional[str] = None,
 ) -> Element:
     """Container that respects safe-area insets (notch, status bar, home indicator).
@@ -670,9 +678,9 @@ def Modal(
     visible: bool = False,
     on_dismiss: Optional[Callable[[], None]] = None,
     title: Optional[str] = None,
-    animation_type: str = "slide",
+    animation_type: Literal["slide", "fade", "none"] = "slide",
     transparent: bool = False,
-    style: StyleValue = None,
+    style: StyleProp = None,
     key: Optional[str] = None,
 ) -> Element:
     """Overlay modal dialog backed by a real native presentation.
@@ -720,7 +728,7 @@ def Pressable(
     on_press: Optional[Callable[[], None]] = None,
     on_long_press: Optional[Callable[[], None]] = None,
     pressed_opacity: float = 0.6,
-    style: StyleValue = None,
+    style: StyleProp = None,
     accessibility_label: Optional[str] = None,
     accessibility_hint: Optional[str] = None,
     accessible: Optional[bool] = None,
@@ -811,7 +819,7 @@ def FlatList(
     separator_height: float = 0,
     refresh_control: Optional[Dict[str, Any]] = None,
     on_item_press: Optional[Callable[[int], None]] = None,
-    style: StyleValue = None,
+    style: StyleProp = None,
     key: Optional[str] = None,
 ) -> Element:
     """Virtualized scrollable list that renders items from `data` lazily.
@@ -941,7 +949,7 @@ def SectionList(
     item_height: Optional[float] = None,
     section_header_height: float = 32.0,
     separator_height: float = 0,
-    style: StyleValue = None,
+    style: StyleProp = None,
     key: Optional[str] = None,
 ) -> Element:
     """Virtualized list that supports section headers.
@@ -1040,8 +1048,8 @@ def SectionList(
 
 def StatusBar(
     *,
-    style: Optional[str] = None,
-    background_color: Optional[str] = None,
+    style: Optional[Literal["light", "dark", "default"]] = None,
+    background_color: Optional[Color] = None,
     hidden: Optional[bool] = None,
     key: Optional[str] = None,
 ) -> Element:
@@ -1075,8 +1083,8 @@ def StatusBar(
 
 def KeyboardAvoidingView(
     *children: Element,
-    behavior: str = "padding",
-    style: StyleValue = None,
+    behavior: Literal["padding", "position"] = "padding",
+    style: StyleProp = None,
     key: Optional[str] = None,
 ) -> Element:
     """Wrap content that should shift up when the keyboard is shown.
@@ -1106,7 +1114,7 @@ def RefreshControl(
     *,
     refreshing: bool = False,
     on_refresh: Optional[Callable[[], None]] = None,
-    tint_color: Optional[str] = None,
+    tint_color: Optional[Color] = None,
 ) -> Dict[str, Any]:
     """Pull-to-refresh spec for [`ScrollView`][pythonnative.ScrollView] / [`FlatList`][pythonnative.FlatList].
 
@@ -1162,7 +1170,7 @@ def Picker(
     items: Optional[List[Dict[str, Any]]] = None,
     on_change: Optional[Callable[[Any], None]] = None,
     placeholder: str = "Select…",
-    style: StyleValue = None,
+    style: StyleProp = None,
     key: Optional[str] = None,
 ) -> Element:
     """A select / dropdown widget.

pythonnative/native_views/__init__.py

@@ -237,12 +237,50 @@ class NativeViewRegistry:
 _registry: Optional[NativeViewRegistry] = None
 
 
+def _active_platform_name() -> str:
+    """Return ``"android"`` or ``"ios"`` for the active runtime."""
+    from ..utils import IS_ANDROID
+
+    return "android" if IS_ANDROID else "ios"
+
+
+def _register_builtin_handlers(registry: NativeViewRegistry) -> None:
+    """Register every built-in handler for the active platform."""
+    from ..utils import IS_ANDROID
+
+    if IS_ANDROID:
+        from .android import register_handlers
+    else:
+        from .ios import register_handlers
+    register_handlers(registry)
+
+
+def _install_sdk_handlers(registry: NativeViewRegistry) -> None:
+    """Copy decorator-registered SDK handlers + entry-point plugins.
+
+    Imported lazily so unit tests that never touch the SDK don't pay the
+    entry-point discovery cost.
+    """
+    try:
+        from ..sdk._components import install_into_registry as _sdk_install
+    except Exception:
+        return
+    try:
+        _sdk_install(registry, _active_platform_name())
+    except Exception:
+        # A misbehaving plugin must not break PythonNative's startup.
+        pass
+
+
 def get_registry() -> NativeViewRegistry:
     """Return the process-wide registry, lazily registering handlers.
 
-    The first call instantiates the registry and registers either the
-    Android or iOS handlers based on `IS_ANDROID`. Subsequent calls
-    return the same instance.
+    The first call instantiates the registry, registers either the
+    Android or iOS handlers based on `IS_ANDROID`, then layers on every
+    decorator-registered SDK handler (and any handlers exposed by
+    third-party packages via the
+    [`pythonnative.handlers`][pythonnative.sdk.ENTRY_POINT_GROUP] entry
+    point group). Subsequent calls return the same instance.
 
     Returns:
         The active `NativeViewRegistry`.
@@ -251,30 +289,40 @@ def get_registry() -> NativeViewRegistry:
     if _registry is not None:
         return _registry
     _registry = NativeViewRegistry()
+    _register_builtin_handlers(_registry)
+    _install_sdk_handlers(_registry)
+    return _registry
 
-    from ..utils import IS_ANDROID
 
-    if IS_ANDROID:
-        from .android import register_handlers
+def refresh_registry() -> NativeViewRegistry:
+    """Re-run SDK handler installation against the existing registry.
 
-        register_handlers(_registry)
-    else:
-        from .ios import register_handlers
+    Call this after registering a new component at runtime if the
+    registry has already been instantiated. This is mostly useful in
+    REPL sessions and tests; the normal flow is "register, then call
+    [`get_registry`][pythonnative.native_views.get_registry]" and the
+    handlers come along automatically.
 
-        register_handlers(_registry)
-    return _registry
+    Returns:
+        The active `NativeViewRegistry`.
+    """
+    registry = get_registry()
+    _install_sdk_handlers(registry)
+    return registry
 
 
-def set_registry(registry: NativeViewRegistry) -> None:
+def set_registry(registry: Optional[NativeViewRegistry]) -> None:
     """Install a custom registry (primarily for testing).
 
     Replaces the lazy singleton so subsequent
     [`get_registry`][pythonnative.native_views.get_registry] calls
     return `registry`. Pass a mock to drive the reconciler from
-    unit tests without touching real native APIs.
+    unit tests without touching real native APIs. Pass ``None`` to
+    reset the singleton; the next ``get_registry`` call will then
+    rebuild it from scratch.
 
     Args:
-        registry: The replacement registry.
+        registry: The replacement registry, or ``None`` to clear.
     """
     global _registry
     _registry = registry

pythonnative/native_views/android.py

@@ -1116,10 +1116,41 @@ class TabBarHandler(AndroidViewHandler):
             menu.clear()
             for i, item in enumerate(items):
                 title = item.get("title", item.get("name", ""))
-                menu.add(0, i, i, str(title))
+                menu_item = menu.add(0, i, i, str(title))
+                res_id = self._resolve_icon(item.get("icon"))
+                if res_id:
+                    try:
+                        menu_item.setIcon(res_id)
+                    except Exception:
+                        pass
         except Exception:
             pass
 
+    def _resolve_icon(self, icon: Any) -> int:
+        """Resolve a tab icon spec to an `android.R.drawable.*` res id.
+
+        Accepts a bare string (treated as the drawable's field name on
+        ``android.R.drawable``) or a dict of the form
+        ``{"ios": "...", "android": "ic_menu_home"}``. Returns ``0``
+        when the icon can't be resolved, which the caller treats as
+        "no icon".
+        """
+        if icon is None:
+            return 0
+        name: Any = None
+        if isinstance(icon, str):
+            name = icon
+        elif isinstance(icon, dict):
+            name = icon.get("android")
+        if not name:
+            return 0
+        try:
+            RDrawable = jclass("android.R$drawable")
+            res_id = getattr(RDrawable, str(name), 0)
+            return int(res_id) if res_id else 0
+        except Exception:
+            return 0
+
     def _set_active(self, bnv: Any, active: Any, items: list) -> None:
         if active and items:
             for i, item in enumerate(items):

pythonnative/native_views/ios.py

@@ -2345,13 +2345,38 @@ class TabBarHandler(IOSViewHandler):
 
     def _set_bar_items(self, tab_bar: Any, items: list) -> None:
         UITabBarItem = ObjCClass("UITabBarItem")
+        UIImage = ObjCClass("UIImage")
         bar_items = []
         for i, item in enumerate(items):
             title = item.get("title", item.get("name", ""))
-            bar_item = UITabBarItem.alloc().initWithTitle_image_tag_(str(title), None, i)
+            image = self._resolve_icon(UIImage, item.get("icon"))
+            bar_item = UITabBarItem.alloc().initWithTitle_image_tag_(str(title), image, i)
             bar_items.append(bar_item)
         tab_bar.setItems_animated_(bar_items, False)
 
+    def _resolve_icon(self, UIImage: Any, icon: Any) -> Any:
+        """Resolve a tab icon spec to a UIImage, or return None.
+
+        Accepts a bare string (treated as an SF Symbol name) or a dict
+        of the form ``{"ios": "house.fill", "android": "..."}``. SF
+        Symbols are looked up via ``UIImage.systemImageNamed:``; names
+        that don't resolve produce a text-only tab.
+        """
+        if icon is None:
+            return None
+        name: Any = None
+        if isinstance(icon, str):
+            name = icon
+        elif isinstance(icon, dict):
+            name = icon.get("ios")
+        if not name:
+            return None
+        try:
+            image = UIImage.systemImageNamed_(str(name))
+            return image if image else None
+        except Exception:
+            return None
+
     def _set_active(self, tab_bar: Any, active: Any, items: list) -> None:
         if not active or not items:
             return

pythonnative/navigation.py

@@ -570,10 +570,14 @@ def _tab_navigator_impl(screens: Any = None, initial_route: Optional[str] = None
     if screen_def is None:
         screen_def = screen_map[screen_list[0].name]
 
-    tab_items: List[Dict[str, str]] = []
+    tab_items: List[Dict[str, Any]] = []
     for s in screen_list:
         if isinstance(s, _ScreenDef):
-            tab_items.append({"name": s.name, "title": s.options.get("title", s.name)})
+            item: Dict[str, Any] = {"name": s.name, "title": s.options.get("title", s.name)}
+            icon = s.options.get("tab_bar_icon")
+            if icon is not None:
+                item["icon"] = icon
+            tab_items.append(item)
 
     def on_tab_select(name: str) -> None:
         switch_tab(name)
@@ -639,8 +643,17 @@ def create_tab_navigator() -> Any:
                 name: Route name and default tab title.
                 component: A `@component` function rendered when this
                     tab is active.
-                options: Optional per-screen settings (e.g.,
-                    `{"title": "..."}`).
+                options: Optional per-screen settings. Recognized keys:
+
+                    - `title` (str): Tab label.
+                    - `tab_bar_icon` (str | dict): Native system icon
+                      identifier. A string is used on every platform; a
+                      dict like `{"ios": "house.fill", "android":
+                      "ic_menu_home"}` selects per platform. iOS values
+                      are resolved via SF Symbols
+                      (`UIImage.systemImageNamed_`); Android values are
+                      resolved against `android.R.drawable.<name>`.
+                      Names that don't resolve fall back to text-only.
 
             Returns:
                 A `_ScreenDef` consumed by `Navigator(...)`.