pyview-web 0.3.0__py3-none-any.whl → 0.8.0a2__py3-none-any.whl

pyview/js.py

@@ -1,62 +1,65 @@
 import json
+from dataclasses import dataclass
 from typing import Any, Optional
-from pyview.vendor.ibis import filters
+
 from pyview.template.context_processor import context_processor
-from dataclasses import dataclass
+from pyview.vendor.ibis import filters
 
 
 @context_processor
-def add_js(meta):
+def add_js(meta) -> dict[str, "JsCommands"]:
     return {"js": JsCommands([])}
 
 
 @filters.register("js.add_class")
-def js_add_class(js: "JsCommands", selector: str, *classes):
+def js_add_class(js: "JsCommands", selector: str, *classes) -> "JsCommands":
     return js.add_class(selector, *classes)
 
 
 @filters.register("js.remove_class")
-def js_remove_class(js: "JsCommands", selector: str, *classes):
+def js_remove_class(js: "JsCommands", selector: str, *classes) -> "JsCommands":
     return js.remove_class(selector, *classes)
 
 
 @filters.register("js.show")
-def js_show(js: "JsCommands", selector: str):
+def js_show(js: "JsCommands", selector: str) -> "JsCommands":
     return js.show(selector)
 
 
 @filters.register("js.hide")
-def js_hide(js: "JsCommands", selector: str):
+def js_hide(js: "JsCommands", selector: str) -> "JsCommands":
     return js.hide(selector)
 
 
 @filters.register("js.toggle")
-def js_toggle(js: "JsCommands", selector: str):
+def js_toggle(js: "JsCommands", selector: str) -> "JsCommands":
     return js.toggle(selector)
 
 
 @filters.register("js.dispatch")
-def js_dispatch(js: "JsCommands", event: str, selector: str):
+def js_dispatch(js: "JsCommands", event: str, selector: str) -> "JsCommands":
     return js.dispatch(event, selector)
 
 
 @filters.register("js.push")
-def js_push(js: "JsCommands", event: str, payload: Optional[dict[str, Any]] = None):
+def js_push(js: "JsCommands", event: str, payload: Optional[dict[str, Any]] = None) -> "JsCommands":
     return js.push(event, payload)
 
 
 @filters.register("js.focus")
-def js_focus(js: "JsCommands", selector: str):
+def js_focus(js: "JsCommands", selector: str) -> "JsCommands":
     return js.focus(selector)
 
 
 @filters.register("js.focus_first")
-def js_focus_first(js: "JsCommands", selector: str):
+def js_focus_first(js: "JsCommands", selector: str) -> "JsCommands":
     return js.focus_first(selector)
 
 
 @filters.register("js.transition")
-def js_transition(js: "JsCommands", selector: str, transition: str, time: int = 200):
+def js_transition(
+    js: "JsCommands", selector: str, transition: str, time: int = 200
+) -> "JsCommands":
     return js.transition(selector, transition, time)
 
 
@@ -91,13 +94,9 @@ class JsCommands:
     def dispatch(self, event: str, selector: str) -> "JsCommands":
         return self.add(JsCommand("dispatch", {"to": selector, "event": event}))
 
-    def push(
-        self, event: str, payload: Optional[dict[str, Any]] = None
-    ) -> "JsCommands":
+    def push(self, event: str, payload: Optional[dict[str, Any]] = None) -> "JsCommands":
         return self.add(
-            JsCommand(
-                "push", {"event": event} | ({"value": payload} if payload else {})
-            )
+            JsCommand("push", {"event": event} | ({"value": payload} if payload else {}))
         )
 
     def focus(self, selector: str) -> "JsCommands":
@@ -106,9 +105,7 @@ class JsCommands:
     def focus_first(self, selector: str) -> "JsCommands":
         return self.add(JsCommand("focus_first", {"to": selector}))
 
-    def transition(
-        self, selector: str, transition: str, time: int = 200
-    ) -> "JsCommands":
+    def transition(self, selector: str, transition: str, time: int = 200) -> "JsCommands":
         return self.add(
             JsCommand(
                 "transition",
@@ -116,5 +113,5 @@ class JsCommands:
             )
         )
 
-    def __str__(self):
+    def __str__(self) -> str:
         return json.dumps([(c.cmd, c.opts) for c in self.commands])

