pywire 0.1.1__py3-none-any.whl → 0.1.2__py3-none-any.whl

pywire/runtime/page.py

@@ -0,0 +1,384 @@
+"""Base page class with lifecycle system."""
+
+import inspect
+from collections import defaultdict
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Awaitable,
+    Callable,
+    ClassVar,
+    Dict,
+    List,
+    Optional,
+    Set,
+    Tuple,
+    Union,
+)
+
+from starlette.requests import Request
+from starlette.responses import Response
+
+if TYPE_CHECKING:
+    from pywire.runtime.router import URLHelper
+
+from pywire.runtime.style_collector import StyleCollector
+
+
+class EventData(dict):
+    """Dict that allows dot-access to keys for Alpine.js compatibility."""
+
+    def __getattr__(self, name: str) -> Any:
+        try:
+            return self[name]
+        except KeyError:
+            # Check for camelCase version of name
+            import re
+
+            camel = re.sub(r"(?!^)_([a-z])", lambda x: x.group(1).upper(), name)
+            if camel in self:
+                return self[camel]
+            raise AttributeError(f"'EventData' object has no attribute '{name}'")
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        self[name] = value
+
+
+class BasePage:
+    """Base class for all compiled pages."""
+
+    # Layout ID (overridden by generator)
+    LAYOUT_ID: Optional[str] = None
+    __file_path__: ClassVar[str]
+
+    # Lifecycle hooks registry (extensible!)
+    INIT_HOOKS = [
+        "on_before_load",
+        "on_load",
+    ]
+
+    RENDER_HOOKS = [
+        "on_after_render",
+    ]
+
+    # Legacy support / full list
+    LIFECYCLE_HOOKS = INIT_HOOKS + RENDER_HOOKS
+
+    def __init__(
+        self,
+        request: Request,
+        params: Dict[str, str],
+        query: Dict[str, str],
+        path: Optional[Dict[str, bool]] = None,
+        url: Optional["URLHelper"] = None,
+        **kwargs: Any,
+    ) -> None:
+        self.request = request
+        self.params = params or {}  # URL params from route
+        self.query = query or {}  # Query string params
+        self.path = path or {}
+        self.url = url
+
+        # Style collector management
+        # If passed from parent component (via kwargs), reuse it.
+        # Otherwise create new one (root page).
+        if "_style_collector" in kwargs:
+            self._style_collector: StyleCollector = kwargs.pop("_style_collector")
+        else:
+            self._style_collector = StyleCollector()
+
+        # Context inheritance for !provide/!inject
+        # If passed from parent component, make a shallow copy for child-specific shadowing.
+        # Otherwise create a new empty context (root page).
+        if "_context" in kwargs:
+            self.context = kwargs.pop("_context").copy()
+        else:
+            self.context = {}
+        self.context: Dict[str, Any]  # type: ignore
+
+        self.user: Any = None  # Set by middleware
+
+        # Expose params as attributes for easy access in templates
+        for k, v in self.params.items():
+            setattr(self, k, v)
+
+        # Framework-managed state
+        self.errors: Dict[str, str] = {}
+        self.loading: Dict[str, bool] = {}
+
+        # Slot registry: layout_id -> slot_name -> renderer (replacement semantics)
+        self.slots: Dict[str, Dict[str, Union[Callable, str]]] = defaultdict(dict)
+
+        # Populate slots from kwargs (for components)
+        if "slots" in kwargs and self.LAYOUT_ID:
+            self.slots[self.LAYOUT_ID].update(kwargs["slots"])
+
+        # Component flag (internal)
+        self.__is_component__ = kwargs.pop("__is_component__", False)
+
+        # Store remaining kwargs as fallthrough attributes
+        self.attrs = {k: v for k, v in kwargs.items() if k != "slots"}
+
+        # Head slot registry: layout_id -> list of renderers (append semantics, top-down order)
+        self.head_slots: Dict[str, List[Callable]] = defaultdict(list)
+
+        # Async update hook for intermediate state (injected by runtime)
+        self._on_update: Optional[Callable[[], Awaitable[None]]] = None
+        self._wire_subscribers: Dict[Tuple[Any, str], Set[str]] = defaultdict(set)
+        self._region_dependencies: Dict[str, Set[Tuple[Any, str]]] = defaultdict(set)
+        self._dirty_regions: Set[str] = set()
+
+        # Error state for error pages
+        self.error_code: Optional[int] = None
+        self.error_detail: Optional[str] = None
+        self.error_trace: Optional[str] = None
+
+    def register_slot(
+        self, layout_id: str, slot_name: str, renderer: Callable[..., Any]
+    ) -> None:
+        """Register a content renderer for a slot in a specific layout."""
+        self.slots[layout_id][slot_name] = renderer
+
+    def register_head_slot(self, layout_id: str, renderer: Callable[..., Any]) -> None:
+        """Register head content to be appended (top-down order)."""
+        # Prevent duplicate registration (can happen with super()._init_slots() chaining)
+        if renderer not in self.head_slots[layout_id]:
+            self.head_slots[layout_id].append(renderer)
+
+    async def render_slot(
+        self,
+        slot_name: str,
+        default_renderer: Optional[Callable[..., Any]] = None,
+        layout_id: Optional[str] = None,
+        append: bool = False,
+    ) -> str:
+        """Render a slot for the current layout."""
+        target_id = layout_id or self.LAYOUT_ID
+
+        # Handle $head slots with append semantics
+        if append:
+            parts = []
+            # Render default content first (from the layout itself)
+            if default_renderer:
+                if inspect.iscoroutinefunction(default_renderer):
+                    parts.append(await default_renderer())
+                else:
+                    parts.append(default_renderer())
+
+            # Collect head content from ALL layout IDs in the inheritance chain
+            for layout_id_key in self.head_slots:
+                for head_renderer in self.head_slots[layout_id_key]:
+                    if inspect.iscoroutinefunction(head_renderer):
+                        parts.append(await head_renderer())
+                    else:
+                        parts.append(head_renderer())
+            return "".join(parts)
+
+        # Normal replacement semantics
+        if target_id and slot_name in self.slots[target_id]:
+            renderer: Union[Callable[..., Any], str] = self.slots[target_id][slot_name]
+            if callable(renderer):
+                if inspect.iscoroutinefunction(renderer):
+                    return str(await renderer())
+                return str(renderer())
+            return str(renderer)
+
+        # Fallback to default content if provided
+        if default_renderer:
+            if inspect.iscoroutinefunction(default_renderer):
+                return str(await default_renderer())
+            return str(default_renderer())
+
+        return ""
+
+    async def render(self, init: bool = True) -> Response:
+        """Main render method - calls lifecycle hooks."""
+        # Run init hooks only if requested (new page load)
+        if init:
+            for hook_name in self.INIT_HOOKS:
+                if hasattr(self, hook_name):
+                    hook = getattr(self, hook_name)
+                    if inspect.iscoroutinefunction(hook):
+                        await hook()
+                    else:
+                        hook()
+
+        # Render template (may be async for layouts with render_slot calls)
+        # Render HTML
+        self._clear_wire_tracking()
+        html = await self._render_template()
+
+        # Inject styles if this is the root render (not a component or partial update)
+        # Actually, BasePage.render() is called for the ROOT page response.
+        # Components use _render_template directly.
+        # So here we can inject the styles into <head>.
+
+        styles = self._style_collector.render()
+        if styles:
+            # Inject into head
+            if "</head>" in html:
+                html = html.replace("</head>", f"{styles}</head>", 1)
+            else:
+                # Fallback: prepend to body or just prepend
+                html = f"{styles}{html}"
+
+        # Run post-render hooks (always run on render)
+        for hook_name in self.RENDER_HOOKS:
+            if hasattr(self, hook_name):
+                hook = getattr(self, hook_name)
+                if inspect.iscoroutinefunction(hook):
+                    await hook()
+                else:
+                    hook()
+
+        return Response(html, media_type="text/html")
+
+    def _clear_wire_tracking(self) -> None:
+        self._wire_subscribers.clear()
+        self._region_dependencies.clear()
+        self._dirty_regions.clear()
+
+    def _begin_region_render(self, region_id: str) -> None:
+        deps = self._region_dependencies.get(region_id)
+        if deps:
+            for dep in deps:
+                regions = self._wire_subscribers.get(dep)
+                if regions and region_id in regions:
+                    regions.discard(region_id)
+                    if not regions:
+                        self._wire_subscribers.pop(dep, None)
+        self._region_dependencies[region_id] = set()
+
+    def _register_wire_read(self, wire_obj: Any, field: str, region_id: str) -> None:
+        key = (wire_obj, field)
+        self._wire_subscribers[key].add(region_id)
+        self._region_dependencies[region_id].add(key)
+
+    def _invalidate_wire(self, wire_obj: Any, field: str) -> None:
+        regions = set()
+        key = (wire_obj, field)
+        if key in self._wire_subscribers:
+            regions |= self._wire_subscribers[key]
+        if regions:
+            self._dirty_regions.update(regions)
+
+    async def handle_event(
+        self, event_name: str, event_data: dict[str, Any]
+    ) -> Dict[str, Any]:
+        """Handle client event (from @click, etc.)."""
+
+        # Security: Validate handler is allowed (prevents arbitrary method invocation)
+        allowed = getattr(self, "__allowed_handlers__", None)
+
+        # Framework-generated handlers are always allowed (form wrappers, bindings)
+        is_framework_handler = (
+            event_name.startswith("_handle_bind_")
+            or event_name.startswith("_handler_")
+            or event_name.startswith("_form_submit_")
+        )
+
+        if not is_framework_handler:
+            # Block private methods (leading underscore) unless in allowlist
+            if event_name.startswith("_"):
+                raise ValueError(f"Handler '{event_name}' not allowed")
+
+            # Check explicit allowlist if defined
+            if allowed is not None and event_name not in allowed:
+                raise ValueError(f"Handler '{event_name}' not allowed")
+
+        # Retrieve handler
+        handler = getattr(self, event_name, None)
+        if not handler:
+            raise ValueError(f"Handler {event_name} not found")
+
+        # Call handler
+        if event_name.startswith("_handle_bind_"):
+            # Binding handlers expect raw event_data
+            if inspect.iscoroutinefunction(handler):
+                await handler(event_data)
+            else:
+                handler(event_data)
+        else:
+            # Regular handlers: intelligent argument mapping
+            args = event_data.get("args", {})
+
+            # Normalize args keys (arg-0 -> arg0) because dataset keys preserve hyphens
+            # before digits
+            normalized_args = {}
+            for k, v in args.items():
+                if k.startswith("arg"):
+                    normalized_args[k.replace("-", "")] = v
+                else:
+                    normalized_args[k] = v
+
+            call_kwargs = {k: v for k, v in event_data.items() if k != "args"}
+            call_kwargs.update(normalized_args)
+
+            # Check signature to see what arguments the handler accepts
+            sig = inspect.signature(handler)
+            bound_kwargs = {}
+
+            has_var_kw = False
+            for param in sig.parameters.values():
+                if param.kind == inspect.Parameter.VAR_KEYWORD:
+                    has_var_kw = True
+                    break
+
+            if has_var_kw:
+                # If accepts **kwargs, pass everything
+                bound_kwargs = call_kwargs
+            else:
+                # Only pass arguments that match parameters
+                for name in sig.parameters:
+                    if name == "event_data" or name == "event":
+                        bound_kwargs[name] = EventData(call_kwargs)
+                    elif name in call_kwargs:
+                        bound_kwargs[name] = call_kwargs[name]
+
+            try:
+                if inspect.iscoroutinefunction(handler):
+                    await handler(**bound_kwargs)
+                else:
+                    handler(**bound_kwargs)
+            except Exception as e:
+                # Let the runtime handle logging and reporting
+                raise e
+
+        # Re-render without re-initializing
+        return await self.render_update(init=False)
+
+    async def render_update(self, init: bool = False) -> Dict[str, Any]:
+        if hasattr(self, "__region_renderers__") and self._dirty_regions:
+            updates = []
+            region_map = getattr(self, "__region_renderers__", {}) or {}
+            for region_id in sorted(self._dirty_regions):
+                method_name = region_map.get(region_id)
+                if not method_name:
+                    continue
+                renderer = getattr(self, method_name, None)
+                if not renderer:
+                    continue
+                if inspect.iscoroutinefunction(renderer):
+                    region_html = await renderer()
+                else:
+                    region_html = renderer()
+                updates.append({"region": region_id, "html": region_html})
+            self._dirty_regions.clear()
+            if updates:
+                return {"type": "regions", "regions": updates}
+
+        response = await self.render(init=init)
+        html = bytes(response.body).decode("utf-8")
+        return {"type": "full", "html": html}
+
+    async def push_state(self) -> None:
+        """Force a UI update with current state (useful for streaming progress)."""
+        if self._on_update:
+            if inspect.iscoroutinefunction(self._on_update):
+                await self._on_update()
+            else:
+                self._on_update()
+
+    async def _render_template(self) -> str:
+        """Render template - implemented by codegen."""
+        return ""

