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

pyview/template/live_view_template.py

@@ -0,0 +1,338 @@
+"""
+LiveViewTemplate processor for Python t-strings.
+Converts Template objects into LiveView's diff tree structure.
+
+This module requires Python 3.14+ for t-string support.
+"""
+
+import sys
+from typing import TYPE_CHECKING, Any, Callable, TypeVar, Union
+from dataclasses import dataclass
+
+# T-string support requires Python 3.14+
+if sys.version_info < (3, 14):
+    raise ImportError(
+        "T-string template support requires Python 3.14 or later. "
+        f"Current version: {sys.version_info.major}.{sys.version_info.minor}"
+    )
+
+from string.templatelib import Template
+
+if TYPE_CHECKING:
+    from pyview.components.base import LiveComponent
+    from pyview.stream import Stream
+
+T = TypeVar("T")
+
+
+@dataclass
+class StreamList:
+    """
+    A list wrapper that carries stream metadata for T-string templates.
+
+    This is returned by stream_for() and detected by LiveViewTemplate._process_list()
+    to include the "stream" key in the wire format.
+    """
+
+    items: list[Any]
+    stream: "Stream"
+
+
+def stream_for(
+    stream: "Stream[T]",
+    render_fn: Callable[[str, T], "Template"],
+) -> StreamList:
+    """
+    Render a stream in a T-string template.
+
+    This function iterates over the stream and applies the render function to each item,
+    returning a StreamList that LiveViewTemplate will process to include stream metadata.
+
+    Args:
+        stream: The Stream to render
+        render_fn: A function that takes (dom_id, item) and returns a Template
+
+    Returns:
+        StreamList containing rendered items and stream reference
+
+    Example:
+        def template(self, assigns, meta):
+            return t'''
+            <div id="messages" phx-update="stream">
+                {stream_for(assigns.messages, lambda dom_id, msg:
+                    t'<div id="{dom_id}">{msg.text}</div>'
+                )}
+            </div>
+            '''
+    """
+    items = [render_fn(dom_id, item) for dom_id, item in stream]
+    return StreamList(items=items, stream=stream)
+
+
+@dataclass
+class LiveComponentPlaceholder:
+    """Placeholder for live components in templates."""
+
+    component_class: "type[LiveComponent]"
+    component_id: str
+    assigns: dict[str, Any]
+
+    def __str__(self):
+        # Return a placeholder that gets replaced during rendering
+        return f"<pyview-component cid='{self.component_id}'/>"
+
+
+@dataclass
+class ComponentMarker:
+    """Marker for component that will be resolved lazily in .text().
+
+    Used during unconnected (HTTP) phase to defer component rendering
+    until after lifecycle methods have run.
+    """
+
+    cid: int
+
+
+class LiveViewTemplate:
+    """Processes Python t-string Templates into LiveView diff tree format."""
+
+    @staticmethod
+    def process(template: Template, socket: Any = None) -> dict[str, Any]:
+        """
+        Convert a Python Template to LiveView diff tree format.
+
+        The LiveView tree format:
+        {
+            "s": ["static", "parts", "here"],  # Static strings
+            "0": "dynamic value",              # Dynamic values indexed by position
+            "1": { "s": [...], "0": ... },    # Nested structures
+            "d": [[...], [...]]               # For comprehensions (loops)
+        }
+        """
+        # Use the template.strings directly for the static parts
+        parts: dict[str, Any] = {"s": list(template.strings)}
+
+        # Process only the interpolations
+        interp_index = 0
+        for item in template:
+            if not isinstance(item, str):
+                # This is an Interpolation object
+                key = str(interp_index)
+
+                # Get the actual value from the interpolation
+                interp_value = item.value
+
+                # Apply format specifier if present
+                if hasattr(item, "format_spec") and item.format_spec:
+                    try:
+                        formatted_value = format(interp_value, item.format_spec)
+                    except (ValueError, TypeError):
+                        # If formatting fails, use the value as-is
+                        formatted_value = interp_value
+                else:
+                    formatted_value = interp_value
+
+                # Handle different interpolation types
+                if isinstance(formatted_value, LiveComponentPlaceholder):
+                    # Handle live component - Phoenix.js expects CID as a number
+                    # which it looks up in output.components[cid]
+                    if socket and hasattr(socket, "components"):
+                        cid = socket.components.register(
+                            formatted_value.component_class,
+                            formatted_value.component_id,
+                            formatted_value.assigns,
+                        )
+                        if getattr(socket, "connected", True):
+                            # Connected: return CID for wire format
+                            parts[key] = cid
+                        else:
+                            # Unconnected: store marker for lazy resolution in .text()
+                            parts[key] = ComponentMarker(cid=cid)
+                    else:
+                        # Fallback if no socket available
+                        parts[key] = str(formatted_value)
+
+                elif isinstance(formatted_value, Template):
+                    # Handle nested templates
+                    parts[key] = LiveViewTemplate.process(formatted_value, socket)
+
+                elif isinstance(formatted_value, str):
+                    # Simple string interpolation (HTML escaped)
+                    parts[key] = LiveViewTemplate.escape_html(formatted_value)
+
+                elif isinstance(formatted_value, (int, float, bool)):
+                    # Primitive types
+                    parts[key] = str(formatted_value)
+
+                elif isinstance(formatted_value, StreamList):
+                    # Handle stream_for() results
+                    parts[key] = LiveViewTemplate._process_stream_list(formatted_value, socket)
+
+                elif isinstance(formatted_value, list):
+                    # Handle list comprehensions
+                    parts[key] = LiveViewTemplate._process_list(formatted_value, socket)
+
+                elif hasattr(formatted_value, "__html__"):
+                    # Handle objects that can render as HTML (like Markup)
+                    parts[key] = str(formatted_value.__html__())
+
+                else:
+                    # Default: convert to string and escape
+                    parts[key] = LiveViewTemplate.escape_html(str(formatted_value))
+
+                interp_index += 1
+
+        return parts
+
+    @staticmethod
+    def _process_list(items: list, socket: Any = None) -> Union[dict[str, Any], str]:
+        """Process a list of items for the 'd' (dynamics) format."""
+        if not items:
+            return ""
+
+        # Process each item based on its type
+        processed_items = []
+        for item in items:
+            if isinstance(item, Template):
+                # Process template items - produces {"s": [...], "0": ..., ...}
+                processed_items.append(LiveViewTemplate.process(item, socket))
+            elif isinstance(item, LiveComponentPlaceholder):
+                # Handle component placeholders in lists
+                # Phoenix.js expects CID as a number for component lookup
+                if socket and hasattr(socket, "components"):
+                    cid = socket.components.register(
+                        item.component_class,
+                        item.component_id,
+                        item.assigns,
+                    )
+                    if getattr(socket, "connected", True):
+                        # Connected: return CID for wire format
+                        processed_items.append(cid)
+                    else:
+                        # Unconnected: store marker for lazy resolution in .text()
+                        processed_items.append(ComponentMarker(cid=cid))
+                else:
+                    # Fallback if no socket available - just escaped string
+                    processed_items.append(LiveViewTemplate.escape_html(str(item)))
+            else:
+                # Plain strings - just escape, will be wrapped once in fallback
+                processed_items.append(LiveViewTemplate.escape_html(str(item)))
+
+        # Phoenix.js comprehension format ALWAYS requires:
+        # - "s": array of static strings (shared across all items)
+        # - "d": array where each item is an array of dynamic values
+        #
+        # processed_items contains either:
+        #   - dicts with {"s": [...], "0": val, "1": val, ...} for Template items
+        #   - integer CIDs for component references
+        #   - escaped strings for non-Template items
+
+        # Check if all items are dicts with the same statics (true comprehension)
+        if processed_items and isinstance(processed_items[0], dict) and "s" in processed_items[0]:
+            first_statics = processed_items[0]["s"]
+            all_same_statics = all(
+                isinstance(item, dict) and item.get("s") == first_statics
+                for item in processed_items
+            )
+
+            if all_same_statics:
+                # True comprehension: all items share same statics
+                # Extract statics to top level, keep only dynamics in "d"
+                # Note: We rely on Python 3.7+ dict insertion order here.
+                # Keys are inserted as "0", "1", "2", ... in process(), so
+                # item.items() yields them in correct order without sorting.
+                return {
+                    "s": first_statics,
+                    "d": [
+                        [v for k, v in item.items() if k != "s"]
+                        for item in processed_items
+                    ],
+                }
+
+        # For all other cases (mixed types, different statics, components, etc.):
+        # Use empty statics and wrap each item as a single dynamic
+        # This ensures Phoenix.js comprehensionToBuffer always has valid statics
+        return {
+            "s": ["", ""],
+            "d": [[item] for item in processed_items],
+        }
+
+    @staticmethod
+    def _process_stream_list(
+        stream_list: StreamList, socket: Any = None
+    ) -> Union[dict[str, Any], str]:
+        """Process a StreamList (from stream_for) including stream metadata."""
+        from pyview.stream import Stream
+
+        stream = stream_list.stream
+        items = stream_list.items
+
+        # Handle empty stream
+        if not items:
+            # Still check for delete/reset operations
+            ops = stream._get_pending_ops()
+            if ops is None:
+                return ""
+            return {"stream": stream._to_wire_format(ops)}
+
+        # Process each item
+        processed_items = []
+        for item in items:
+            if isinstance(item, Template):
+                processed_items.append(LiveViewTemplate.process(item, socket))
+            else:
+                processed_items.append([LiveViewTemplate.escape_html(str(item))])
+
+        result: dict[str, Any] = {"d": processed_items}
+
+        # Extract statics from first item if it has them.
+        # processed_items contains either:
+        #   - dicts with {"s": [...], "0": val, "1": val, ...} for Template items
+        #   - lists of escaped strings for non-Template items
+        if processed_items and isinstance(processed_items[0], dict) and "s" in processed_items[0]:
+            # All Template items share the same statics (the template's static strings),
+            # so we extract "s" from the first item and use it for the entire result.
+            result["s"] = processed_items[0]["s"]
+            # Convert each item to just its dynamic values (excluding "s").
+            # We rely on Python 3.7+ dict insertion order - keys are inserted as
+            # "0", "1", "2", ... in process(), so item.items() yields correct order.
+            # Non-dict items (lists): pass through as-is.
+            result["d"] = [
+                [v for k, v in item.items() if k != "s"]
+                if isinstance(item, dict)
+                else item
+                for item in processed_items
+            ]
+
+        # Add stream metadata
+        ops = stream._get_pending_ops()
+        if ops is not None:
+            result["stream"] = stream._to_wire_format(ops)
+
+        return result
+
+    @staticmethod
+    def escape_html(text: str) -> str:
+        """Escape HTML special characters."""
+        return (
+            text.replace("&", "&amp;")
+            .replace("<", "&lt;")
+            .replace(">", "&gt;")
+            .replace('"', "&quot;")
+            .replace("'", "&#x27;")
+        )
+
+
+def live_component(
+    component_class: "type[LiveComponent]", id: str, **assigns
+) -> LiveComponentPlaceholder:
+    """
+    Insert a live component into a template.
+
+    Usage:
+        comp = live_component(MyComponent, id="comp-1", foo="bar")
+        template = t'<div>{comp}</div>'
+    """
+    return LiveComponentPlaceholder(
+        component_class=component_class, component_id=id, assigns=assigns
+    )