pyview/live_routes.py

@@ -1,7 +1,9 @@
-from pyview.live_view import LiveView
-from typing import Callable, Any
+from typing import Any, Callable
+
 from starlette.routing import compile_path
 
+from pyview.live_view import LiveView
+
 
 class LiveViewLookup:
     def __init__(self):
@@ -15,7 +17,7 @@ class LiveViewLookup:
         # Find all matching routes
         matches = []
 
-        for path_format, path_regex, param_convertors, lv in self.routes:
+        for _path_format, path_regex, param_convertors, lv in self.routes:
             match_obj = path_regex.match(path)
             if match_obj is not None:
                 params = match_obj.groupdict()

pyview/live_socket.py

@@ -1,34 +1,42 @@
 from __future__ import annotations
-from starlette.websockets import WebSocket
+
+import datetime
 import json
 import logging
+import uuid
+from contextlib import suppress
 from typing import (
+    TYPE_CHECKING,
     Any,
-    TypeVar,
+    Callable,
     Generic,
-    TYPE_CHECKING,
     Optional,
-    Union,
     TypeAlias,
     TypeGuard,
+    TypeVar,
+    Union,
 )
-from urllib.parse import urlencode
-from apscheduler.schedulers.asyncio import AsyncIOScheduler
+from urllib.parse import urlencode, urlparse
+
 from apscheduler.jobstores.base import JobLookupError
-from pyview.vendor.flet.pubsub import PubSubHub, PubSub
+from apscheduler.schedulers.asyncio import AsyncIOScheduler
+from starlette.websockets import WebSocket
+
+from pyview.async_stream_runner import AsyncStreamRunner
+from pyview.binding.helpers import call_handle_params
+from pyview.components.manager import ComponentsManager
 from pyview.events import InfoEvent
-from pyview.uploads import UploadConstraints, UploadConfig, UploadManager
 from pyview.meta import PyViewMeta
 from pyview.template.render_diff import calc_diff
-import datetime
-from pyview.async_stream_runner import AsyncStreamRunner
+from pyview.uploads import UploadConfig, UploadConstraints, UploadManager
+from pyview.vendor.flet.pubsub import PubSub, PubSubHub
 
 logger = logging.getLogger(__name__)
 
 
 if TYPE_CHECKING:
-    from .live_view import LiveView
     from .instrumentation import InstrumentationProvider
+    from .live_view import LiveView
 
 
 pub_sub_hub = PubSubHub()
@@ -36,19 +44,52 @@ pub_sub_hub = PubSubHub()
 T = TypeVar("T")
 
 
-def is_connected(socket: LiveViewSocket[T]) -> TypeGuard["ConnectedLiveViewSocket[T]"]:
+def is_connected(socket: LiveViewSocket[T]) -> TypeGuard[ConnectedLiveViewSocket[T]]:
     return socket.connected
 
 
+class UnconnectedLiveView:
+    """Stub liveview that raises if send_parent() is called in unconnected phase."""
+
+    async def handle_event(self, event: str, payload: dict[str, Any], socket: Any) -> None:
+        raise RuntimeError(
+            "send_parent() is not available during initial HTTP render. "
+            "Component events only work after WebSocket connection."
+        )
+
+
 class UnconnectedSocket(Generic[T]):
     context: T
     live_title: Optional[str] = None
     connected: bool = False
+    _liveview: UnconnectedLiveView
+    components: ComponentsManager
+
+    def __init__(self) -> None:
+        self._liveview = UnconnectedLiveView()
+        self.components = ComponentsManager(self)
+
+    @property
+    def liveview(self) -> UnconnectedLiveView:
+        return self._liveview
 
     def allow_upload(
-        self, upload_name: str, constraints: UploadConstraints
+        self,
+        upload_name: str,
+        constraints: UploadConstraints,
+        auto_upload: bool = False,
+        progress: Optional[Callable] = None,
+        external: Optional[Callable] = None,
+        entry_complete: Optional[Callable] = None,
     ) -> UploadConfig:
-        return UploadConfig(name=upload_name, constraints=constraints)
+        return UploadConfig(
+            name=upload_name,
+            constraints=constraints,
+            autoUpload=auto_upload,
+            progress_callback=progress,
+            external_callback=external,
+            entry_complete_callback=entry_complete,
+        )
 
 
 class ConnectedLiveViewSocket(Generic[T]):