pywire/runtime/pydantic_integration.py

@@ -0,0 +1,52 @@
+from typing import Any, Dict, Optional, Tuple, Type
+
+from pydantic import BaseModel, ValidationError
+
+
+def validate_with_model(
+    data: Dict[str, Any], model_class: Type[BaseModel]
+) -> Tuple[Optional[BaseModel], Dict[str, str]]:
+    """
+    Attempt to instantiate and validate a Pydantic model.
+
+    Args:
+        data: The input dictionary (already type-converted by FormValidator if possible,
+              but Pydantic handles its own conversion too).
+        model_class: The Pydantic model class to validate against.
+
+    Returns:
+        (model_instance, {}) on success.
+        (None, {field_name: error_message}) on validation failure.
+    """
+    try:
+        # Pydantic v2 use model_validate, v1 use parse_obj.
+        # Let's support v2 primarily, but fallback if needed.
+        if hasattr(model_class, "model_validate"):
+            instance = model_class.model_validate(data)
+        else:
+            instance = model_class.parse_obj(data)
+
+        return instance, {}
+
+    except ValidationError as e:
+        errors = {}
+        for err in e.errors():
+            # Extract field name. 'loc' is a tuple like ('field',).
+            # Nested fields might be ('parent', 'child').
+            # We want to map this back to dotted string for errors dict.
+            loc = err.get("loc", ())
+            field_name = ".".join(str(part) for part in loc)
+
+            # Simple error message
+            msg = err.get("msg", "Invalid value")
+
+            # Remove Pydantic's "Value error, " prefix if present
+            if msg.startswith("Value error, "):
+                msg = msg[len("Value error, ") :]
+
+            errors[field_name] = msg
+
+        return None, errors
+    except Exception as e:
+        # Unexpected error during validation
+        return None, {"__all__": str(e)}

