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

pyview/binding/converters.py

@@ -0,0 +1,191 @@
+"""Type conversion for parameter binding."""
+
+import dataclasses
+import types
+from typing import Any, Union, get_args, get_origin, get_type_hints
+
+
+class ConversionError(Exception):
+    """Raised when type conversion fails."""
+
+    pass
+
+
+class ConverterRegistry:
+    """Handles type conversion from raw string values to typed parameters.
+
+    Supports:
+    - Primitives: int, float, str, bool
+    - Optional[T] and T | None: Returns None for missing/empty values
+    - Union[T1, T2, ...] and T1 | T2: Tries each variant in order
+    - Containers: list[T], set[T], tuple[T, ...]
+    """
+
+    def convert(self, raw: Any, expected: Any) -> Any:
+        """Convert raw value to expected type.
+
+        Args:
+            raw: Raw value (usually str or list[str] from params)
+            expected: Target type annotation
+
+        Returns:
+            Converted value
+
+        Raises:
+            ConversionError: If conversion fails
+        """
+        origin = get_origin(expected)
+        args = get_args(expected)
+
+        # Handle None/missing
+        if raw is None:
+            if self.is_optional(expected):
+                return None
+            raise ConversionError("Value is required")
+
+        # Handle Optional / Union (both typing.Union and types.UnionType for X | Y syntax)
+        if origin is Union or origin is types.UnionType:
+            return self._convert_union(raw, args)
+
+        # Handle list/set/tuple
+        if origin in (list, set, tuple):
+            return self._convert_container(raw, origin, args)
+
+        # Handle scalar primitives
+        if expected in (int, float, str, bool):
+            return self._convert_scalar(raw, expected)
+
+        # Handle dataclasses - construct from dict
+        if dataclasses.is_dataclass(expected) and isinstance(expected, type):
+            return self._convert_dataclass(raw, expected)
+
+        # Fallback: return as-is
+        return raw
+
+    def _convert_dataclass(self, raw: Any, expected: type) -> Any:
+        """Convert dict to dataclass instance."""
+        if not isinstance(raw, dict):
+            raise ConversionError(
+                f"Expected dict for dataclass {expected.__name__}, got {type(raw).__name__}"
+            )
+
+        # Get type hints, falling back to empty for missing annotations
+        # NameError: forward reference can't be resolved
+        # AttributeError: accessing annotations on some objects
+        # RecursionError: circular type references
+        try:
+            hints = get_type_hints(expected)
+        except (NameError, AttributeError, RecursionError):
+            hints = {}
+
+        fields = dataclasses.fields(expected)
+        kwargs: dict[str, Any] = {}
+
+        missing_fields: list[str] = []
+
+        for field in fields:
+            field_type = hints.get(field.name, Any)
+            if field.name in raw:
+                kwargs[field.name] = self.convert(raw[field.name], field_type)
+            elif field.default is not dataclasses.MISSING:
+                kwargs[field.name] = field.default
+            elif field.default_factory is not dataclasses.MISSING:
+                kwargs[field.name] = field.default_factory()
+            elif self.is_optional(field_type):
+                kwargs[field.name] = None
+            else:
+                missing_fields.append(field.name)
+
+        if missing_fields:
+            raise ConversionError(
+                f"Missing required fields for {expected.__name__}: {', '.join(missing_fields)}"
+            )
+
+        return expected(**kwargs)
+
+    def _convert_union(self, raw: Any, args: tuple[type, ...]) -> Any:
+        """Try each union variant in order."""
+        errors: list[str] = []
+        for variant in args:
+            if variant is type(None):
+                # Handle empty string as None for Optional
+                if raw == "" or raw == [""]:
+                    return None
+                continue
+            try:
+                return self.convert(raw, variant)
+            except (ConversionError, ValueError, TypeError) as e:
+                errors.append(str(e))
+        raise ConversionError(f"No union variant matched: {errors}")
+
+    def _convert_container(self, raw: Any, origin: type, args: tuple[type, ...]) -> Any:
+        """Convert to list/set/tuple.
+
+        Handles:
+        - list[T], set[T]: homogeneous containers
+        - tuple[T, ...]: homogeneous variable-length tuple
+        - tuple[T1, T2, T3]: heterogeneous fixed-length tuple
+        """
+        items = raw if isinstance(raw, list) else [raw]
+
+        if origin is tuple and args:
+            # Check for homogeneous tuple: tuple[T, ...] has Ellipsis as second arg
+            if len(args) == 2 and args[1] is ...:
+                inner = args[0]
+                converted = [self.convert(v, inner) for v in items]
+            else:
+                # Heterogeneous tuple: tuple[T1, T2, T3]
+                if len(items) != len(args):
+                    raise ConversionError(
+                        f"Expected {len(args)} values for tuple, got {len(items)}"
+                    )
+                converted = [
+                    self.convert(item, arg_type) for item, arg_type in zip(items, args, strict=True)
+                ]
+            return tuple(converted)
+
+        # list[T] or set[T]: homogeneous
+        inner = args[0] if args else str
+        converted = [self.convert(v, inner) for v in items]
+
+        if origin is list:
+            return converted
+        if origin is set:
+            return set(converted)
+        return tuple(converted)
+
+    def _convert_scalar(self, raw: Any, expected: type) -> Any:
+        """Convert to scalar type, picking first if input is a list."""
+        # Normalize: if list, take first element
+        if isinstance(raw, list):
+            if not raw:
+                raise ConversionError("Empty list for scalar type")
+            raw = raw[0]
+
+        if expected is bool:
+            return self._convert_bool(raw)
+
+        try:
+            return expected(raw)
+        except (ValueError, TypeError) as e:
+            raise ConversionError(f"Cannot convert {raw!r} to {expected.__name__}: {e}") from e
+
+    def _convert_bool(self, raw: Any) -> bool:
+        """Convert to boolean with common string values."""
+        if isinstance(raw, bool):
+            return raw
+        if isinstance(raw, (int, float)):
+            return bool(raw)
+        s = str(raw).lower().strip()
+        if s in ("true", "1", "yes", "on"):
+            return True
+        if s in ("false", "0", "no", "off", ""):
+            return False
+        raise ConversionError(f"Cannot convert {raw!r} to bool")
+
+    def is_optional(self, expected: Any) -> bool:
+        """Check if type is Optional[T] (Union[T, None] or T | None)."""
+        origin = get_origin(expected)
+        if origin is Union or origin is types.UnionType:
+            return type(None) in get_args(expected)
+        return False

