pythonnative 0.40.0__cp314-cp314-win_amd64.whl

pythonnative/navigation/screen.py

@@ -0,0 +1,149 @@
+"""Screen definitions and the typed options a screen accepts."""
+
+from __future__ import annotations
+
+import sys
+from typing import Any, Callable, Dict, Literal, Mapping, Optional, TypedDict, Union
+
+if sys.version_info >= (3, 11):
+    from typing import Unpack
+else:  # pragma: no cover
+    from typing_extensions import Unpack
+
+from ..element import Element
+
+__all__ = ["HeaderSlot", "ScreenDef", "ScreenOptions", "Unpack"]
+
+HeaderSlot = Union[Element, Callable[[], Optional[Element]], None]
+"""An element (or zero-arg factory) rendered into a header slot."""
+
+
+class ScreenOptions(TypedDict, total=False):
+    """Per-screen options accepted by ``Screen(...)`` and ``nav.set_options(...)``.
+
+    All keys are optional. Navigators ignore keys they don't use; the
+    native host applies the header keys it can (see the platform notes
+    on each key).
+
+    Attributes:
+        title: Screen title. Stack navigators show it in the native
+            navigation bar; tab and drawer navigators use it as the item
+            label.
+        header_shown: Whether the native navigation bar is visible for
+            this screen (default ``True``).
+        header_large_title: iOS: use a large title that collapses on
+            scroll. Ignored elsewhere.
+        header_back_title: iOS: label of the back button shown on the
+            *next* screen when it navigates back to this one. Ignored
+            elsewhere.
+        header_back_visible: Whether the back button is shown
+            (default ``True``).
+        header_left: Element (or factory) rendered at the leading edge
+            of the navigation bar. Rendered by PythonNative into the bar
+            on iOS; ignored on Android and in the browser preview today.
+        header_right: Element (or factory) rendered at the trailing edge
+            of the navigation bar (same platform notes as
+            ``header_left``).
+        header_tint_color: Color of the bar's buttons and back chevron.
+        header_style: Style dict for the bar itself; ``background_color``
+            is honored on every platform that draws a bar.
+        header_title_style: Style dict for the title label
+            (``color``, ``font_size``, ``bold``).
+        presentation: ``"card"`` (default) pushes; ``"modal"`` presents
+            the screen as a sheet on iOS and as a full-screen push
+            elsewhere.
+        gesture_enabled: Whether the interactive back gesture (iOS
+            swipe) can pop this screen (default ``True``).
+        animation: Transition to use when the screen is pushed:
+            ``"default"``, ``"none"``, ``"fade"``, ``"slide_from_right"``,
+            ``"slide_from_bottom"``. Only ``"none"`` versus animated is
+            distinguished on iOS and Android today.
+        tab_bar_icon: Native system icon identifier for tab items. A
+            string is used on every platform; a dict like
+            ``{"ios": "house.fill", "android": "ic_menu_home"}`` selects
+            per platform (SF Symbols on iOS, ``android.R.drawable.<name>``
+            on Android).
+        tab_bar_badge: Badge text or count shown on the tab item.
+        tab_bar_label: Label used for the tab item when it should differ
+            from ``title``.
+        lazy: Tab and drawer navigators only: mount the screen the first
+            time it's focused (default ``True``) instead of at
+            navigator mount.
+        unmount_on_blur: Tab and drawer navigators only: unmount the
+            screen when it loses focus instead of keeping it alive
+            hidden (default ``False``).
+    """
+
+    title: str
+    header_shown: bool
+    header_large_title: bool
+    header_back_title: str
+    header_back_visible: bool
+    header_left: HeaderSlot
+    header_right: HeaderSlot
+    header_tint_color: str
+    header_style: Dict[str, Any]
+    header_title_style: Dict[str, Any]
+    presentation: Literal["card", "modal"]
+    gesture_enabled: bool
+    animation: Literal["default", "none", "fade", "slide_from_right", "slide_from_bottom"]
+    tab_bar_icon: Union[str, Dict[str, str]]
+    tab_bar_badge: Union[str, int]
+    tab_bar_label: str
+    lazy: bool
+    unmount_on_blur: bool
+
+
+class ScreenDef:
+    """Configuration for one screen inside a navigator.
+
+    Created by ``Navigator.Screen(name, component, **options)``.
+
+    Attributes:
+        name: Route name used by ``nav.navigate(name)``.
+        component: The ``@component`` rendered when this screen is
+            active. Receives no props; read params with
+            [`use_route`][pythonnative.use_route].
+        options: Static [`ScreenOptions`][pythonnative.ScreenOptions]
+            for the screen. May be a callable ``(route) -> options`` to
+            derive options from the route's params.
+        initial_params: Params merged under any params supplied by
+            ``navigate`` when this screen is first shown.
+    """
+
+    __slots__ = ("name", "component", "options", "initial_params")
+
+    def __init__(
+        self,
+        name: str,
+        component: Callable[[], Any],
+        *,
+        options: Union[ScreenOptions, Callable[[Any], ScreenOptions], None] = None,
+        initial_params: Optional[Mapping[str, Any]] = None,
+        **option_kwargs: Unpack[ScreenOptions],
+    ) -> None:
+        if not name or not isinstance(name, str):
+            raise TypeError("Screen name must be a non-empty string")
+        if not callable(component):
+            raise TypeError(f"Screen {name!r}: component must be a @component, got {component!r}")
+        self.name = name
+        self.component = component
+        if callable(options):
+            if option_kwargs:
+                raise TypeError("Pass either a callable `options` or keyword options, not both")
+            self.options: Union[ScreenOptions, Callable[[Any], ScreenOptions]] = options
+        else:
+            merged: Dict[str, Any] = dict(options or {})
+            merged.update(option_kwargs)
+            self.options = merged  # type: ignore[assignment]
+        self.initial_params: Dict[str, Any] = dict(initial_params or {})
+
+    def resolve_options(self, route: Any) -> Dict[str, Any]:
+        """Return the static options, evaluating a callable ``options`` for ``route``."""
+        opts = self.options
+        if callable(opts):
+            return dict(opts(route) or {})
+        return dict(opts)
+
+    def __repr__(self) -> str:
+        return f"Screen({self.name!r})"

