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

pyview/playground/builder.py

@@ -0,0 +1,118 @@
+"""
+Playground helpers for creating single-file PyView examples.
+
+Example usage:
+
+    from pyview.playground import playground
+    from pyview import LiveView, LiveViewSocket
+
+    class CounterView(LiveView):
+        async def mount(self, socket: LiveViewSocket, session):
+            socket.context = {"count": 0}
+
+        async def handle_event(self, event, payload, socket: LiveViewSocket):
+            if event == "increment":
+                socket.context["count"] += 1
+
+        async def render(self, context, meta):
+            return f"<button phx-click='increment'>Count: {context['count']}</button>"
+
+    # Create app, run with: uvicorn module:app --reload
+    app = playground().with_live_view(CounterView).with_title("Counter").build()
+"""
+
+from typing import Optional
+
+from markupsafe import Markup
+from starlette.requests import Request
+from starlette.responses import Response
+from starlette.routing import Route
+from starlette.staticfiles import StaticFiles
+
+from pyview.live_view import LiveView
+from pyview.playground.favicon import Favicon, generate_favicon_svg
+from pyview.pyview import PyView
+from pyview.template import defaultRootTemplate
+
+
+class PlaygroundBuilder:
+    """Fluent builder for creating PyView playground applications."""
+
+    def __init__(self) -> None:
+        self._views: list[tuple[str, type[LiveView]]] = []
+        self._css: list[Markup] = []
+        self._title: Optional[str] = None
+        self._title_suffix: Optional[str] = " | LiveView"
+        self._favicon: Optional[Favicon] = Favicon()
+
+    def with_live_view(self, view: type[LiveView], path: str = "/") -> "PlaygroundBuilder":
+        """Add a LiveView to the application."""
+        self._views.append((path, view))
+        return self
+
+    def with_css(self, css: Markup | str) -> "PlaygroundBuilder":
+        """Add CSS/head content. Can be called multiple times to accumulate."""
+        self._css.append(Markup(css) if isinstance(css, str) else css)
+        return self
+
+    def with_title(self, title: str, suffix: Optional[str] = " | LiveView") -> "PlaygroundBuilder":
+        """Set the page title and optional suffix."""
+        self._title = title
+        self._title_suffix = suffix
+        return self
+
+    def with_favicon(self, favicon: Optional[Favicon]) -> "PlaygroundBuilder":
+        """Configure favicon generation. Pass None to disable."""
+        self._favicon = favicon
+        return self
+
+    def no_favicon(self) -> "PlaygroundBuilder":
+        """Disable auto-generated favicon."""
+        self._favicon = None
+        return self
+
+    def build(self) -> PyView:
+        """Build and return the configured PyView application."""
+        if not self._views:
+            raise ValueError("Must add at least one LiveView via with_live_view()")
+
+        app = PyView()
+
+        # Auto-mount static files
+        app.mount("/static", StaticFiles(packages=[("pyview", "static")]), name="static")
+
+        # Collect CSS entries
+        css_parts = list(self._css)
+
+        # Add favicon route and link tag if favicon config exists and title is set
+        if self._favicon is not None and self._title:
+            favicon_svg = generate_favicon_svg(
+                self._title,
+                bg_color=self._favicon.bg_color,
+                text_color=self._favicon.text_color,
+            )
+
+            async def favicon_route(request: Request) -> Response:
+                return Response(content=favicon_svg, media_type="image/svg+xml")
+
+            app.routes.append(Route("/favicon.svg", favicon_route, methods=["GET"]))
+            css_parts.append(Markup('<link rel="icon" href="/favicon.svg" type="image/svg+xml">'))
+
+        # Configure root template - join all CSS entries
+        combined_css = Markup("\n".join(css_parts)) if css_parts else None
+        app.rootTemplate = defaultRootTemplate(
+            css=combined_css,
+            title=self._title,
+            title_suffix=self._title_suffix,
+        )
+
+        # Add all LiveViews
+        for path, view in self._views:
+            app.add_live_view(path, view)
+
+        return app
+
+
+def playground() -> PlaygroundBuilder:
+    """Create a new playground builder."""
+    return PlaygroundBuilder()

pyview/playground/favicon.py

@@ -0,0 +1,39 @@
+"""Favicon generation utilities for PyView playground."""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class Favicon:
+    """Configuration for auto-generated favicon."""
+
+    bg_color: str = "#3b82f6"
+    text_color: str = "#ffffff"
+
+
+def generate_favicon_svg(
+    text: str,
+    bg_color: str = "#3b82f6",
+    text_color: str = "#ffffff",
+) -> str:
+    """Generate a rounded square SVG favicon with initials.
+
+    Args:
+        text: Text to extract initials from (e.g., app title)
+        bg_color: Background color (hex)
+        text_color: Text color (hex)
+
+    Returns:
+        SVG string
+    """
+    words = text.strip().split()
+    if len(words) >= 2:
+        initials = (words[0][0] + words[1][0]).upper()
+    else:
+        initials = words[0][0].upper() if words else "A"
+
+    return f'''<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
+  <rect width="100" height="100" rx="15" fill="{bg_color}"/>
+  <text x="50" y="50" font-family="sans-serif" font-size="52" font-weight="bold"
+        fill="{text_color}" text-anchor="middle" dominant-baseline="central">{initials}</text>
+</svg>'''