pyview/binding/helpers.py

@@ -0,0 +1,78 @@
+"""Helper functions for runtime integration."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+from urllib.parse import ParseResult
+
+from .binder import Binder
+from .context import BindContext
+from .params import Params
+
+if TYPE_CHECKING:
+    from pyview.live_socket import LiveViewSocket
+
+logger = logging.getLogger(__name__)
+
+
+async def call_handle_params(
+    lv, url: ParseResult, params: dict[str, list[str]], socket: LiveViewSocket
+):
+    """Bind params and call handle_params with signature-matched args.
+
+    Args:
+        lv: The LiveView instance
+        url: Parsed URL
+        params: Raw dict[str, list[str]] from parse_qs
+        socket: The socket instance
+
+    Returns:
+        Result of lv.handle_params()
+    """
+    ctx = BindContext(
+        params=Params(params),
+        payload=None,
+        url=url,
+        socket=socket,
+        event=None,
+    )
+    binder = Binder()
+    result = binder.bind(lv.handle_params, ctx)
+
+    if not result.success:
+        for err in result.errors:
+            logger.warning(f"Param binding error: {err}")
+        raise ValueError(f"Parameter binding failed: {result.errors}")
+
+    return await lv.handle_params(**result.bound_args)
+
+
+async def call_handle_event(lv, event: str, payload: dict, socket: LiveViewSocket):
+    """Bind event payload and call handle_event with signature-matched args.
+
+    Args:
+        lv: The LiveView instance
+        event: Event name (e.g., "increment", "submit")
+        payload: Event payload dict
+        socket: The socket instance
+
+    Returns:
+        Result of lv.handle_event()
+    """
+    ctx = BindContext(
+        params=Params({}),
+        payload=payload,
+        url=None,
+        socket=socket,
+        event=event,
+    )
+    binder = Binder()
+    result = binder.bind(lv.handle_event, ctx)
+
+    if not result.success:
+        for err in result.errors:
+            logger.warning(f"Event binding error: {err}")
+        raise ValueError(f"Event binding failed: {result.errors}")
+
+    return await lv.handle_event(**result.bound_args)

pyview/binding/injectables.py

@@ -0,0 +1,119 @@
+"""Injectable parameter resolution for special runtime objects."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Generic, TypeVar, get_args, get_origin
+
+from .converters import ConverterRegistry
+from .params import Params
+
+if TYPE_CHECKING:
+    from .context import BindContext
+
+# Sentinel to distinguish "not resolvable" from "resolved to None"
+_NOT_FOUND = object()
+
+T = TypeVar("T")
+
+
+class InjectableRegistry(Generic[T]):
+    """Resolves special injectable parameters by name or type.
+
+    Injectables are parameters that come from the runtime context rather than
+    from user-provided params/payload. Examples: socket, event, payload, url, params.
+    """
+
+    def resolve(
+        self,
+        name: str,
+        annotation: Any,
+        ctx: BindContext[T],
+    ) -> Any | None:
+        """Try to resolve a parameter from injectables.
+
+        Args:
+            name: Parameter name
+            annotation: Parameter type annotation
+            ctx: Binding context with available values
+
+        Returns:
+            The injectable value, or None if not resolvable
+        """
+        # Name-based injection
+        if name == "socket":
+            return ctx.socket
+        if name == "event":
+            return ctx.event
+        if name == "payload":
+            return ctx.payload
+        if name == "url":
+            return ctx.url
+        if name == "params":
+            # Only inject if typed as Params, dict, or untyped (Any)
+            # Otherwise treat "params" as a regular URL param name
+            if self._is_params_annotation(annotation):
+                return self._resolve_params(annotation, ctx)
+            return _NOT_FOUND
+
+        # Check extra injectables
+        if name in ctx.extra:
+            return ctx.extra[name]
+
+        return _NOT_FOUND
+
+    def _is_params_annotation(self, annotation: Any) -> bool:
+        """Check if annotation indicates params injection vs URL param named 'params'."""
+        # Untyped (Any) -> inject for backward compat
+        if annotation is Any:
+            return True
+        # Explicit Params type
+        if annotation is Params:
+            return True
+        # dict or dict[...] -> inject
+        return annotation is dict or get_origin(annotation) is dict
+
+    def _resolve_params(self, annotation: Any, ctx: BindContext[T]) -> Any:
+        """Resolve params parameter based on annotation type."""
+        origin = get_origin(annotation)
+        args = get_args(annotation)
+
+        # params: Params -> return wrapper
+        if annotation is Params:
+            return ctx.params
+
+        # Handle dict annotations
+        if annotation is dict or origin is dict:
+            # params: dict[str, list[str]] -> return raw
+            if args == (str, list[str]):
+                return ctx.params.raw()
+
+            # params: dict[str, Any] -> flatten
+            if len(args) == 2 and args[0] is str:
+                if args[1] is Any:
+                    return ctx.params.to_flat_dict()
+
+                # params: dict[str, T] -> convert values
+                value_type = args[1]
+                return self._convert_dict_values(ctx.params, value_type)
+
+            # Bare dict or dict[str, list[str]] default
+            if not args:
+                return ctx.params.to_flat_dict()
+
+        # Default: return Params wrapper
+        return ctx.params
+
+    def _convert_dict_values(
+        self,
+        params: Params,
+        value_type: type,
+    ) -> dict[str, Any]:
+        """Convert all param values to specified type."""
+        converter = ConverterRegistry()
+        result: dict[str, Any] = {}
+
+        for key in params:
+            raw = params.getlist(key)
+            result[key] = converter.convert(raw, value_type)
+
+        return result