pyview/template/render_diff.py

@@ -6,22 +6,38 @@ def calc_diff(old_tree: dict[str, Any], new_tree: dict[str, Any]) -> dict[str, A
     for key in new_tree:
         if key not in old_tree:
             diff[key] = new_tree[key]
-        elif (
-            isinstance(new_tree[key], dict)
-            and "s" in new_tree[key]
-            and "d" in new_tree[key]
-        ):
+        elif isinstance(new_tree[key], dict) and "s" in new_tree[key] and "d" in new_tree[key]:
             if isinstance(old_tree[key], str):
                 diff[key] = new_tree[key]
                 continue
 
-            # Handle special case of for loop
+            # Handle special case of for loop (comprehension)
             old_static = old_tree[key].get("s", [])
             new_static = new_tree[key]["s"]
 
-            old_dynamic = old_tree[key]["d"]
+            old_dynamic = old_tree[key].get("d", [])
             new_dynamic = new_tree[key]["d"]
 
+            # Check for stream metadata - always include if present
+            has_stream = "stream" in new_tree[key]
+
+            if has_stream:
+                # For streams, always include the stream operations
+                # The stream metadata contains insert/delete operations since last render
+                comp_diff: dict[str, Any] = {"stream": new_tree[key]["stream"]}
+
+                # Include dynamics if there are items being inserted
+                if new_dynamic:
+                    comp_diff["d"] = new_dynamic
+
+                # Include statics on first render or if changed
+                if old_static != new_static:
+                    comp_diff["s"] = new_static
+
+                diff[key] = comp_diff
+                continue
+
+            # Regular comprehension (non-stream)
             if old_static != new_static:
                 diff[key] = {"s": new_static, "d": new_dynamic}
                 continue
@@ -29,6 +45,16 @@ def calc_diff(old_tree: dict[str, Any], new_tree: dict[str, Any]) -> dict[str, A
             if old_dynamic != new_dynamic:
                 diff[key] = {"d": new_dynamic}
 
+        elif isinstance(new_tree[key], dict) and "stream" in new_tree[key]:
+            # Handle stream-only diff (no "s" or "d", just stream operations like delete-only)
+            diff[key] = new_tree[key]
+
+        elif new_tree[key] == "" and isinstance(old_tree[key], dict) and "stream" in old_tree[key]:
+            # Stream went from having items to no pending operations
+            # Don't report this as a change - client already has the content
+            # This is Phoenix LiveView semantics: stream items persist on client
+            pass
+
         elif isinstance(new_tree[key], dict) and isinstance(old_tree[key], dict):
             nested_diff = calc_diff(old_tree[key], new_tree[key])
             if nested_diff:

pyview/template/root_template.py

@@ -1,4 +1,5 @@
 from typing import Callable, Optional, TypedDict
+
 from markupsafe import Markup
 
 
@@ -16,32 +17,43 @@ ContentWrapper = Callable[[RootTemplateContext, Markup], Markup]
 
 
 def defaultRootTemplate(
-    css: Optional[Markup] = None, content_wrapper: Optional[ContentWrapper] = None
+    css: Optional[Markup] = None,
+    content_wrapper: Optional[ContentWrapper] = None,
+    title: Optional[str] = None,
+    title_suffix: Optional[str] = " | LiveView",
 ) -> RootTemplate:
     content_wrapper = content_wrapper or (lambda c, m: m)
 
     def template(context: RootTemplateContext) -> str:
-        return _defaultRootTemplate(context, css or Markup(""), content_wrapper)
+        return _defaultRootTemplate(
+            context, css or Markup(""), content_wrapper, title, title_suffix
+        )
 
     return template
 
 
 def _defaultRootTemplate(
-    context: RootTemplateContext, css: Markup, contentWrapper: ContentWrapper
+    context: RootTemplateContext,
+    css: Markup,
+    contentWrapper: ContentWrapper,
+    default_title: Optional[str] = None,
+    title_suffix: Optional[str] = " | LiveView",
 ) -> str:
-    suffix = " | LiveView"
-    render_title = (context["title"] + suffix) if context.get("title", None) is not None else "LiveView"  # type: ignore
+    suffix = title_suffix or ""
+    # Use context title if provided, otherwise use default_title, otherwise "LiveView"
+    title = context.get("title") or default_title
+    render_title = (title + suffix) if title is not None else "LiveView"
     main_content = contentWrapper(
         context,
         Markup(
             f"""
       <div
         data-phx-main="true"
-        data-phx-session="{context['session']}"
+        data-phx-session="{context["session"]}"
         data-phx-static=""
-        id="phx-{context['id']}"
+        id="phx-{context["id"]}"
         >
-        {context['content']}
+        {context["content"]}
     </div>"""
         ),
     )
@@ -55,7 +67,7 @@ def _defaultRootTemplate(
 <html lang="en">
     <head>
       <title data-suffix="{suffix}">{render_title}</title>
-      <meta name="csrf-token" content="{context['csrf_token']}" />
+      <meta name="csrf-token" content="{context["csrf_token"]}" />
       <meta charset="utf-8">
       <meta http-equiv="X-UA-Compatible" content="IE=edge">
       <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">

pyview/template/serializer.py

@@ -1,8 +1,5 @@
-from typing import Any, Union, Protocol, Optional
 from dataclasses import fields, is_dataclass
-from pydantic import BaseModel
-
-import inspect
+from typing import Any
 
 
 def serialize(assigns: Any) -> dict[str, Any]:
@@ -18,7 +15,7 @@ def serialize(assigns: Any) -> dict[str, Any]:
     raise TypeError("Assigns must be a dict or have an asdict() method")
 
 
-def isprop(v):
+def isprop(v) -> bool:
     return isinstance(v, property)
 
 

pyview/template/template_view.py

@@ -0,0 +1,170 @@
+"""
+LiveView support for t-string templates.
+
+This module requires Python 3.14+ for t-string support.
+"""
+
+import sys
+from typing import Any, TypeVar, Generic, Optional
+
+# T-string support requires Python 3.14+
+if sys.version_info < (3, 14):
+    raise ImportError(
+        "T-string template support requires Python 3.14 or later. "
+        f"Current version: {sys.version_info.major}.{sys.version_info.minor}"
+    )
+
+from pyview.components import SocketWithComponents
+from .live_view_template import LiveViewTemplate, ComponentMarker
+from string.templatelib import Template
+from pyview.meta import PyViewMeta
+
+T = TypeVar("T")
+
+
+class TStringRenderedContent:
+    """RenderedContent implementation for t-string templates."""
+
+    def __init__(self, tree_data: dict[str, Any]):
+        self._tree_data = tree_data
+
+    def tree(self) -> dict[str, Any]:
+        """Return the LiveView diff tree."""
+        return self._tree_data
+
+    def text(self, socket: Optional[SocketWithComponents] = None) -> str:
+        """Convert tree back to HTML string, resolving any component markers.
+
+        Args:
+            socket: Optional socket with components manager for resolving
+                    ComponentMarkers during unconnected phase.
+        """
+        return self._tree_to_html(self._tree_data, socket)
+
+    def _tree_to_html(self, tree: dict[str, Any] | list[Any], socket: Optional[SocketWithComponents] = None) -> str:
+        """Convert tree back to HTML, resolving ComponentMarkers."""
+        if isinstance(tree, str):
+            return tree
+
+        if isinstance(tree, ComponentMarker):
+            return self._resolve_component_marker(tree, socket)
+
+        if not isinstance(tree, dict):
+            return str(tree)
+
+        # Handle comprehension format with "s" and "d" keys
+        # This is the format for loops: {"s": ["<div>", "</div>"], "d": [["value1"], ["value2"]]}
+        if "d" in tree and "s" in tree:
+            statics = tree["s"]
+            dynamics_list = tree["d"]
+            html_items = []
+
+            for dynamics in dynamics_list:
+                # Each dynamics is a list of values to interleave with statics
+                parts = []
+                for i, static in enumerate(statics):
+                    parts.append(static)
+                    if i < len(dynamics):
+                        dyn = dynamics[i]
+                        parts.append(self._value_to_html(dyn, socket))
+                html_items.append("".join(parts))
+
+            return "".join(html_items)
+
+        # Handle "d" without "s" (just a list of items)
+        if "d" in tree:
+            items = tree["d"]
+            html_items = []
+            for item in items:
+                if isinstance(item, list) and len(item) == 1:
+                    html_items.append(self._value_to_html(item[0], socket))
+                else:
+                    html_items.append(self._tree_to_html(item, socket))
+            return "".join(html_items)
+
+        html_parts = []
+        statics = tree.get("s", [])
+
+        for i, static in enumerate(statics):
+            html_parts.append(static)
+
+            # Look for dynamic content
+            key = str(i)
+            if key in tree:
+                dynamic = tree[key]
+                html_parts.append(self._value_to_html(dynamic, socket))
+
+        return "".join(html_parts)
+
+    def _value_to_html(self, value: Any, socket: Optional[SocketWithComponents]) -> str:
+        """Convert a tree value to HTML string."""
+        if isinstance(value, ComponentMarker):
+            return self._resolve_component_marker(value, socket)
+        elif isinstance(value, dict):
+            return self._tree_to_html(value, socket)
+        elif isinstance(value, list):
+            return "".join(self._value_to_html(item, socket) for item in value)
+        else:
+            return str(value)
+
+    def _resolve_component_marker(self, marker: ComponentMarker, socket: Optional[SocketWithComponents]) -> str:
+        """Resolve a ComponentMarker to HTML by rendering the component."""
+        if not socket or not hasattr(socket, "components"):
+            return ""  # Component not available
+
+        meta = PyViewMeta(socket=socket)
+        template = socket.components.render_component(marker.cid, meta)
+        if template is None:
+            return ""
+
+        # Process the component template and recursively convert to HTML
+        component_tree = LiveViewTemplate.process(template, socket)
+        return self._tree_to_html(component_tree, socket)
+
+
+class TemplateView(Generic[T]):
+    """
+    Mixin for LiveView classes to support t-string templates.
+
+    Usage:
+        class MyView(TemplateView, LiveView[MyContext]):
+            def template(self, assigns: MyContext, meta: PyViewMeta):
+                return t'<div>{assigns.name}</div>'
+    """
+
+    async def render(self, assigns: T, meta: PyViewMeta):
+        """Override render to check for t-string template method."""
+
+        # Check if this class has a template method
+        if hasattr(self, "template") and callable(self.template):
+            # Call template method with both assigns and meta
+            template = self.template(assigns, meta)
+
+            # Ensure it returns a Template
+            if not isinstance(template, Template):
+                raise ValueError(
+                    f"template() method must return a Template, got {type(template)}"
+                )
+
+            # Process the template into LiveView tree format
+            # Pass socket for component registration if available
+            socket = meta.socket if meta else None
+            tree = LiveViewTemplate.process(template, socket=socket)
+
+            return TStringRenderedContent(tree)
+
+        # Fall back to parent implementation (Ibis templates)
+        return await super().render(assigns, meta)  # type: ignore
+
+    def template(self, assigns: T, meta: PyViewMeta) -> Template:
+        """
+        Override this method to provide a t-string template.
+
+        Args:
+            assigns: The typed context object (dataclass)
+            meta: PyViewMeta object with request info
+
+        Returns:
+            Template: A t-string Template object
+        """
+        raise NotImplementedError("Subclasses must implement the template() method")

pyview/template/utils.py

@@ -1,6 +1,7 @@
-from typing import Optional
 import inspect
 import os
+from typing import Optional
+
 from markupsafe import Markup
 
 
@@ -18,7 +19,7 @@ def find_associated_file(o: object, extension: str) -> Optional[str]:
 def find_associated_css(o: object) -> list[Markup]:
     css_file = find_associated_file(o, ".css")
     if css_file:
-        with open(css_file, "r") as css:
+        with open(css_file) as css:
             return [Markup(f"<style>{css.read()}</style>")]
 
     return []