pythonnative/navigation/state.py

@@ -0,0 +1,269 @@
+"""Immutable navigation state and the pure operations on it.
+
+A navigator's state is a [`NavigationState`][pythonnative.navigation.NavigationState]:
+an ordered tuple of [`Route`][pythonnative.navigation.Route] entries
+plus the index of the active one. Stack navigators treat the tuple as
+a history (the active route is always the last); tab and drawer
+navigators keep one route per screen and move the index.
+
+Every operation returns a new state, so navigators can store the state
+in ``use_state`` and diff it like any other value. States serialize to
+plain dicts (``to_dict`` / ``from_dict``) so a native host can hand a
+pushed screen the full history it belongs to.
+"""
+
+from __future__ import annotations
+
+import itertools
+from typing import Any, Dict, Iterable, Iterator, Mapping, Optional, Sequence, Tuple, cast
+
+__all__ = ["NavigationState", "Route", "RouteParams"]
+
+type RouteParams = Mapping[str, Any]
+"""Bound for the ``P`` type parameter of [`Route`][pythonnative.navigation.Route].
+
+Declare a screen's params as a ``TypedDict`` and read them with
+``use_route(MyParams)`` for a fully typed ``route.params``.
+"""
+
+_route_keys = itertools.count(1)
+
+
+def _new_key(name: str) -> str:
+    return f"{name}-{next(_route_keys)}"
+
+
+class Route[P: RouteParams = Dict[str, Any]]:
+    """One entry in a navigator's state.
+
+    ``Route`` is generic in its params type. Bare ``Route`` is
+    ``Route[dict[str, Any]]``; pass a ``TypedDict`` to
+    [`use_route`][pythonnative.use_route] to get ``Route[MyParams]``
+    with a typed ``params`` attribute:
+
+    ```python
+    class DetailParams(TypedDict):
+        id: int
+
+    route = pn.use_route(DetailParams)
+    route.params["id"]  # int
+    ```
+
+    Attributes:
+        name: The screen name this route renders.
+        params: Parameters passed to the screen (read with
+            [`use_route`][pythonnative.use_route]). Always a plain
+            ``dict`` at runtime.
+        key: Stable identity for this particular visit to the screen,
+            unique per process. Two pushes of the same screen have
+            different keys, so their component state never mixes.
+        state: Seed state for a navigator rendered by this screen
+            (set by ``navigate("Tabs", screen="Profile")`` and by deep
+            links). ``None`` for ordinary screens.
+    """
+
+    __slots__ = ("name", "params", "key", "state")
+
+    def __init__(
+        self,
+        name: str,
+        params: Optional[Mapping[str, Any]] = None,
+        key: Optional[str] = None,
+        state: Optional["NavigationState"] = None,
+    ) -> None:
+        self.name = name
+        self.params: P = cast(P, dict(params or {}))
+        self.key = key or _new_key(name)
+        self.state = state
+
+    def with_params(self, params: Mapping[str, Any], *, merge: bool = True) -> "Route[P]":
+        """Return a copy carrying ``params`` (merged over the current ones by default)."""
+        merged = {**self.params, **params} if merge else dict(params)
+        return Route(self.name, merged, key=self.key, state=self.state)
+
+    def with_state(self, state: Optional["NavigationState"]) -> "Route[P]":
+        """Return a copy carrying a nested navigator seed ``state``."""
+        return Route(self.name, self.params, key=self.key, state=state)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Serialize to a plain dict (``name``, ``params``, ``key``, and ``state`` when nested)."""
+        out: Dict[str, Any] = {"name": self.name, "params": dict(self.params), "key": self.key}
+        if self.state is not None:
+            out["state"] = self.state.to_dict()
+        return out
+
+    @classmethod
+    def from_dict(cls, data: Mapping[str, Any]) -> "Route[Dict[str, Any]]":
+        """Rebuild a route from ``to_dict`` output, keeping its ``key`` so component state carries over."""
+        params = data.get("params")
+        nested = data.get("state")
+        return Route(
+            str(data["name"]),
+            params if isinstance(params, Mapping) else {},
+            key=data.get("key"),
+            state=NavigationState.from_dict(nested) if isinstance(nested, Mapping) and nested.get("routes") else None,
+        )
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Route):
+            return NotImplemented
+        return (
+            self.name == other.name
+            and self.params == other.params
+            and self.key == other.key
+            and self.state == other.state
+        )
+
+    def __hash__(self) -> int:
+        return hash(self.key)
+
+    def __repr__(self) -> str:
+        return f"Route({self.name!r}, params={self.params!r}, key={self.key!r})"
+
+
+class NavigationState:
+    """Immutable ordered routes plus the active index.
+
+    Attributes:
+        routes: The routes, oldest first.
+        index: Position of the active route in ``routes``.
+    """
+
+    __slots__ = ("routes", "index")
+
+    def __init__(self, routes: Iterable[Route], index: Optional[int] = None) -> None:
+        self.routes: Tuple[Route, ...] = tuple(routes)
+        if not self.routes:
+            raise ValueError("NavigationState needs at least one route")
+        self.index = len(self.routes) - 1 if index is None else index
+        if not 0 <= self.index < len(self.routes):
+            raise IndexError(f"index {self.index} out of range for {len(self.routes)} route(s)")
+
+    # ------------------------------------------------------------------
+    # Introspection
+    # ------------------------------------------------------------------
+
+    @property
+    def current(self) -> Route:
+        """The active route."""
+        return self.routes[self.index]
+
+    @property
+    def can_go_back(self) -> bool:
+        """Whether a route precedes the active one."""
+        return self.index > 0
+
+    def find(self, name: str) -> Optional[int]:
+        """Index of the most recent route named ``name``, or ``None``."""
+        for i in range(len(self.routes) - 1, -1, -1):
+            if self.routes[i].name == name:
+                return i
+        return None
+
+    def __len__(self) -> int:
+        return len(self.routes)
+
+    def __iter__(self) -> Iterator[Route]:
+        return iter(self.routes)
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, NavigationState):
+            return NotImplemented
+        return self.routes == other.routes and self.index == other.index
+
+    def __repr__(self) -> str:
+        names = [r.name for r in self.routes]
+        return f"NavigationState({names!r}, index={self.index})"
+
+    # ------------------------------------------------------------------
+    # Stack operations (history semantics)
+    # ------------------------------------------------------------------
+
+    def push(
+        self, name: str, params: Optional[Mapping[str, Any]] = None, state: Optional["NavigationState"] = None
+    ) -> "NavigationState":
+        """Append a new route and make it active (drops any forward entries)."""
+        kept = self.routes[: self.index + 1]
+        return NavigationState(kept + (Route(name, params, state=state),))
+
+    def pop(self, count: int = 1) -> "NavigationState":
+        """Remove up to ``count`` routes from the end (never below one)."""
+        keep = max(1, len(self.routes) - max(0, count))
+        return NavigationState(self.routes[:keep])
+
+    def pop_to_top(self) -> "NavigationState":
+        """Keep only the first route."""
+        return NavigationState(self.routes[:1])
+
+    def pop_to(
+        self, name: str, params: Optional[Mapping[str, Any]] = None, state: Optional["NavigationState"] = None
+    ) -> "NavigationState":
+        """Pop back to the most recent route named ``name``, merging ``params`` into it."""
+        idx = self.find(name)
+        if idx is None:
+            raise KeyError(name)
+        routes = list(self.routes[: idx + 1])
+        if params:
+            routes[-1] = routes[-1].with_params(params)
+        if state is not None:
+            routes[-1] = routes[-1].with_state(state)
+        return NavigationState(routes)
+
+    def replace(
+        self, name: str, params: Optional[Mapping[str, Any]] = None, state: Optional["NavigationState"] = None
+    ) -> "NavigationState":
+        """Swap the active route for a fresh one (new key, so state resets)."""
+        routes = list(self.routes)
+        routes[self.index] = Route(name, params, state=state)
+        return NavigationState(routes, self.index)
+
+    def navigate(
+        self, name: str, params: Optional[Mapping[str, Any]] = None, state: Optional["NavigationState"] = None
+    ) -> "NavigationState":
+        """Go to ``name``: pop back to it if it's in the history, else push it."""
+        if self.find(name) is not None:
+            return self.pop_to(name, params, state)
+        return self.push(name, params, state)
+
+    # ------------------------------------------------------------------
+    # Tab / drawer operations (one route per screen)
+    # ------------------------------------------------------------------
+
+    def jump_to(
+        self, name: str, params: Optional[Mapping[str, Any]] = None, state: Optional["NavigationState"] = None
+    ) -> "NavigationState":
+        """Activate the route named ``name`` in place, merging ``params``."""
+        idx = self.find(name)
+        if idx is None:
+            raise KeyError(name)
+        routes = list(self.routes)
+        if params:
+            routes[idx] = routes[idx].with_params(params)
+        if state is not None:
+            routes[idx] = routes[idx].with_state(state)
+        return NavigationState(routes, idx)
+
+    # ------------------------------------------------------------------
+    # Shared
+    # ------------------------------------------------------------------
+
+    def set_params(self, params: Mapping[str, Any]) -> "NavigationState":
+        """Merge ``params`` into the active route."""
+        routes = list(self.routes)
+        routes[self.index] = routes[self.index].with_params(params)
+        return NavigationState(routes, self.index)
+
+    def reset(self, routes: Sequence[Route], index: Optional[int] = None) -> "NavigationState":
+        """Return a state holding exactly ``routes`` with ``index`` active (the last route by default)."""
+        return NavigationState(routes, index)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Serialize to a plain dict with ``routes`` (each via ``Route.to_dict``) and ``index``."""
+        return {"routes": [r.to_dict() for r in self.routes], "index": self.index}
+
+    @classmethod
+    def from_dict(cls, data: Mapping[str, Any]) -> "NavigationState":
+        """Rebuild a state from ``to_dict`` output; a missing ``index`` activates the last route."""
+        routes = [Route.from_dict(r) for r in data.get("routes", [])]
+        index = data.get("index")
+        return cls(routes, int(index) if isinstance(index, int) else None)

pythonnative/net.py

@@ -0,0 +1,248 @@
+"""Async HTTP client (``pn.fetch``).
+
+A small, dependency-free coroutine wrapper around
+:mod:`urllib.request`. Operates on bytes internally and exposes a
+:class:`Response` with `text()`, `json()`, and `bytes` accessors.
+
+The implementation is deliberately minimal; it covers the
+"call a JSON API" path that's overwhelmingly the use case for mobile
+apps. For streaming, multipart uploads, or HTTP/2, integrate
+``httpx`` / ``aiohttp`` directly; this module won't try to compete.
+
+Example:
+    ```python
+    import pythonnative as pn
+
+
+    async def load_user(user_id):
+        resp = await pn.fetch(
+            f"https://api.example.com/users/{user_id}",
+            headers={"Accept": "application/json"},
+        )
+        resp.raise_for_status()
+        return resp.json()
+    ```
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import ssl
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass, field
+from typing import Any, Dict, Mapping, Optional, Union
+
+# A package-level SSL context lets callers (or tests) override TLS
+# verification globally without monkeypatching the stdlib. Defaults
+# to the system trust store.
+_default_ssl_context: Optional[ssl.SSLContext] = None
+
+
+def set_default_ssl_context(context: Optional[ssl.SSLContext]) -> None:
+    """Override the SSL context used by [`fetch`][pythonnative.fetch].
+
+    ``None`` (the default) means ``urllib`` builds a context from
+    the system trust store. Tests can pass an unverified context.
+    """
+    global _default_ssl_context
+    _default_ssl_context = context
+
+
+# ======================================================================
+# Response object
+# ======================================================================
+
+
+@dataclass
+class Response:
+    """The result of a [`fetch`][pythonnative.fetch] call.
+
+    Attributes:
+        status: HTTP status code (e.g. ``200``).
+        url: Final URL after any redirects.
+        headers: Response headers, case-insensitive.
+        content: Raw response body.
+    """
+
+    status: int
+    url: str
+    headers: Mapping[str, str] = field(default_factory=dict)
+    content: bytes = b""
+
+    @property
+    def ok(self) -> bool:
+        """``True`` if the status is in the 2xx range."""
+        return 200 <= self.status < 300
+
+    def __repr__(self) -> str:
+        cls = type(self).__name__
+        return f"{cls}(status={self.status}, url={self.url!r}, ok={self.ok}, content={len(self.content)} bytes)"
+
+    def text(self, encoding: Optional[str] = None) -> str:
+        """Decode ``content`` to ``str``.
+
+        Args:
+            encoding: Optional override; defaults to the
+                ``charset`` parameter of ``Content-Type`` (or UTF-8).
+        """
+        enc = encoding or _charset_from_headers(self.headers) or "utf-8"
+        try:
+            return self.content.decode(enc)
+        except (UnicodeDecodeError, LookupError):
+            return self.content.decode("utf-8", errors="replace")
+
+    def json(self) -> Any:
+        """Parse the response body as JSON.
+
+        Raises:
+            json.JSONDecodeError: If the body isn't valid JSON.
+        """
+        return json.loads(self.text())
+
+    def raise_for_status(self) -> None:
+        """Raise [`HTTPError`][pythonnative.net.HTTPError] for non-2xx responses."""
+        if not self.ok:
+            raise HTTPError(self.status, self.url, self.text())
+
+
+class HTTPError(Exception):
+    """Raised by [`Response.raise_for_status`][pythonnative.net.Response.raise_for_status]."""
+
+    def __init__(self, status: int, url: str, body: str) -> None:
+        super().__init__(f"HTTP {status} from {url}: {body[:200]}")
+        self.status = status
+        self.url = url
+        self.body = body
+
+
+def _charset_from_headers(headers: Mapping[str, str]) -> Optional[str]:
+    ctype = headers.get("Content-Type") or headers.get("content-type")
+    if not ctype:
+        return None
+    for part in ctype.split(";"):
+        part = part.strip()
+        if part.lower().startswith("charset="):
+            return part[len("charset=") :].strip().strip('"')
+    return None
+
+
+# ======================================================================
+# Public fetch coroutine
+# ======================================================================
+
+
+async def fetch(
+    url: str,
+    *,
+    method: str = "GET",
+    headers: Optional[Mapping[str, str]] = None,
+    body: Union[bytes, str, Mapping[str, Any], None] = None,
+    params: Optional[Mapping[str, Any]] = None,
+    timeout: float = 30.0,
+) -> Response:
+    """Make an HTTP request and return a [`Response`][pythonnative.net.Response].
+
+    Args:
+        url: Target URL. Relative URLs are not supported.
+        method: HTTP method (``"GET"``, ``"POST"``, ``"PUT"`` …).
+        headers: Optional request headers.
+        body: Request body. ``bytes`` are sent as-is; ``str`` is
+            UTF-8 encoded; ``dict`` is JSON-encoded with a
+            ``Content-Type: application/json`` header added (unless
+            already supplied).
+        params: Optional mapping of query-string parameters appended
+            to ``url`` (urlencoded).
+        timeout: Seconds to wait for the response (excluding the
+            time spent on DNS / connect).
+
+    Returns:
+        A [`Response`][pythonnative.net.Response].
+
+    Raises:
+        TimeoutError: If the request doesn't complete within
+            ``timeout`` seconds.
+        OSError: For network errors (DNS failure, connection refused,
+            etc.), re-raised from ``urllib``.
+
+    Example:
+        ```python
+        resp = await pn.fetch(
+            "https://api.example.com/posts",
+            method="POST",
+            body={"title": "Hello"},
+        )
+        resp.raise_for_status()
+        ```
+    """
+    request = _build_request(url=url, method=method, headers=headers, body=body, params=params)
+    return await asyncio.to_thread(_dispatch_request, request, timeout)
+
+
+def _build_request(
+    *,
+    url: str,
+    method: str,
+    headers: Optional[Mapping[str, str]],
+    body: Union[bytes, str, Mapping[str, Any], None],
+    params: Optional[Mapping[str, Any]],
+) -> urllib.request.Request:
+    if params:
+        sep = "&" if "?" in url else "?"
+        url = url + sep + urllib.parse.urlencode(params, doseq=True)
+
+    header_dict: Dict[str, str] = dict(headers or {})
+    payload: Optional[bytes] = None
+    if body is None:
+        pass
+    elif isinstance(body, (bytes, bytearray)):
+        payload = bytes(body)
+    elif isinstance(body, str):
+        payload = body.encode("utf-8")
+    elif isinstance(body, Mapping):
+        payload = json.dumps(body, default=str).encode("utf-8")
+        header_dict.setdefault("Content-Type", "application/json")
+    else:
+        raise TypeError(f"Unsupported body type: {type(body)!r}")
+
+    return urllib.request.Request(
+        url=url,
+        data=payload,
+        method=method.upper(),
+        headers=header_dict,
+    )
+
+
+def _dispatch_request(request: urllib.request.Request, timeout: float) -> Response:
+    context = _default_ssl_context
+    try:
+        with urllib.request.urlopen(request, timeout=timeout, context=context) as resp:
+            content = resp.read()
+            return Response(
+                status=resp.status,
+                url=resp.geturl(),
+                headers={k: v for k, v in resp.headers.items()},
+                content=content,
+            )
+    except urllib.error.HTTPError as exc:
+        # HTTPError is itself a response object; propagate the body
+        # so callers can inspect it before deciding to raise.
+        body = exc.read() if hasattr(exc, "read") else b""
+        return Response(
+            status=exc.code,
+            url=getattr(exc, "url", request.full_url),
+            headers={k: v for k, v in (exc.headers or {}).items()},
+            content=body,
+        )
+    except urllib.error.URLError as exc:
+        # Convert urllib's TimeoutError wrapper into a plain TimeoutError
+        # so callers get a recognisable exception type.
+        reason = getattr(exc, "reason", exc)
+        if isinstance(reason, TimeoutError):
+            raise reason
+        raise OSError(str(reason)) from exc
+
+
+__all__ = ["fetch", "Response", "HTTPError", "set_default_ssl_context"]