pyview/binding/params.py

@@ -0,0 +1,105 @@
+"""Multi-value parameter container for query/path/form params."""
+
+from typing import Any, Iterator, Optional
+
+
+def _as_list(value: Any) -> list[str]:
+    """Convert a value to list[str].
+
+    Handles mixed sources:
+    - Query params from parse_qs() are already list[str]
+    - Path params from Starlette are single values (str or int)
+    """
+    if isinstance(value, list):
+        return value
+    elif value is not None:
+        return [str(value)]
+    else:
+        return []
+
+
+class Params:
+    """Multi-value parameter container for query/path/form params.
+
+    This provides a convenient interface for accessing parameters that may have
+    multiple values (e.g., from query strings like ?tag=a&tag=b).
+
+    Handles mixed value types:
+    - Query params from parse_qs(): list[str]
+    - Path params from Starlette: str or int
+    """
+
+    def __init__(self, data: dict[str, Any]) -> None:
+        self._data = data
+
+    def get(self, key: str, default: Optional[str] = None) -> Optional[str]:
+        """Get first value for key, or default if missing."""
+        values = _as_list(self._data.get(key))
+        return values[0] if values else default
+
+    def getlist(self, key: str) -> list[str]:
+        """Get all values for key as a list."""
+        return _as_list(self._data.get(key))
+
+    def getone(self, key: str) -> str:
+        """Get exactly one value for key.
+
+        Raises:
+            KeyError: If key is missing or has multiple values.
+        """
+        values = _as_list(self._data.get(key))
+        if len(values) != 1:
+            raise KeyError(f"Expected exactly one value for '{key}', got {len(values)}")
+        return values[0]
+
+    def has(self, key: str) -> bool:
+        """Check if key exists."""
+        return key in self._data
+
+    def keys(self) -> list[str]:
+        """Return all keys."""
+        return list(self._data.keys())
+
+    def items(self) -> Iterator[tuple[str, str]]:
+        """Iterate over (key, value) pairs (first value only for each key)."""
+        for k, v in self._data.items():
+            values = _as_list(v)
+            if values:
+                yield k, values[0]
+
+    def multi_items(self) -> Iterator[tuple[str, str]]:
+        """Iterate over all (key, value) pairs including multi-values."""
+        for k, v in self._data.items():
+            for val in _as_list(v):
+                yield k, val
+
+    def raw(self) -> dict[str, Any]:
+        """Return the underlying dict (may contain mixed value types)."""
+        return self._data
+
+    def to_flat_dict(self) -> dict[str, Any]:
+        """Convert to flat dict.
+
+        Single values become scalars, multiple values remain as lists.
+        """
+        result: dict[str, Any] = {}
+        for k, v in self._data.items():
+            values = _as_list(v)
+            result[k] = values[0] if len(values) == 1 else values
+        return result
+
+    def __contains__(self, key: str) -> bool:
+        return key in self._data
+
+    def __getitem__(self, key: str) -> Any:
+        """Get raw value for key (returns original type from underlying dict)."""
+        return self._data[key]
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._data)
+
+    def __len__(self) -> int:
+        return len(self._data)
+
+    def __repr__(self) -> str:
+        return f"Params({self._data!r})"

