pythonnative 0.14.0__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.14.0"
+__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/sdk/__init__.py

@@ -0,0 +1,132 @@
+"""Public extension surface for PythonNative.
+
+The ``pythonnative.sdk`` package collects the *stable* extension
+contract that third-party packages rely on: the
+[`ViewHandler`][pythonnative.sdk.ViewHandler] protocol, the
+[`Style`][pythonnative.sdk.Style] type, the
+[`@native_component`][pythonnative.sdk.native_component] registration
+decorator, and an
+[`element_factory`][pythonnative.sdk.element_factory] helper for
+producing strongly-typed element constructors.
+
+A custom native component is three things:
+
+1. A typed, frozen [`Props`][pythonnative.sdk.Props] dataclass listing
+   the public properties the component accepts.
+2. One or more
+   [`ViewHandler`][pythonnative.sdk.ViewHandler] subclasses (one per
+   target platform) implementing creation, update, and child management
+   for the underlying native widget.
+3. A registration call (the
+   [`@native_component`][pythonnative.sdk.native_component] decorator,
+   or
+   [`register_component`][pythonnative.sdk.register_component] for
+   imperative use) that binds the props type and handler into the
+   process-wide registry.
+
+Once registered, the component appears alongside the built-ins: the
+reconciler, layout engine, and Fast Refresh treat it identically.
+
+PyPI packages can ship handlers without users importing them
+explicitly by declaring an entry point in the
+``pythonnative.handlers`` group; PythonNative discovers and imports
+those modules the first time the registry is asked for a handler.
+
+Example:
+    ```python
+    from dataclasses import dataclass
+    import pythonnative as pn
+    from pythonnative.sdk import (
+        Props,
+        ViewHandler,
+        element_factory,
+        native_component,
+    )
+
+
+    @dataclass(frozen=True)
+    class BadgeProps(Props):
+        text: str = ""
+        color: str = "#FF3B30"
+        style: pn.StyleProp = None
+
+
+    @native_component("Badge", props=BadgeProps, platforms=("ios",))
+    class IOSBadgeHandler(ViewHandler):
+        def create(self, props):
+            ...
+
+        def update(self, view, changed):
+            ...
+
+
+    Badge = element_factory("Badge")
+
+    @pn.component
+    def App():
+        return pn.Column(
+            Badge(text="3", color="#0A84FF"),
+            pn.Text("Inbox"),
+        )
+    ```
+"""
+
+from ..element import Element
+from ..native_views.base import ViewHandler, parse_color_int, resolve_padding
+from ..style import (
+    Color,
+    Dimension,
+    EdgeInsets,
+    EdgeValue,
+    FlexDirection,
+    JustifyContent,
+    Overflow,
+    Position,
+    Style,
+    StyleProp,
+    TransformSpec,
+    style,
+)
+from ._components import (
+    ENTRY_POINT_GROUP,
+    Props,
+    element_factory,
+    get_props_type,
+    install_into_registry,
+    list_components,
+    native_component,
+    register_component,
+    unregister_component,
+)
+
+__all__ = [
+    # Core types
+    "Element",
+    "ViewHandler",
+    # Style types
+    "Color",
+    "Dimension",
+    "EdgeInsets",
+    "EdgeValue",
+    "FlexDirection",
+    "JustifyContent",
+    "Overflow",
+    "Position",
+    "Style",
+    "StyleProp",
+    "TransformSpec",
+    "style",
+    # SDK helpers (re-exported so users only import from one place)
+    "parse_color_int",
+    "resolve_padding",
+    # Native-component SDK
+    "ENTRY_POINT_GROUP",
+    "Props",
+    "element_factory",
+    "get_props_type",
+    "install_into_registry",
+    "list_components",
+    "native_component",
+    "register_component",
+    "unregister_component",
+]