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

pyview/components/slots.py

@@ -0,0 +1,73 @@
+"""
+Slots support for LiveComponents.
+
+Slots allow parent templates to pass content into component slots,
+similar to React's children/slots or Phoenix LiveView's slots.
+
+Usage:
+    from pyview.components import live_component, slots
+
+    # Default slot only
+    live_component(Card, id="card-1", slots=slots(
+        t"<p>This is the card body content</p>"
+    ))
+
+    # Named slots
+    live_component(Card, id="card-1", slots=slots(
+        t"<p>Default body content</p>",
+        header=t"<h2>Card Title</h2>",
+        footer=t"<button>Submit</button>"
+    ))
+
+    # In the component template
+    class Card(LiveComponent[CardContext]):
+        def template(self, assigns: CardContext, meta: ComponentMeta):
+            return t'''
+                <div class="card">
+                    <header>{meta.slots['header']}</header>
+                    <main>{meta.slots['default']}</main>
+                    <footer>{meta.slots['footer']}</footer>
+                </div>
+            '''
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from string.templatelib import Template  # type: ignore[import-not-found]
+    from typing import TypeAlias
+
+    Slots: TypeAlias = dict[str, Template]
+else:
+    # Runtime: use Any to avoid import errors on Python < 3.14
+    Slots = dict[str, Any]
+
+
+def slots(__default: Template | None = None, **named: Template) -> Slots:
+    """
+    Create a slots dictionary for component children.
+
+    Args:
+        __default: The default/unnamed slot content (positional argument)
+        **named: Named slots (header, footer, etc.)
+
+    Returns:
+        Dictionary mapping slot names to template content
+
+    Examples:
+        # Default slot only
+        slots(t"<p>Body content</p>")
+
+        # Named slots only
+        slots(header=t"<h2>Title</h2>", footer=t"<button>OK</button>")
+
+        # Both default and named slots
+        slots(t"<p>Body</p>", header=t"<h2>Title</h2>")
+    """
+    result: Slots = {}
+    if __default is not None:
+        result["default"] = __default
+    result.update(named)
+    return result

pyview/csrf.py

@@ -1,7 +1,9 @@
-from itsdangerous import BadData, SignatureExpired, URLSafeTimedSerializer
-from typing import Optional
 import hmac
 import logging
+from typing import Optional
+
+from itsdangerous import BadData, SignatureExpired, URLSafeTimedSerializer
+
 from pyview.secret import get_secret
 
 logger = logging.getLogger(__name__)

pyview/events/AutoEventDispatch.py

@@ -0,0 +1,98 @@
+from typing import Callable
+
+from .BaseEventHandler import BaseEventHandler
+
+
+class BoundEventMethod:
+    """
+    A bound method wrapper that can be stringified to its event name.
+
+    This allows methods to be referenced in templates like {self.increment}
+    and have them automatically convert to their event name string.
+    """
+
+    def __init__(self, instance, func: Callable, event_name: str):
+        self.instance = instance
+        self.func = func
+        self.event_name = event_name
+
+    def __str__(self) -> str:
+        """Return the event name when converted to string (for template interpolation)."""
+        return self.event_name
+
+    async def __call__(self, *args, **kwargs):
+        """Still callable as a normal async method."""
+        return await self.func(self.instance, *args, **kwargs)
+
+
+class EventMethodDescriptor:
+    """
+    Descriptor that wraps event handler methods.
+
+    When accessed, returns a BoundEventMethod that:
+    1. Stringifies to the event name (for templates)
+    2. Remains callable (for direct invocation)
+    """
+
+    def __init__(self, func: Callable, event_name: str):
+        self.func = func
+        self.event_name = event_name
+        self.__name__ = func.__name__
+        self.__doc__ = func.__doc__
+
+    def __get__(self, obj, objtype=None):
+        if obj is None:
+            return self
+        return BoundEventMethod(obj, self.func, self.event_name)
+
+    def __set_name__(self, owner, name):
+        """Called when the descriptor is assigned to a class attribute."""
+        if not self.event_name:
+            self.event_name = name
+
+
+class AutoEventDispatch(BaseEventHandler):
+    """
+    Base class that enables automatic event dispatch from function references.
+
+    Methods decorated with @event (with or without explicit names) can be
+    referenced directly in templates, automatically converting to their event name.
+
+    Inherits from BaseEventHandler and extends it by wrapping decorated methods
+    with descriptors for template stringification.
+
+    Usage:
+        class MyView(AutoEventDispatch, TemplateView, LiveView):
+            @event  # or @event()
+            async def increment(self, event, payload, socket):
+                socket.context["count"] += 1
+
+            @event("custom-name")
+            async def some_handler(self, event, payload, socket):
+                pass
+
+            def template(self, assigns, meta):
+                return t'''
+                    <button phx-click={self.increment}>+</button>
+                    <button phx-click={self.some_handler}>Custom</button>
+                '''
+    """
+
+    def __init_subclass__(cls, **kwargs):
+        super().__init_subclass__(**kwargs)
+
+        # BaseEventHandler already populated _event_handlers with raw functions
+        # Now we wrap them with descriptors for template stringification
+        for event_name, handler in list(cls._event_handlers.items()):
+            # Find which attribute this handler came from
+            for attr_name in dir(cls):
+                if not attr_name.startswith("_"):
+                    attr = getattr(cls, attr_name, None)
+                    if attr is handler or (
+                        isinstance(attr, EventMethodDescriptor) and attr.func is handler
+                    ):
+                        # Wrap with descriptor if not already wrapped
+                        if not isinstance(attr, EventMethodDescriptor):
+                            descriptor = EventMethodDescriptor(handler, event_name)
+                            setattr(cls, attr_name, descriptor)
+                        break

pyview/events/BaseEventHandler.py

@@ -1,15 +1,39 @@
-from typing import Callable, TYPE_CHECKING
 import logging
+from typing import TYPE_CHECKING, Any, Callable
+
+from pyview.binding import BindContext, Binder, Params
 
 if TYPE_CHECKING:
     from pyview.live_view import InfoEvent
 
+logger = logging.getLogger(__name__)
+
 
 def event(*event_names):
-    """Decorator that marks methods as event handlers."""
+    """
+    Decorator that marks methods as event handlers.
+
+    Can be used with or without explicit event names:
+        @event                      # Uses method name as event name
+        @event()                    # Uses method name as event name
+        @event("custom-name")       # Uses "custom-name" as event name
+        @event("name1", "name2")    # Handles multiple event names
+
+    When used with AutoEventDispatch, methods without explicit names can be
+    referenced directly in templates: phx-click={self.increment}
+    """
+
+    def decorator(func: Callable) -> Callable:
+        # If no event names provided, use the function name
+        names = event_names if event_names else (func.__name__,)
+        func_any: Any = func
+        func_any._event_names = names
+        return func
 
-    def decorator(func):
-        func._event_names = event_names
+    # Handle @event without parentheses (decorator applied directly to function)
+    if len(event_names) == 1 and callable(event_names[0]):
+        func: Any = event_names[0]
+        func._event_names = (func.__name__,)
         return func
 
     return decorator
@@ -50,10 +74,29 @@ class BaseEventHandler:
     async def handle_event(self, event: str, payload: dict, socket):
         handler = self._event_handlers.get(event)
 
-        if handler:
-            return await handler(self, event, payload, socket)
-        else:
-            logging.warning(f"Unhandled event: {event} {payload}")
+        if not handler:
+            logger.warning(f"Unhandled event: {event} {payload}")
+            return
+
+        # Create bind context for event handling
+        ctx = BindContext(
+            params=Params({}),
+            payload=payload,
+            url=None,
+            socket=socket,
+            event=event,
+        )
+
+        # Bind parameters and invoke handler
+        binder = Binder()
+        result = binder.bind(handler, ctx)
+
+        if not result.success:
+            for err in result.errors:
+                logger.warning(f"Event binding error for '{event}': {err}")
+            raise ValueError(f"Event binding failed for '{event}': {result.errors}")
+
+        return await handler(self, **result.bound_args)
 
     async def handle_info(self, event: "InfoEvent", socket):
         handler = self._info_handlers.get(event.name)

pyview/events/__init__.py

@@ -1,4 +1,5 @@
+from .AutoEventDispatch import AutoEventDispatch
 from .BaseEventHandler import BaseEventHandler, event, info
 from .info_event import InfoEvent
 
-__all__ = ["BaseEventHandler", "event", "info", "InfoEvent"]
+__all__ = ["AutoEventDispatch", "BaseEventHandler", "event", "info", "InfoEvent"]

pyview/instrumentation/__init__.py

@@ -1,12 +1,12 @@
 """PyView instrumentation interfaces and implementations."""
 
 from .interfaces import (
-    InstrumentationProvider,
     Counter,
-    UpDownCounter,
     Gauge,
     Histogram,
+    InstrumentationProvider,
     Span,
+    UpDownCounter,
 )
 from .noop import NoOpInstrumentation
 
@@ -18,4 +18,4 @@ __all__ = [
     "Histogram",
     "Span",
     "NoOpInstrumentation",
-]
+]

pyview/instrumentation/interfaces.py

@@ -1,16 +1,16 @@
 """Abstract base classes for PyView instrumentation."""
 
-from abc import ABC, abstractmethod
-from typing import Any, Optional, Callable, Union
-from contextlib import contextmanager
+import asyncio
 import functools
 import time
-import asyncio
+from abc import ABC, abstractmethod
+from contextlib import contextmanager
+from typing import Any, Callable, Optional
 
 
 class Counter(ABC):
     """A monotonically increasing counter metric."""
-    
+
     @abstractmethod
     def add(self, value: float = 1, attributes: Optional[dict[str, Any]] = None) -> None:
         """Add to the counter value."""
@@ -19,7 +19,7 @@ class Counter(ABC):
 
 class UpDownCounter(ABC):
     """A counter that can increase or decrease."""
-    
+
     @abstractmethod
     def add(self, value: float, attributes: Optional[dict[str, Any]] = None) -> None:
         """Add to the counter value (can be negative)."""
@@ -28,7 +28,7 @@ class UpDownCounter(ABC):
 
 class Gauge(ABC):
     """A point-in-time value metric."""
-    
+
     @abstractmethod
     def set(self, value: float, attributes: Optional[dict[str, Any]] = None) -> None:
         """Set the gauge to a specific value."""
@@ -37,7 +37,7 @@ class Gauge(ABC):
 
 class Histogram(ABC):
     """A metric that tracks the distribution of values."""
-    
+
     @abstractmethod
     def record(self, value: float, attributes: Optional[dict[str, Any]] = None) -> None:
         """Record a value in the histogram."""
@@ -46,17 +46,17 @@ class Histogram(ABC):
 
 class Span(ABC):
     """A span representing a unit of work."""
-    
+
     @abstractmethod
     def set_attribute(self, key: str, value: Any) -> None:
         """Set an attribute on the span."""
         pass
-    
+
     @abstractmethod
     def add_event(self, name: str, attributes: Optional[dict[str, Any]] = None) -> None:
         """Add an event to the span."""
         pass
-    
+
     @abstractmethod
     def end(self, status: str = "ok") -> None:
         """End the span with a status."""
@@ -65,55 +65,65 @@ class Span(ABC):
 
 class InstrumentationProvider(ABC):
     """Abstract base class for instrumentation providers."""
-    
+
     # Create instruments (efficient, reusable)
     @abstractmethod
     def create_counter(self, name: str, description: str = "", unit: str = "") -> Counter:
         """Create a counter instrument."""
         pass
-    
+
     @abstractmethod
-    def create_updown_counter(self, name: str, description: str = "", unit: str = "") -> UpDownCounter:
+    def create_updown_counter(
+        self, name: str, description: str = "", unit: str = ""
+    ) -> UpDownCounter:
         """Create an up/down counter instrument."""
         pass
-    
+
     @abstractmethod
     def create_gauge(self, name: str, description: str = "", unit: str = "") -> Gauge:
         """Create a gauge instrument."""
         pass
-    
+
     @abstractmethod
     def create_histogram(self, name: str, description: str = "", unit: str = "") -> Histogram:
         """Create a histogram instrument."""
         pass
-    
+
     # Convenience methods (simple, pass name each time)
-    def increment_counter(self, name: str, value: float = 1, attributes: Optional[dict[str, Any]] = None) -> None:
+    def increment_counter(
+        self, name: str, value: float = 1, attributes: Optional[dict[str, Any]] = None
+    ) -> None:
         """Convenience method to increment a counter."""
         counter = self.create_counter(name)
         counter.add(value, attributes)
-    
-    def update_updown_counter(self, name: str, value: float, attributes: Optional[dict[str, Any]] = None) -> None:
+
+    def update_updown_counter(
+        self, name: str, value: float, attributes: Optional[dict[str, Any]] = None
+    ) -> None:
         """Convenience method to update an up/down counter."""
         counter = self.create_updown_counter(name)
         counter.add(value, attributes)
-    
-    def record_gauge(self, name: str, value: float, attributes: Optional[dict[str, Any]] = None) -> None:
+
+    def record_gauge(
+        self, name: str, value: float, attributes: Optional[dict[str, Any]] = None
+    ) -> None:
         """Convenience method to record a gauge value."""
         gauge = self.create_gauge(name)
         gauge.set(value, attributes)
-    
-    def record_histogram(self, name: str, value: float, attributes: Optional[dict[str, Any]] = None) -> None:
+
+    def record_histogram(
+        self, name: str, value: float, attributes: Optional[dict[str, Any]] = None
+    ) -> None:
         """Convenience method to record a histogram value."""
         histogram = self.create_histogram(name)
         histogram.record(value, attributes)
-    
+
     # Span methods
     @abstractmethod
     def start_span(self, name: str, attributes: Optional[dict[str, Any]] = None) -> Span:
         """Start a new span."""
         pass
-    
+
     # Context manager for spans
     @contextmanager
     def span(self, name: str, attributes: Optional[dict[str, Any]] = None):
@@ -129,27 +139,33 @@ class InstrumentationProvider(ABC):
             raise
         else:
             span.end("ok")
-    
+
     # Decorator for tracing functions
     def trace(self, name: Optional[str] = None, attributes: Optional[dict[str, Any]] = None):
         """Decorator to trace function execution."""
+
         def decorator(func: Callable):
             span_name = name or f"{func.__module__}.{func.__name__}"
-            
+
             if asyncio.iscoroutinefunction(func):
+
                 @functools.wraps(func)
                 async def async_wrapper(*args, **kwargs):
                     with self.span(span_name, attributes):
                         return await func(*args, **kwargs)
+
                 return async_wrapper
             else:
+
                 @functools.wraps(func)
                 def sync_wrapper(*args, **kwargs):
                     with self.span(span_name, attributes):
                         return func(*args, **kwargs)
+
                 return sync_wrapper
+
         return decorator
-    
+
     # Timing helpers
     @contextmanager
     def time_histogram(self, name: str, attributes: Optional[dict[str, Any]] = None):
@@ -161,22 +177,30 @@ class InstrumentationProvider(ABC):
         finally:
             duration = time.perf_counter() - start
             histogram.record(duration, attributes)
-    
-    def time_function(self, histogram_name: Optional[str] = None, attributes: Optional[dict[str, Any]] = None):
+
+    def time_function(
+        self, histogram_name: Optional[str] = None, attributes: Optional[dict[str, Any]] = None
+    ):
         """Decorator to time function execution."""
+
         def decorator(func: Callable):
             name = histogram_name or f"{func.__module__}.{func.__name__}.duration"
-            
+
             if asyncio.iscoroutinefunction(func):
+
                 @functools.wraps(func)
                 async def async_wrapper(*args, **kwargs):
                     with self.time_histogram(name, attributes):
                         return await func(*args, **kwargs)
+
                 return async_wrapper
             else:
+
                 @functools.wraps(func)
                 def sync_wrapper(*args, **kwargs):
                     with self.time_histogram(name, attributes):
                         return func(*args, **kwargs)
+
                 return sync_wrapper
-        return decorator
+
+        return decorator

pyview/instrumentation/noop.py

@@ -1,19 +1,20 @@
 """No-operation implementation of instrumentation interfaces."""
 
 from typing import Any, Optional
+
 from .interfaces import (
-    InstrumentationProvider,
     Counter,
-    UpDownCounter,
     Gauge,
     Histogram,
+    InstrumentationProvider,
     Span,
+    UpDownCounter,
 )
 
 
 class NoOpCounter(Counter):
     """No-op counter implementation."""
-    
+
     def add(self, value: float = 1, attributes: Optional[dict[str, Any]] = None) -> None:
         """No-op: does nothing."""
         pass
@@ -21,7 +22,7 @@ class NoOpCounter(Counter):
 
 class NoOpUpDownCounter(UpDownCounter):
     """No-op up/down counter implementation."""
-    
+
     def add(self, value: float, attributes: Optional[dict[str, Any]] = None) -> None:
         """No-op: does nothing."""
         pass
@@ -29,7 +30,7 @@ class NoOpUpDownCounter(UpDownCounter):
 
 class NoOpGauge(Gauge):
     """No-op gauge implementation."""
-    
+
     def set(self, value: float, attributes: Optional[dict[str, Any]] = None) -> None:
         """No-op: does nothing."""
         pass
@@ -37,7 +38,7 @@ class NoOpGauge(Gauge):
 
 class NoOpHistogram(Histogram):
     """No-op histogram implementation."""
-    
+
     def record(self, value: float, attributes: Optional[dict[str, Any]] = None) -> None:
         """No-op: does nothing."""
         pass
@@ -45,15 +46,15 @@ class NoOpHistogram(Histogram):
 
 class NoOpSpan(Span):
     """No-op span implementation."""
-    
+
     def set_attribute(self, key: str, value: Any) -> None:
         """No-op: does nothing."""
         pass
-    
+
     def add_event(self, name: str, attributes: Optional[dict[str, Any]] = None) -> None:
         """No-op: does nothing."""
         pass
-    
+
     def end(self, status: str = "ok") -> None:
         """No-op: does nothing."""
         pass
@@ -62,11 +63,11 @@ class NoOpSpan(Span):
 class NoOpInstrumentation(InstrumentationProvider):
     """
     Default no-operation instrumentation provider.