pyview/pyview.py

@@ -1,27 +1,32 @@
+import uuid
+from contextlib import asynccontextmanager
+from typing import Optional
+from urllib.parse import parse_qs, urlparse
+
 from starlette.applications import Starlette
-from starlette.responses import HTMLResponse
 from starlette.middleware.gzip import GZipMiddleware
-from starlette.routing import Route, WebSocketRoute
 from starlette.requests import Request
-import uuid
-from urllib.parse import parse_qs, urlparse
-from typing import Optional
+from starlette.responses import HTMLResponse
+from starlette.routing import Route, WebSocketRoute
 
-from pyview.live_socket import UnconnectedSocket
-from pyview.csrf import generate_csrf_token
-from pyview.session import serialize_session
 from pyview.auth import AuthProviderFactory
-from pyview.meta import PyViewMeta
+from pyview.binding import call_handle_params
+from pyview.components.lifecycle import run_nested_component_lifecycle
+from pyview.csrf import generate_csrf_token
 from pyview.instrumentation import InstrumentationProvider, NoOpInstrumentation
-from .ws_handler import LiveSocketHandler
-from .live_view import LiveView
+from pyview.live_socket import UnconnectedSocket
+from pyview.meta import PyViewMeta
+from pyview.session import serialize_session
+
 from .live_routes import LiveViewLookup
+from .live_view import LiveView
 from .template import (
     RootTemplate,
     RootTemplateContext,
     defaultRootTemplate,
     find_associated_css,
 )
+from .ws_handler import LiveSocketHandler
 
 
 class PyView(Starlette):
@@ -29,6 +34,10 @@ class PyView(Starlette):
     instrumentation: InstrumentationProvider
 
     def __init__(self, *args, instrumentation: Optional[InstrumentationProvider] = None, **kwargs):
+        # Extract user's lifespan if provided, then always use our composed lifespan
+        user_lifespan = kwargs.pop("lifespan", None)
+        kwargs["lifespan"] = self._create_lifespan(user_lifespan)
+
         super().__init__(*args, **kwargs)
         self.rootTemplate = defaultRootTemplate()
         self.instrumentation = instrumentation or NoOpInstrumentation()
@@ -38,20 +47,40 @@ class PyView(Starlette):
         self.routes.append(WebSocketRoute("/live/websocket", self.live_handler.handle))
         self.add_middleware(GZipMiddleware)
 
+    def _create_lifespan(self, user_lifespan=None):
+        """Create the lifespan context manager for proper startup/shutdown.
+
+        Args:
+            user_lifespan: Optional user-provided lifespan context manager to wrap
+        """
+
+        @asynccontextmanager
+        async def lifespan(app):
+            # Startup: Start the scheduler
+            app.live_handler.start_scheduler()
+
+            # Run user's lifespan if they provided one
+            if user_lifespan:
+                async with user_lifespan(app):
+                    yield
+            else:
+                yield
+
+            # Shutdown: Stop the scheduler
+            await app.live_handler.shutdown_scheduler()
+
+        return lifespan
+
     def add_live_view(self, path: str, view: type[LiveView]):
         async def lv(request: Request):
-            return await liveview_container(
-                self.rootTemplate, self.view_lookup, request
-            )
+            return await liveview_container(self.rootTemplate, self.view_lookup, request)
 
         self.view_lookup.add(path, view)
         auth = AuthProviderFactory.get(view)
         self.routes.append(Route(path, auth.wrap(lv), methods=["GET"]))
 
 
-async def liveview_container(
-    template: RootTemplate, view_lookup: LiveViewLookup, request: Request
-):
+async def liveview_container(template: RootTemplate, view_lookup: LiveViewLookup, request: Request):
     url = request.url
     path = url.path
     lv, path_params = view_lookup.get(path)
@@ -69,9 +98,14 @@ async def liveview_container(
     merged_params = {**query_params, **path_params}
 
     # Pass merged parameters to handle_params
-    await lv.handle_params(urlparse(url._url), merged_params, s)
+    await call_handle_params(lv, urlparse(url._url), merged_params, s)
+
+    # Pass socket to meta for component registration
+    meta = PyViewMeta(socket=s)
+    r = await lv.render(s.context, meta)
 
-    r = await lv.render(s.context, PyViewMeta())
+    # Run component lifecycle, including nested components
+    await run_nested_component_lifecycle(s, meta)
 
     liveview_css = find_associated_css(lv)
 
@@ -79,7 +113,7 @@ async def liveview_container(
 
     context: RootTemplateContext = {
         "id": id,
-        "content": r.text(),
+        "content": r.text(socket=s),  # Pass socket for ComponentMarker resolution
         "title": s.live_title,
         "csrf_token": generate_csrf_token("lv:phx-" + id),
         "session": serialize_session(session),

pyview/session.py

@@ -1,5 +1,7 @@
 from typing import Any, cast
+
 from itsdangerous import URLSafeSerializer
+
 from pyview.secret import get_secret