pythonnative 0.14.0__tar.gz → 0.15.0__tar.gz

{pythonnative-0.14.0/src/pythonnative.egg-info → pythonnative-0.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythonnative
-Version: 0.14.0
+Version: 0.15.0
 Summary: Cross-platform native UI toolkit for Android and iOS
 Author: Owen Carey
 License: MIT License
@@ -96,10 +96,11 @@ PythonNative is a cross-platform toolkit for building native Android and iOS app
 
 - **Declarative UI:** Describe *what* your UI should look like with element functions (`Text`, `Button`, `Column`, `Row`, etc.). PythonNative creates and updates native views automatically.
 - **Hooks and function components:** Manage state with `use_state`, side effects with `use_effect`, and navigation with `use_navigation`, all through one consistent pattern.
-- **`style` prop:** Pass all visual and layout properties through a single `style` dict, composable via `StyleSheet`.
+- **Typed `style` prop:** Pass all visual and layout properties through a single `style` dict, fully described by the `pn.Style` `TypedDict` and the ergonomic `pn.style(...)` helper for IDE autocomplete and static checking. Compose reusable styles with `StyleSheet`.
 - **Cross-platform flexbox engine:** A pure-Python, Yoga-style layout engine computes frames once and applies them to native views, so `flex`, `padding`, `aspect_ratio`, and `position: "absolute"` produce the same geometry on Android and iOS.
 - **Virtual view tree + reconciler:** Element trees are diffed and patched with minimal native mutations, similar to React's reconciliation.
 - **Direct native bindings:** Python calls platform APIs directly through Chaquopy and rubicon-objc, with no JavaScript bridge.
+- **Custom-component SDK:** Wrap any platform widget as a first-class element with type-checked props via `pythonnative.sdk` (`Props`, `@native_component`, `element_factory`). Plugins distributed on PyPI auto-register through the `pythonnative.handlers` entry-point group.
 - **CLI scaffolding:** `pn init` creates a ready-to-run project; `pn run android` and `pn run ios` build and launch your app.
 - **Native-backed navigation:** Declarative `Stack`, `Tab`, and `Drawer` navigators inspired by React Navigation. The root stack drives the platform's native navigation controller (`UINavigationController` on iOS, AndroidX Navigation Component on Android), so transitions, back gestures, and the hardware back button match what users expect.
 - **Fast Refresh hot reload:** `pn run --hot-reload` watches `app/` and patches edits into the running app on save, preserving component state across most changes.
@@ -123,12 +124,12 @@ import pythonnative as pn
 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, bold=True)),
         pn.Button(
             "Tap me",
             on_click=lambda: set_count(count + 1),
         ),
-        style={"spacing": 12, "padding": 16},
+        style=pn.style(spacing=12, padding=16),
     )
 ```
 

{pythonnative-0.14.0 → pythonnative-0.15.0}/README.md

@@ -32,10 +32,11 @@ PythonNative is a cross-platform toolkit for building native Android and iOS app
 
 - **Declarative UI:** Describe *what* your UI should look like with element functions (`Text`, `Button`, `Column`, `Row`, etc.). PythonNative creates and updates native views automatically.
 - **Hooks and function components:** Manage state with `use_state`, side effects with `use_effect`, and navigation with `use_navigation`, all through one consistent pattern.
-- **`style` prop:** Pass all visual and layout properties through a single `style` dict, composable via `StyleSheet`.
+- **Typed `style` prop:** Pass all visual and layout properties through a single `style` dict, fully described by the `pn.Style` `TypedDict` and the ergonomic `pn.style(...)` helper for IDE autocomplete and static checking. Compose reusable styles with `StyleSheet`.
 - **Cross-platform flexbox engine:** A pure-Python, Yoga-style layout engine computes frames once and applies them to native views, so `flex`, `padding`, `aspect_ratio`, and `position: "absolute"` produce the same geometry on Android and iOS.
 - **Virtual view tree + reconciler:** Element trees are diffed and patched with minimal native mutations, similar to React's reconciliation.
 - **Direct native bindings:** Python calls platform APIs directly through Chaquopy and rubicon-objc, with no JavaScript bridge.
+- **Custom-component SDK:** Wrap any platform widget as a first-class element with type-checked props via `pythonnative.sdk` (`Props`, `@native_component`, `element_factory`). Plugins distributed on PyPI auto-register through the `pythonnative.handlers` entry-point group.
 - **CLI scaffolding:** `pn init` creates a ready-to-run project; `pn run android` and `pn run ios` build and launch your app.
 - **Native-backed navigation:** Declarative `Stack`, `Tab`, and `Drawer` navigators inspired by React Navigation. The root stack drives the platform's native navigation controller (`UINavigationController` on iOS, AndroidX Navigation Component on Android), so transitions, back gestures, and the hardware back button match what users expect.
 - **Fast Refresh hot reload:** `pn run --hot-reload` watches `app/` and patches edits into the running app on save, preserving component state across most changes.
@@ -59,12 +60,12 @@ import pythonnative as pn
 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, bold=True)),
         pn.Button(
             "Tap me",
             on_click=lambda: set_count(count + 1),
         ),
-        style={"spacing": 12, "padding": 16},
+        style=pn.style(spacing=12, padding=16),
     )
 ```
 

{pythonnative-0.14.0 → pythonnative-0.15.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pythonnative"
-version = "0.14.0"
+version = "0.15.0"
 description = "Cross-platform native UI toolkit for Android and iOS"
 authors = [
   { name = "Owen Carey" }
@@ -64,6 +64,7 @@ Documentation = "https://docs.pythonnative.com/"
 
 
 
+
 [tool.setuptools.packages.find]
 where = ["src"]
 

{pythonnative-0.14.0 → pythonnative-0.15.0}/src/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-0.14.0 → pythonnative-0.15.0}/src/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-0.14.0 → pythonnative-0.15.0}/src/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-0.14.0 → pythonnative-0.15.0}/src/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