pythonnative 0.33.0__tar.gz → 0.35.0__tar.gz

{pythonnative-0.33.0/src/pythonnative.egg-info → pythonnative-0.35.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythonnative
-Version: 0.33.0
+Version: 0.35.0
 Summary: Cross-platform native UI toolkit for Android and iOS
 Author: Owen Carey
 License: MIT License
@@ -43,6 +43,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: requests>=2.31.0
 Requires-Dist: tomli>=2.0; python_version < "3.11"
+Requires-Dist: typing_extensions>=4.4; python_version < "3.11"
 Provides-Extra: ios
 Requires-Dist: rubicon-objc<0.5.0,>=0.4.6; extra == "ios"
 Provides-Extra: build

{pythonnative-0.33.0 → pythonnative-0.35.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pythonnative"
-version = "0.33.0"
+version = "0.35.0"
 description = "Cross-platform native UI toolkit for Android and iOS"
 authors = [
   { name = "Owen Carey" }
@@ -26,6 +26,7 @@ classifiers = [
 dependencies = [
   "requests>=2.31.0",
   "tomli>=2.0; python_version < '3.11'",
+  "typing_extensions>=4.4; python_version < '3.11'",
 ]
 
 [project.optional-dependencies]

{pythonnative-0.33.0 → pythonnative-0.35.0}/src/pythonnative/__init__.py

@@ -60,11 +60,12 @@ Example:
     ```
 """
 
-__version__ = "0.33.0"
+__version__ = "0.35.0"
 
 from . import appearance, diagnostics, gestures, images, runtime, sdk
 from .alerts import Alert
 from .animated import Animated, AnimatedValue, use_animated_value
+from .component import Component, component, memo
 from .components import (
     ActivityIndicator,
     Button,
@@ -103,15 +104,12 @@ from .components import (
 from .diagnostics import HookOrderError
 from .element import Element
 from .hooks import (
+    Context,
     MutationCall,
     MutationState,
-    Provider,
     QueryResult,
     Ref,
-    batch_updates,
-    component,
     create_context,
-    memo,
     use_back_handler,
     use_callback,
     use_color_scheme,
@@ -123,16 +121,17 @@ from .hooks import (
     use_layout_effect,
     use_memo,
     use_mutation,
-    use_navigation,
     use_query,
     use_reducer,
     use_ref,
     use_resource,
     use_safe_area_insets,
     use_state,
+    use_subscription,
     use_transition,
     use_window_dimensions,
 )
+from .hosts import create_screen
 from .native_modules import (
     AppState,
     Battery,
@@ -153,18 +152,24 @@ from .native_modules import (
     use_net_info,
 )
 from .navigation import (
+    LinkingConfig,
+    Navigation,
     NavigationContainer,
+    NavigationState,
+    Route,
     ScreenOptions,
     create_drawer_navigator,
     create_stack_navigator,
     create_tab_navigator,
     use_focus_effect,
+    use_is_focused,
+    use_navigation,
     use_route,
 )
 from .net import HTTPError, Response, fetch
-from .platform import Platform
+from .platform import Platform, get_platform
 from .runtime import run_async, run_blocking
-from .screen import create_screen
+from .scheduler import batch_updates
 from .sdk import (
     Props,
     ViewHandler,
@@ -245,51 +250,58 @@ __all__ = [
     "View",
     "WebView",
     # Core
+    "Component",
     "Element",
-    "create_screen",
-    # Hooks
-    "batch_updates",
     "component",
-    "create_context",
+    "create_screen",
     "memo",
+    # Hooks
+    "Context",
     "MutationCall",
     "MutationState",
     "QueryResult",
     "Ref",
+    "batch_updates",
+    "create_context",
     "use_back_handler",
     "use_callback",
     "use_color_scheme",
     "use_context",
     "use_deferred_value",
     "use_effect",
-    "use_focus_effect",
     "use_imperative_handle",
     "use_keyboard_height",
     "use_layout_effect",
     "use_memo",
     "use_mutation",
-    "use_navigation",
     "use_persisted_state",
     "use_query",
     "use_reducer",
     "use_ref",
     "use_resource",
-    "use_route",
     "use_safe_area_insets",
     "use_state",
+    "use_subscription",
     "use_transition",
     "use_window_dimensions",
-    "Provider",
     # Suspense and async rendering
     "Resource",
     "lazy",
     "start_resource",
     # Navigation
+    "LinkingConfig",
+    "Navigation",
     "NavigationContainer",
+    "NavigationState",
+    "Route",
     "ScreenOptions",
     "create_drawer_navigator",
     "create_stack_navigator",
     "create_tab_navigator",
+    "use_focus_effect",
+    "use_is_focused",
+    "use_navigation",
+    "use_route",
     # Styling - typed primitives
     "AccessibilityState",
     "AlignContent",
@@ -367,6 +379,7 @@ __all__ = [
     "diagnostics",
     # Platform
     "Platform",
+    "get_platform",
     # Custom-component SDK
     "Props",
     "ViewHandler",

{pythonnative-0.33.0 → pythonnative-0.35.0}/src/pythonnative/animated.py

@@ -1356,20 +1356,14 @@ def _make_animated_factory(
     accept_children: bool,
 ) -> Callable[..., Element]:
     """Build an animated wrapper for ``element_type``."""
-    from .hooks import component  # local import to avoid cycle
+    from .component import Component
 
-    @component
-    def _animated(*args: Any, **kwargs: Any) -> Element:
+    def _animated(*children: Any, **kwargs: Any) -> Element:
         from .components import Image as _Image
         from .components import Text as _Text
         from .components import View as _View
 
-        # ``@component`` packs positional children into the ``children``
-        # prop (this function declares ``*args``), and the reconciler
-        # re-invokes it with keyword props only, so at render time the
-        # payload arrives in ``kwargs``, never in ``args``.
-        children = list(args) or list(kwargs.pop("children", ()) or ())
-
+        kids: List[Any] = list(children)
         style = kwargs.pop("style", None)
         plain_style, bindings = _resolve_style_with_values(style)
 
@@ -1397,13 +1391,13 @@ def _make_animated_factory(
             text = children[0] if children else kwargs.pop("text", "")
             return _Text(text, style=plain_style, ref=ref, **kwargs)
         if element_type == "Image":
-            source = children[0] if children else kwargs.pop("source", "")
+            source = kids[0] if kids else kwargs.pop("source", "")
             return _Image(source, style=plain_style, ref=ref, **kwargs)
         if not accept_children:
-            children = []
-        return _View(*children, style=plain_style, ref=ref, **kwargs)
+            kids = []
+        return _View(*kids, style=plain_style, ref=ref, **kwargs)
 
-    return _animated
+    return Component(_animated, display_name=f"Animated.{element_type}")
 
 
 def _animated_prop_name(prop: str) -> str:

{pythonnative-0.33.0 → pythonnative-0.35.0}/src/pythonnative/cli/pn.py

@@ -196,8 +196,7 @@ def init_project(args: argparse.Namespace) -> None:
     # ``is_symlink()`` so the whole class is closed, not one spelling of it.
     if name and (target.is_symlink() or target.resolve().parent != cwd.resolve()):
         print(
-            f"Refusing to scaffold through a link or outside the current directory: {name}. "
-            "Use a plain directory name."
+            f"Refusing to scaffold through a link or outside the current directory: {name}. Use a plain directory name."
         )
         sys.exit(1)
 

pythonnative-0.35.0/src/pythonnative/component.py

@@ -0,0 +1,255 @@
+"""The ``@component`` decorator and the [`Component`][pythonnative.Component] type.
+
+A component is a plain Python function that takes props and returns a
+[`Node`][pythonnative.element.Node]: an [`Element`][pythonnative.Element],
+a list of elements, or ``None``. Decorating it with
+[`@component`][pythonnative.component.component] turns it into a
+[`Component`][pythonnative.Component]: a callable that *describes* a
+render (it returns an ``Element`` whose ``type`` is the component)
+instead of performing one. The reconciler invokes the function body
+later, with hook state installed.
+
+The decorator preserves the function's signature for type checkers via
+:class:`typing.ParamSpec`, so ``Greeting(nme="x")`` is a static error
+and editors autocomplete props from the function definition.
+
+Children
+--------
+
+Children are positional. A component that accepts children declares a
+``*children`` parameter, exactly like the built-in containers:
+
+```python
+@pn.component
+def Card(*children: pn.Element, title: str = "") -> pn.Element:
+    return pn.Column(pn.Text(title, style=pn.style(bold=True)), *children)
+
+Card(pn.Text("body"), title="Hello")
+```
+
+Positional arguments to a component *without* ``*children`` bind to its
+positional parameters, so ``Greeting("World")`` works for
+``def Greeting(name: str)``.
+
+Keys
+----
+
+Every component accepts ``key=`` at the call site for keyed
+reconciliation. ``key`` is consumed by the framework and is not passed
+to the function unless the function declares a ``key`` parameter
+itself. Declaring it (``key: str | None = None``) is the way to keep
+strict type checkers happy when a component is rendered in a list;
+otherwise use [`Element.with_key`][pythonnative.element.Element.with_key].
+"""
+
+from __future__ import annotations
+
+import functools
+import inspect
+from typing import Any, Awaitable, Callable, Dict, Generic, List, Optional, ParamSpec, Tuple, Union
+
+from .element import Element, Node
+
+__all__ = ["Component", "RenderFn", "component", "memo", "is_component"]
+
+P = ParamSpec("P")
+
+RenderFn = Callable[P, Union[Node, Awaitable[Node]]]
+"""A component body: returns a [`Node`][pythonnative.element.Node], or awaits one when ``async def``."""
+
+
+class Component(Generic[P]):
+    """A render-function wrapped by [`@component`][pythonnative.component.component].
+
+    Calling a ``Component`` does not run the function; it returns an
+    [`Element`][pythonnative.Element] describing the call so the
+    reconciler can mount it, preserve its hook state across renders,
+    and re-run it when its state or props change.
+
+    Attributes:
+        fn: The original render function.
+        display_name: Name shown in diagnostics and dev tooling
+            (defaults to ``fn.__name__``).
+        memoized: Whether [`memo`][pythonnative.memo] was applied, in
+            which case the reconciler skips re-rendering this component
+            when its props are shallowly equal to the previous render.
+        accepts_children: Whether ``fn`` declares ``*children``.
+    """
+
+    __slots__ = (
+        "fn",
+        "display_name",
+        "memoized",
+        "props_equal",
+        "accepts_children",
+        "_positional",
+        "_declares_key",
+        "_is_async",
+        "__wrapped__",
+        "__dict__",
+    )
+
+    def __init__(self, fn: RenderFn[P], *, display_name: Optional[str] = None) -> None:
+        if isinstance(fn, Component):
+            raise TypeError(f"{fn!r} is already a component; remove the duplicate @component")
+        sig = inspect.signature(fn)
+        positional: List[str] = []
+        accepts_children = False
+        declares_key = False
+        for name, param in sig.parameters.items():
+            if param.kind in (inspect.Parameter.POSITIONAL_ONLY, inspect.Parameter.POSITIONAL_OR_KEYWORD):
+                positional.append(name)
+            elif param.kind is inspect.Parameter.VAR_POSITIONAL:
+                accepts_children = True
+            if name == "key":
+                declares_key = True
+        self.fn = fn
+        self.display_name = display_name or getattr(fn, "__name__", "Component")
+        self.memoized = False
+        self.props_equal: Optional[Callable[[Dict[str, Any], Dict[str, Any]], bool]] = None
+        self.accepts_children = accepts_children
+        self._positional: Tuple[str, ...] = tuple(positional)
+        self._declares_key = declares_key
+        self._is_async = inspect.iscoroutinefunction(fn)
+        self.__wrapped__ = fn
+        functools.update_wrapper(self, fn, updated=())
+
+    # ------------------------------------------------------------------
+    # Element construction
+    # ------------------------------------------------------------------
+
+    def __call__(self, *args: P.args, **kwargs: P.kwargs) -> Element:
+        """Describe a render of this component with the given props."""
+        props: Dict[str, Any] = dict(kwargs)
+        key = props.pop("key", None) if not self._declares_key else props.get("key")
+        children: List[Any] = []
+        if args:
+            if self.accepts_children:
+                children = list(args)
+            else:
+                names = self._positional
+                if len(args) > len(names):
+                    raise TypeError(
+                        f"{self.display_name}() takes {len(names)} positional argument(s) but "
+                        f"{len(args)} were given. Declare *children to accept child elements."
+                    )
+                for name, value in zip(names, args):
+                    if name in props:
+                        raise TypeError(f"{self.display_name}() got multiple values for argument {name!r}")
+                    props[name] = value
+        return Element(self, props, children, key=key if isinstance(key, str) or key is None else str(key))
+
+    # ------------------------------------------------------------------
+    # Rendering (used by the reconciler)
+    # ------------------------------------------------------------------
+
+    def render(self, element: Element) -> Any:
+        """Invoke the render function for ``element``.
+
+        Children stored on the element are passed positionally; props
+        are passed by keyword. Returns whatever the function returned
+        (an element, a list, ``None``, or a coroutine for ``async def``
+        bodies).
+        """
+        if self.accepts_children:
+            return self.fn(*element.children, **element.props)
+        return self.fn(**element.props)  # type: ignore[call-arg]
+
+    @property
+    def is_async(self) -> bool:
+        """Whether the render function is an ``async def``."""
+        return self._is_async
+
+    def __repr__(self) -> str:
+        flags = " memo" if self.memoized else ""
+        return f"<Component {self.display_name}{flags}>"
+
+    def __get__(self, instance: Any, owner: Any = None) -> "Component[P]":
+        # Components stored on classes (rare) should not bind ``self``.
+        return self
+
+
+def component(fn: RenderFn[P]) -> Component[P]:
+    """Turn a render function into a [`Component`][pythonnative.Component].
+
+    The decorated function may use hooks (``use_state``, ``use_effect``,
+    etc.) and returns an [`Element`][pythonnative.Element] tree, a list
+    of elements, or ``None``. Each call site creates an independent
+    component instance with its own hook state.
+
+    Args:
+        fn: The render function. May be ``async def``; the body is then
+            driven by the reconciler and suspends on pending awaits (see
+            [`Suspense`][pythonnative.Suspense]).
+
+    Returns:
+        A ``Component`` whose call signature mirrors ``fn`` (plus the
+        framework ``key=`` keyword).
+
+    Example:
+        ```python
+        import pythonnative as pn
+
+        @pn.component
+        def Greeting(name: str = "World"):
+            return pn.Text(f"Hello, {name}!")
+        ```
+    """
+    return Component(fn)
+
+
+def memo(
+    target: Optional[Component[P]] = None,
+    *,
+    equal: Optional[Callable[[Dict[str, Any], Dict[str, Any]], bool]] = None,
+) -> Any:
+    """Skip a component's render when its props haven't changed.
+
+    Apply on top of ``@component``. When the reconciler re-renders the
+    parent tree, a memoized child is skipped (its previously-rendered
+    subtree is reused) iff its props and children are equal to the
+    previous render and none of its own state setters fired. Props are
+    compared shallowly by default: callables by identity, everything
+    else by ``==``.
+
+    Pair with [`use_callback`][pythonnative.use_callback] when passing
+    callbacks as props, otherwise a fresh closure defeats the memo.
+
+    Args:
+        target: A [`Component`][pythonnative.Component].
+        equal: Optional custom comparator ``(old_props, new_props) ->
+            bool`` replacing the shallow comparison.
+
+    Returns:
+        The same component, marked for memoization (or a decorator when
+        called with keyword arguments only).
+
+    Example:
+        ```python
+        @pn.memo
+        @pn.component
+        def ExpensiveRow(label: str):
+            ...
+
+        @pn.memo(equal=lambda a, b: a["id"] == b["id"])
+        @pn.component
+        def Row(id: int, extra: dict):
+            ...
+        ```
+    """
+
+    def apply(comp: Component[P]) -> Component[P]:
+        if not isinstance(comp, Component):
+            raise TypeError("@memo must wrap a @component; write @memo above @component")
+        comp.memoized = True
+        comp.props_equal = equal
+        return comp
+
+    if target is None:
+        return apply
+    return apply(target)
+
+
+def is_component(obj: Any) -> bool:
+    """Return whether ``obj`` is a [`Component`][pythonnative.Component]."""
+    return isinstance(obj, Component)

pythonnative-0.35.0/src/pythonnative/components/__init__.py

@@ -0,0 +1,106 @@
+"""Built-in element factories.
+
+Each factory function (``Text``, ``Button``, …) is a fully-typed thin
+wrapper that builds an [`Element`][pythonnative.Element] through the
+shared ``_make_element`` helper, so style resolution, ``ref``
+attachment, ``None``-default dropping, and forced overrides (e.g.
+``Column``'s fixed ``flex_direction``) live in exactly one place. The
+factory signatures themselves are the canonical prop schemas: editors
+and type checkers validate calls directly against them.
+
+The factories are grouped by concern into submodules (``text``,
+``media``, ``controls``, ``layout``, ``pressable``, ``overlays``,
+``structural``, ``lists``); everything public is re-exported here, so
+``from pythonnative.components import Text`` keeps working.
+
+Example:
+    ```python
+    import pythonnative as pn
+
+    pn.Column(
+        pn.Text("Hello", style=pn.style(font_size=18)),
+        pn.Button("Tap", on_press=lambda: print("tapped")),
+        style=pn.style(spacing=12, padding=16),
+    )
+    ```
+"""
+
+from ._base import _SPAN_STYLE_KEYS, _flatten_text_spans, _make_element  # noqa: F401
+from .controls import (
+    ActivityIndicator,
+    Checkbox,
+    DatePicker,
+    Picker,
+    ProgressBar,
+    RefreshControl,
+    SegmentedControl,
+    Slider,
+    StatusBar,
+    Switch,
+)
+from .layout import (  # noqa: F401
+    _SAFE_AREA_EDGES,
+    Column,
+    KeyboardAvoidingView,
+    Row,
+    SafeAreaView,
+    ScrollView,
+    Spacer,
+    View,
+    _KeyboardAvoidingContainer,
+    _numeric_edge_padding,
+    _SafeAreaContainer,
+)
+from .lists import (  # noqa: F401
+    _DEFAULT_ROW_EXTENT,
+    FlatList,
+    ListController,
+    SectionList,
+    _all_extents_known,
+    _dispatch_scroll_command,
+    _native_lists_supported,
+    _NativeList,
+    _RowSpec,
+    _VirtualizedList,
+)
+from .media import Image, ImageBackground, WebView
+from .overlays import Modal, Portal
+from .pressable import Pressable, TouchableOpacity, _StatefulPressable  # noqa: F401
+from .structural import ErrorBoundary, Fragment, Suspense
+from .text import Button, Text, TextInput
+
+__all__ = [
+    "ActivityIndicator",
+    "Button",
+    "Checkbox",
+    "Column",
+    "DatePicker",
+    "ErrorBoundary",
+    "FlatList",
+    "Fragment",
+    "Image",
+    "ImageBackground",
+    "KeyboardAvoidingView",
+    "ListController",
+    "Modal",
+    "Picker",
+    "Portal",
+    "Pressable",
+    "ProgressBar",
+    "RefreshControl",
+    "Row",
+    "SafeAreaView",
+    "ScrollView",
+    "SectionList",
+    "SegmentedControl",
+    "Slider",
+    "Spacer",
+    "StatusBar",
+    "Suspense",
+    "Switch",
+    "Text",
+    "TextInput",
+    "TouchableOpacity",
+    "View",
+    "WebView",
+]