-    
+
     This implementation does nothing and has zero performance overhead.
     It's used as the default when no instrumentation is configured.
     """
-    
+
     def __init__(self):
         """Initialize the no-op provider."""
         # Cache single instances to avoid object creation overhead
@@ -75,23 +76,25 @@ class NoOpInstrumentation(InstrumentationProvider):
         self._gauge = NoOpGauge()
         self._histogram = NoOpHistogram()
         self._span = NoOpSpan()
-    
+
     def create_counter(self, name: str, description: str = "", unit: str = "") -> Counter:
         """Return a no-op counter."""
         return self._counter
-    
-    def create_updown_counter(self, name: str, description: str = "", unit: str = "") -> UpDownCounter:
+
+    def create_updown_counter(
+        self, name: str, description: str = "", unit: str = ""
+    ) -> UpDownCounter:
         """Return a no-op up/down counter."""
         return self._updown_counter
-    
+
     def create_gauge(self, name: str, description: str = "", unit: str = "") -> Gauge:
         """Return a no-op gauge."""
         return self._gauge
-    
+
     def create_histogram(self, name: str, description: str = "", unit: str = "") -> Histogram:
         """Return a no-op histogram."""
         return self._histogram
-    
+
     def start_span(self, name: str, attributes: Optional[dict[str, Any]] = None) -> Span:
         """Return a no-op span."""
-        return self._span
+        return self._span