@@ -64,23 +105,63 @@ class ConnectedLiveViewSocket(Generic[T]):
         topic: str,
         liveview: LiveView,
         scheduler: AsyncIOScheduler,
-        instrumentation: "InstrumentationProvider",
+        instrumentation: InstrumentationProvider,
     ):
         self.websocket = websocket
         self.topic = topic
         self.liveview = liveview
         self.instrumentation = instrumentation
-        self.scheduled_jobs = []
+        self.scheduled_jobs = set()
         self.connected = True
         self.pub_sub = PubSub(pub_sub_hub, topic)
         self.pending_events = []
         self.upload_manager = UploadManager()
         self.stream_runner = AsyncStreamRunner(self)
         self.scheduler = scheduler
+        self.components = ComponentsManager(self)
 
     @property
     def meta(self) -> PyViewMeta:
-        return PyViewMeta()
+        return PyViewMeta(socket=self)
+
+    async def render_with_components(self) -> dict[str, Any]:
+        """
+        Render the LiveView and all its components.
+
+        Handles the full component lifecycle:
+        1. Begin render cycle (track seen components)
+        2. Render parent LiveView template
+        3. Run pending component lifecycle (mount/update)
+        4. Prune stale components not in this render
+        5. Render all component templates with ROOT flag
+
+        Returns:
+            Rendered tree in Phoenix wire format
+        """
+        import sys
+
+        # Start new render cycle - track which components are seen during parent render
+        self.components.begin_render()
+
+        rendered = (await self.liveview.render(self.context, self.meta)).tree()
+
+        # Component rendering requires Python 3.14+ (t-string support)
+        if sys.version_info < (3, 14):
+            return rendered
+
+        from pyview.components.lifecycle import run_nested_component_lifecycle
+
+        # Run component lifecycle and get rendered trees in one pass
+        rendered_trees = await run_nested_component_lifecycle(self, self.meta)
+
+        # Clean up components that were removed from the DOM
+        self.components.prune_stale_components()
+
+        # Include rendered component trees in response
+        if rendered_trees:
+            rendered["c"] = {str(cid): tree for cid, tree in rendered_trees.items()}
+
+        return rendered
 
     async def subscribe(self, topic: str):
         await self.pub_sub.subscribe_topic_async(topic, self._topic_callback_internal)
@@ -96,16 +177,19 @@ class ConnectedLiveViewSocket(Generic[T]):
         self.scheduler.add_job(
             self.send_info, args=[event], id=id, trigger="interval", seconds=seconds
         )
-        self.scheduled_jobs.append(id)
+        self.scheduled_jobs.add(id)
 
     def schedule_info_once(self, event, seconds=None):
+        job_id = f"{self.topic}:once:{uuid.uuid4().hex}"
         self.scheduler.add_job(
-            self.send_info,
-            args=[event],
+            self._send_info_once,
+            args=[job_id, event],
+            id=job_id,
             trigger="date",
             run_date=datetime.datetime.now() + datetime.timedelta(seconds=seconds or 0),
             misfire_grace_time=None,
         )
+        self.scheduled_jobs.add(job_id)
 
     def diff(self, render: dict[str, Any]) -> dict[str, Any]:
         if self.prev_rendered:
@@ -116,24 +200,31 @@ class ConnectedLiveViewSocket(Generic[T]):
         self.prev_rendered = render
         return diff
 
+    async def _send_info_once(self, job_id: str, event: InfoEvent):
+        """Wrapper for one-time info sends that cleans up the job ID after execution"""
+        await self.send_info(event)
+        self.scheduled_jobs.discard(job_id)
+
     async def send_info(self, event: InfoEvent):
         await self.liveview.handle_info(event, self)
-        r = await self.liveview.render(self.context, self.meta)
-        resp = [None, None, self.topic, "diff", self.diff(r.tree())]
+
+        rendered = await self.render_with_components()
+        resp = [None, None, self.topic, "diff", self.diff(rendered)]
 
         try:
             await self.websocket.send_text(json.dumps(resp))
         except Exception:
-            for id in self.scheduled_jobs:
+            for id in list(self.scheduled_jobs):
                 logger.debug("Removing scheduled job %s", id)
                 try:
                     self.scheduler.remove_job(id)
                 except Exception:
-                    logger.warning(
-                        "Failed to remove scheduled job %s", id, exc_info=True
-                    )
+                    logger.warning("Failed to remove scheduled job %s", id, exc_info=True)
+
+    async def push_patch(self, path: str, params: Optional[dict[str, Any]] = None):
+        if params is None:
+            params = {}
 
-    async def push_patch(self, path: str, params: dict[str, Any] = {}):
         # or "replace"
         kind = "push"
 
@@ -153,21 +244,27 @@ class ConnectedLiveViewSocket(Generic[T]):
         ]
 
         # TODO another way to marshall this
-        for k in params:
-            params[k] = [params[k]]
+        # Create a copy to avoid mutating the caller's dict
+        params_for_handler = {k: [v] for k, v in params.items()}
 
-        await self.liveview.handle_params(to, params, self)
+        # Parse string to ParseResult for type consistency
+        parsed_url = urlparse(to)
+        await call_handle_params(self.liveview, parsed_url, params_for_handler, self)
         try:
             await self.websocket.send_text(json.dumps(message))
         except Exception:
             logger.warning("Error sending patch message", exc_info=True)
 
-    async def push_navigate(self, path: str, params: dict[str, Any] = {}):
+    async def push_navigate(self, path: str, params: Optional[dict[str, Any]] = None):
         """Navigate to a different LiveView without full page reload"""
+        if params is None:
+            params = {}
         await self._navigate(path, params, kind="push")
 
-    async def replace_navigate(self, path: str, params: dict[str, Any] = {}):
+    async def replace_navigate(self, path: str, params: Optional[dict[str, Any]] = None):
         """Navigate to a different LiveView, replacing current history entry"""
+        if params is None:
+            params = {}
         await self._navigate(path, params, kind="replace")
 
     async def _navigate(self, path: str, params: dict[str, Any], kind: str):
@@ -192,32 +289,58 @@ class ConnectedLiveViewSocket(Generic[T]):
         except Exception:
             logger.warning("Error sending navigation message", exc_info=True)
 
+    async def redirect(self, path: str, params: Optional[dict[str, Any]] = None):
+        """Redirect to a new location with full page reload"""
+        if params is None:
+            params = {}
+        to = path
+        if params:
+            to = to + "?" + urlencode(params)
+
+        message = [
+            None,
+            None,
+            self.topic,
+            "redirect",
+            {"to": to},
+        ]
+
+        try:
+            await self.websocket.send_text(json.dumps(message))
+        except Exception:
+            logger.warning("Error sending redirect message", exc_info=True)
+
     async def push_event(self, event: str, value: dict[str, Any]):
         self.pending_events.append((event, value))
 
     def allow_upload(
-        self, upload_name: str, constraints: UploadConstraints
+        self,
+        upload_name: str,
+        constraints: UploadConstraints,
+        auto_upload: bool = False,
+        progress: Optional[Callable] = None,
+        external: Optional[Callable] = None,
+        entry_complete: Optional[Callable] = None,
     ) -> UploadConfig:
-        return self.upload_manager.allow_upload(upload_name, constraints)
+        return self.upload_manager.allow_upload(
+            upload_name, constraints, auto_upload, progress, external, entry_complete
+        )
 
     async def close(self):
         self.connected = False
-        for id in self.scheduled_jobs:
-            try:
+        for id in list(self.scheduled_jobs):
+            with suppress(JobLookupError):
                 self.scheduler.remove_job(id)
-            except JobLookupError:
-                pass
         await self.pub_sub.unsubscribe_all_async()
 
-        try:
+        with suppress(Exception):
             self.upload_manager.close()
-        except Exception:
-            pass
 
-        try:
+        with suppress(Exception):
+            self.components.clear()
+
+        with suppress(Exception):
             await self.liveview.disconnect(self)
-        except Exception:
-            pass
 
 
 LiveViewSocket: TypeAlias = Union[ConnectedLiveViewSocket[T], UnconnectedSocket[T]]

pyview/live_view.py