pywire/runtime/router.py

@@ -0,0 +1,229 @@
+"""Routing system."""
+
+import re
+from typing import Any, Dict, Optional, Tuple, Type
+
+from pywire.runtime.page import BasePage
+
+
+class Route:
+    """Represents a single route pattern."""
+
+    def __init__(
+        self, pattern: str, page_class: Type[BasePage], name: Optional[str]
+    ) -> None:
+        self.pattern = pattern
+        self.page_class = page_class
+        self.name = name
+
+        # Compile pattern to regex
+        self.regex = self._compile_pattern(pattern)
+
+    def _compile_pattern(self, pattern: str) -> re.Pattern:
+        """Convert '/projects/:id:int' to regex."""
+        if pattern == "/":
+            return re.compile(r"^/$")
+
+        # 1. Normalize :param syntax to {param} for internal processing if needed,
+        #    or just process directly. Let's process :param directly.
+        #    Supported format: :name or :name:type or {name} or {name:type}
+
+        # We need to handle both :param and {param} syntax
+        # Let's standardize on one before regex gen or handle both in regex replacement
+
+        # Replace placeholders with regex groups
+        # We look for two patterns:
+        # 1. :name(:type)?
+        # 2. \{name(:type)?\}
+
+        # Helper to generate regex for a type
+        def get_type_regex(type_name: str) -> str:
+            if type_name == "int":
+                return r"\d+"
+            elif type_name == "str":
+                return r"[^/]+"
+            # Default to string
+            return r"[^/]+"
+
+        # This logic is a bit complex for a single regex replace.
+        # Let's manually parse/split the string or use a strict regex.
+
+        # Let's use a tokenizing approach for robustness,
+        # or a series of regex replacements that don't conflict.
+
+        # Tokenizing approach for robustness
+        # 1. Split by '/'
+        # 2. Process segments
+        # 3. Join
+
+        parts = pattern.split("/")
+        regex_parts = []
+
+        for part in parts:
+            if not part:
+                # Empty part (e.g. start of string)
+                continue
+
+            # Check for :param
+            if part.startswith(":"):
+                # :id or :id:int
+                content = part[1:]
+                if ":" in content:
+                    name, type_name = content.split(":", 1)
+                else:
+                    name, type_name = content, "str"
+
+                regex = get_type_regex(type_name)
+                regex_parts.append(f"(?P<{name}>{regex})")
+
+            # Check for {param}
+            elif part.startswith("{") and part.endswith("}"):
+                content = part[1:-1]
+                if ":" in content:
+                    name, type_name = content.split(":", 1)
+                else:
+                    name, type_name = content, "str"
+
+                regex = get_type_regex(type_name)
+                regex_parts.append(f"(?P<{name}>{regex})")
+
+            else:
+                # Literal
+                regex_parts.append(re.escape(part))
+
+        regex_str = "^/" + "/".join(regex_parts) + "$"
+        return re.compile(regex_str)
+
+    def match(self, path: str) -> Optional[dict[str, str]]:
+        """Try to match path, return params if successful."""
+        match = self.regex.match(path)
+        if match:
+            # We need to convert types!
+            params = match.groupdict()
+            # Since we baked types into regex (e.g. \d+), we know they match format.
+            # But we should cast them to Python types.
+
+            # For this MVP, we might just return strings,
+            # BUT the user asked for ":id:int matches /test/2", which implies type checking
+            # Match only digits. The generated params dict currently contains strings.
+            # We should probably convert them if we have the type info available.
+
+            # Re-parsing pattern to get types is inefficient.
+            # Let's assume for now they want the matching behavior.
+            # BasePage expects params: Dict[str, str].
+            # If we change that, we break compatibility or need to update BasePage.
+            # User requirement: "params['id'] is guaranteed to be populated".
+            # Doesn't explicitly demand it be an int object, but ":int" suggests validation.
+            # Given dynamic nature, let's keep as strings in params for now to
+            # satisfy Dict[str, str] hint, or update hint in BasePage.
+
+            return params
+        return None
+
+
+class URLHelper:
+    """Helper to generate URLs."""
+
+    def __init__(self, routes: Dict[str, str]) -> None:
+        self.routes = routes
+
+    def __getitem__(self, key: str) -> "URLTemplate":
+        if key not in self.routes:
+            raise KeyError(f"Route variant '{key}' not found")
+        return URLTemplate(self.routes[key])
+
+    def __str__(self) -> str:
+        # Return dict with normalized patterns
+        import re
+
+        def normalize_pattern(pattern: str) -> str:
+            def replace_param(match: re.Match) -> str:
+                return f"{{{match.group(1)}}}"
+
+            cleaned = re.sub(r":(\w+)(:\w+)?", replace_param, pattern)
+            cleaned = re.sub(r"\{(\w+)(:\w+)?\}", replace_param, cleaned)
+            return cleaned
+
+        normalized = {k: normalize_pattern(v) for k, v in self.routes.items()}
+        return str(normalized)
+
+
+class URLTemplate:
+    """Wraps a route pattern to allow .format()."""
+
+    def __init__(self, pattern: str) -> None:
+        self.pattern = pattern
+
+    def format(self, **kwargs: Any) -> str:
+        url = self.pattern
+        # Simple replacement for now.
+        # Needs to handle :param syntax conversion to {param} for format,
+        # or custom formatter.
+
+        # Regex to find params in pattern:
+        # 1. {name:type} or {name}
+        # 2. :name:type or :name
+        # Note: We must be careful not to match the :type part of {name:type} as a :name.
+        # We can do this by matching the more specific {name:type} first in an OR,
+        # or by using a single regex for both.
+
+        pattern = r"\{(\w+)(?::\w+)?\}|:(\w+)(?::\w+)?"
+
+        def replace_match(match: re.Match) -> str:
+            # Group 1 is from {}, Group 2 is from :
+            name = match.group(1) or match.group(2)
+            return f"{{{name}}}"
+
+        return re.sub(pattern, replace_match, url).format(**kwargs)
+
+    def __str__(self) -> str:
+        # Return normalized pattern with {param} instead of :param
+        pattern = r"\{(\w+)(?::\w+)?\}|:(\w+)(?::\w+)?"
+
+        def replace_match(match: re.Match) -> str:
+            name = match.group(1) or match.group(2)
+            return f"{{{name}}}"
+
+        return re.sub(pattern, replace_match, self.pattern)
+
+
+class Router:
+    """Routes requests to page classes based on !path directives."""
+
+    def __init__(self) -> None:
+        self.routes: list[Route] = []
+
+    def add_route(
+        self, pattern: str, page_class: Type[BasePage], name: Optional[str] = None
+    ) -> None:
+        """Add route from compiled page."""
+        self.routes.append(Route(pattern, page_class, name))
+
+    def add_page(self, page_class: Type[BasePage]) -> None:
+        """Register all routes for a page class."""
+        if hasattr(page_class, "__routes__"):
+            for name, pattern in page_class.__routes__.items():
+                self.add_route(pattern, page_class, name)
+        elif hasattr(page_class, "__route__"):
+            self.add_route(page_class.__route__, page_class)
+
+    def match(
+        self, path: str
+    ) -> Optional[Tuple[Type[BasePage], dict[str, str], Optional[str]]]:
+        """Match URL path to page class. Returns: (PageClass, params, variant_name)."""
+        for route in self.routes:
+            params = route.match(path)
+            if params is not None:
+                return (route.page_class, params, route.name)
+        return None
+
+    def remove_routes_for_file(self, file_path: str) -> None:
+        """Remove all routes associated with a file path."""
+        # Normalize file path for comparison
+        file_path = str(file_path)
+
+        self.routes = [
+            r
+            for r in self.routes
+            if getattr(r.page_class, "__file_path__", "") != file_path
+        ]

pywire/runtime/server.py

@@ -0,0 +1,25 @@
+"""Server factory for uvicorn."""
+
+from pathlib import Path
+from typing import Any, Optional
+
+from pywire.runtime.app import PyWire
+
+
+def create_app(pages_dir: Optional[Path] = None, reload: bool = False) -> Any:
+    """Create ASGI app - used by uvicorn."""
+    if pages_dir is None:
+        # Default pages directory
+        pages_dir = Path("pages")
+
+        # Try to find pages directory
+        if not pages_dir.exists():
+            # Try src/pages
+            pages_dir = Path("src/pages")
+
+    app = PyWire(str(pages_dir))
+    # Store references to handlers in state for dev server access
+    app.app.state.ws_handler = app.ws_handler
+    app.app.state.http_handler = app.http_handler
+    app.app.state.pywire_app = app
+    return app.app