pyview/binding/result.py

@@ -0,0 +1,32 @@
+"""Result types for parameter binding."""
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class ParamError:
+    """Describes a parameter binding error."""
+
+    name: str
+    expected: str
+    value: Any
+    reason: str
+
+    def __str__(self) -> str:
+        return (
+            f"Parameter '{self.name}': {self.reason} (expected {self.expected}, got {self.value!r})"
+        )
+
+
+@dataclass
+class BindResult:
+    """Result of binding parameters to a function signature."""
+
+    bound_args: dict[str, Any]
+    errors: list[ParamError]
+
+    @property
+    def success(self) -> bool:
+        """True if binding completed without errors."""
+        return len(self.errors) == 0

pyview/changesets/__init__.py

@@ -1 +1,3 @@
 from .changesets import ChangeSet, change_set
+
+__all__ = ["ChangeSet", "change_set"]

pyview/changesets/changesets.py

@@ -1,7 +1,8 @@
-from typing import TypeVar, Any, Generic, Optional
-from pydantic import BaseModel, ValidationError
 from dataclasses import dataclass
 from types import SimpleNamespace
+from typing import Any, Generic, Optional, TypeVar
+
+from pydantic import BaseModel, ValidationError
 
 Base = TypeVar("Base", bound=BaseModel)
 