@@ -1,22 +1,22 @@
-from typing import TypeVar, Generic, Optional, Union, Any
-from .live_socket import LiveViewSocket, ConnectedLiveViewSocket
+from typing import Any, Generic, Optional, TypeVar
+from urllib.parse import ParseResult
+
+from pyview.events import InfoEvent
+from pyview.meta import PyViewMeta
 from pyview.template import (
+    LiveRender,
     LiveTemplate,
-    template_file,
     RenderedContent,
-    LiveRender,
     find_associated_file,
+    template_file,
 )
-from pyview.events import InfoEvent
-from pyview.meta import PyViewMeta
-from urllib.parse import ParseResult
+
+from .live_socket import ConnectedLiveViewSocket, LiveViewSocket
 
 T = TypeVar("T")
 
 Session = dict[str, Any]
-
-# TODO: ideally this would always be a ParseResult, but we need to update push_patch
-URL = Union[ParseResult, str]
+URL = ParseResult
 
 
 class LiveView(Generic[T]):
@@ -26,13 +26,25 @@ class LiveView(Generic[T]):
     async def mount(self, socket: LiveViewSocket[T], session: Session):
         pass
 
-    async def handle_event(self, event, payload, socket: ConnectedLiveViewSocket[T]):
+    async def handle_event(self, *args, **kwargs) -> None:
+        """Handle client events (clicks, form submissions).
+
+        Common signatures:
+            handle_event(self, socket, amount: int)      # new style
+            handle_event(self, event, payload, socket)   # legacy style
+        """
         pass
 
     async def handle_info(self, event: InfoEvent, socket: ConnectedLiveViewSocket[T]):
         pass
 
-    async def handle_params(self, url: URL, params, socket: LiveViewSocket[T]):
+    async def handle_params(self, *args, **kwargs) -> None:
+        """Called when URL params change.
+
+        Common signatures:
+            handle_params(self, socket, page: int = 1)   # new style
+            handle_params(self, url, params, socket)     # legacy style
+        """
         pass
 
     async def disconnect(self, socket: ConnectedLiveViewSocket[T]):

pyview/meta.py

@@ -1,6 +1,18 @@
-from dataclasses import dataclass
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:
+    from pyview.components import SocketWithComponents
 
 
 @dataclass
 class PyViewMeta:
-    pass
+    """
+    Metadata passed to LiveView render and template methods.
+
+    Attributes:
+        socket: Optional reference to the socket (for component registration).
+                Can be either ConnectedLiveViewSocket or UnconnectedSocket.
+    """
+
+    socket: Optional["SocketWithComponents"] = field(default=None, repr=False)

pyview/phx_message.py

@@ -1,13 +1,15 @@
-from starlette.websockets import WebSocketDisconnect
-from starlette.types import Message
 import json
+import struct
+
+from starlette.types import Message
+from starlette.websockets import WebSocketDisconnect
 
 
 def parse_message(message: Message) -> tuple[str, str, str, str, dict]:
     if "text" in message:
         data = message["text"]
-        [joinRef, mesageRef, topic, event, payload] = json.loads(data)
-        return joinRef, mesageRef, topic, event, payload
+        [joinRef, messageRef, topic, event, payload] = json.loads(data)
+        return joinRef, messageRef, topic, event, payload
 
     if "bytes" in message:
         data = message["bytes"]
@@ -19,15 +21,12 @@ def parse_message(message: Message) -> tuple[str, str, str, str, dict]:
     raise WebSocketDisconnect(message["code"])
 
 
-import struct
-
-
 class BinaryUploadSerDe:
     def deserialize(self, encoded_data: bytes) -> tuple[str, str, str, str, bytes]:
         offset = 0
 
         # Read the kind (1 byte)
-        kind = struct.unpack_from("B", encoded_data, offset)[0]
+        _kind = struct.unpack_from("B", encoded_data, offset)[0]
         offset += 1
 
         # Read lengths (4 bytes total, 1 byte each)

pyview/playground/__init__.py

@@ -0,0 +1,10 @@
+"""Playground module for creating single-file PyView examples."""
+
+from pyview.playground.builder import PlaygroundBuilder, playground
+from pyview.playground.favicon import Favicon
+
+__all__ = [
+    "Favicon",
+    "PlaygroundBuilder",
+    "playground",
+]