@@ -52,7 +53,11 @@ class ChangeSet(Generic[Base]):
             self.valid = True
         except ValidationError as e:
             for error in e.errors():
-                loc = str(error["loc"][0])
+                # Model-level validators have empty loc tuple - show on current field
+                if not error["loc"]:
+                    loc = k
+                else:
+                    loc = str(error["loc"][0])
                 if loc in self.changes:
                     self.errors[loc] = error["msg"]
             self.valid = False

pyview/cli/commands/create_view.py

@@ -1,8 +1,9 @@
-import click
-from pathlib import Path
 import tomllib
+from pathlib import Path
 from typing import Optional
 
+import click
+
 
 def snake_case(name: str) -> str:
     """Convert PascalCase or camelCase to snake_case."""
@@ -50,7 +51,7 @@ def generate_html_file(name: str) -> str:
     css_class = kebab_case(name)
     return f'''<div class="{css_class}-container">
     <h1>{pascal_case(name)}</h1>
-    
+
     <div class="content">
         <!-- Add your content here -->
     </div>

pyview/cli/main.py

@@ -14,4 +14,4 @@ cli.add_command(create_view)
 
 
 if __name__ == "__main__":
-    cli()
+    cli()

pyview/components/__init__.py

@@ -0,0 +1,72 @@
+"""
+PyView Components - Phoenix-style LiveComponents for Python.
+
+This module provides stateful, reusable components that can:
+- Maintain their own state (context)
+- Handle their own events via phx-target
+- Have lifecycle hooks (mount, update)
+
+Usage:
+    from pyview.components import LiveComponent, ComponentMeta, live_component
+
+    class Counter(LiveComponent[CounterContext]):
+        async def mount(self, socket):
+            socket.context = {"count": 0}
+
+        def template(self, assigns, meta):
+            return t'''
+                <div>
+                    Count: {assigns["count"]}
+                    <button phx-click="increment" phx-target="{meta.myself}">+</button>
+                </div>
+            '''
+
+        async def handle_event(self, event, payload, socket):
+            if event == "increment":
+                socket.context["count"] += 1
+
+    # In parent LiveView template:
+    {live_component(Counter, id="counter-1")}
+"""
+
+from typing import Any, Protocol
+
+from .base import ComponentMeta, ComponentSocket, LiveComponent
+from .manager import ComponentsManager
+from .slots import Slots, slots
+
+
+class ComponentsManagerProtocol(Protocol):
+    """Protocol for component manager used in text() rendering."""
+
+    def render_component(self, cid: int, parent_meta: Any) -> Any: ...
+
+    def has_pending_lifecycle(self) -> bool: ...
+
+    def get_all_cids(self) -> list[int]: ...
+
+    def get_seen_cids(self) -> set[int]: ...
+
+    async def run_pending_lifecycle(self) -> None: ...
+
+    @property
+    def component_count(self) -> int: ...
+
+
+class SocketWithComponents(Protocol):
+    """Protocol for socket with components manager (for template rendering)."""
+
+    @property
+    def components(self) -> ComponentsManagerProtocol: ...
+
+
+__all__ = [
+    "LiveComponent",
+    "ComponentMeta",
+    "ComponentSocket",
+    "ComponentsManager",
+    "ComponentsManagerProtocol",
+    "SocketWithComponents",
+    "Slots",
+    "slots",
+]