xitzin 0.1.2__py3-none-any.whl

xitzin/responses.py

@@ -0,0 +1,235 @@
+"""Response classes for Xitzin handlers.
+
+These classes provide a convenient way to return different types of Gemini responses.
+Handlers can return these objects, and Xitzin will convert them to GeminiResponse.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Protocol
+
+from nauyaca.protocol.response import GeminiResponse
+from nauyaca.protocol.status import StatusCode
+
+if TYPE_CHECKING:
+    from .application import Xitzin
+    from .requests import Request
+
+
+class ResponseConvertible(Protocol):
+    """Protocol for objects that can be converted to GeminiResponse."""
+
+    def to_gemini_response(self) -> GeminiResponse: ...
+
+
+@dataclass
+class Response:
+    """Success response with a body.
+
+    Example:
+        @app.gemini("/")
+        def home(request: Request):
+            return Response("# Welcome!", mime_type="text/gemini")
+    """
+
+    body: str
+    mime_type: str = "text/gemini"
+
+    def to_gemini_response(self) -> GeminiResponse:
+        return GeminiResponse(
+            status=StatusCode.SUCCESS,
+            meta=self.mime_type,
+            body=self.body,
+        )
+
+
+@dataclass
+class Input:
+    """Request input from the client (status 10/11).
+
+    When returned from a handler, the client will prompt the user for input
+    and re-request the same URL with the input as a query string.
+
+    Example:
+        @app.gemini("/search")
+        def search(request: Request):
+            if not request.query:
+                return Input("Enter your search query:")
+            return f"# Results for: {request.query}"
+    """
+
+    prompt: str
+    sensitive: bool = False
+
+    def to_gemini_response(self) -> GeminiResponse:
+        status = StatusCode.SENSITIVE_INPUT if self.sensitive else StatusCode.INPUT
+        return GeminiResponse(status=status, meta=self.prompt)
+
+
+@dataclass
+class Redirect:
+    """Redirect to another URL (status 30/31).
+
+    Example:
+        @app.gemini("/old-page")
+        def old_page(request: Request):
+            return Redirect("/new-page", permanent=True)
+    """
+
+    url: str
+    permanent: bool = False
+
+    def to_gemini_response(self) -> GeminiResponse:
+        status = (
+            StatusCode.REDIRECT_PERMANENT
+            if self.permanent
+            else StatusCode.REDIRECT_TEMPORARY
+        )
+        return GeminiResponse(status=status, meta=self.url)
+
+
+@dataclass
+class Link:
+    """Build Gemtext link lines.
+
+    Generates link lines in the format: => URL [LABEL]
+
+    Example:
+        # Basic link
+        link = Link("/about", "About Us")
+        str(link)  # "=> /about About Us"
+
+        # Link without label
+        link = Link("/about")
+        str(link)  # "=> /about"
+
+        # Using with app.reverse()
+        link = Link(app.reverse("user_profile", username="alice"), "Alice's Profile")
+        str(link)  # "=> /user/alice Alice's Profile"
+
+        # Using to_route() classmethod
+        link = Link.to_route(
+            app, "user_profile", username="alice", label="Alice's Profile"
+        )
+        str(link)  # "=> /user/alice Alice's Profile"
+    """
+
+    url: str
+    label: str | None = None
+
+    def to_gemtext(self) -> str:
+        """Generate Gemtext link line."""
+        if self.label:
+            return f"=> {self.url} {self.label}"
+        return f"=> {self.url}"
+
+    @classmethod
+    def to_route(
+        cls,
+        app: "Xitzin",
+        name: str,
+        *,
+        label: str | None = None,
+        **params: Any,
+    ) -> "Link":
+        """Create a link to a named route.
+
+        Args:
+            app: Xitzin application instance.
+            name: Route name.
+            label: Optional link label text.
+            **params: Path parameters for URL building.
+
+        Returns:
+            Link instance pointing to the route.
+
+        Example:
+            link = Link.to_route(app, "user_profile", username="alice", label="Profile")
+            str(link)  # "=> /user/alice Profile"
+        """
+        url = app.reverse(name, **params)
+        return cls(url, label)
+
+    def __str__(self) -> str:
+        """Return Gemtext representation."""
+        return self.to_gemtext()
+
+
+def convert_response(result: Any, request: Request | None = None) -> GeminiResponse:
+    """Convert a handler return value to a GeminiResponse.
+
+    Handlers can return:
+    - str: Converted to success response with text/gemini MIME type
+    - Response, Input, Redirect: Converted via to_gemini_response()
+    - GeminiResponse: Returned as-is
+    - tuple: (body, status) or (body, status, meta)
+    - None: Empty success response
+
+    Args:
+        result: The return value from a handler.
+        request: The current request (for URL tracking).
+
+    Returns:
+        A GeminiResponse instance.
+
+    Raises:
+        TypeError: If the result cannot be converted.
+    """
+    url = request._raw_request.normalized_url if request else None
+
+    # Already a GeminiResponse
+    if isinstance(result, GeminiResponse):
+        return result
+
+    # Objects with to_gemini_response method
+    if hasattr(result, "to_gemini_response"):
+        response = result.to_gemini_response()
+        # Add URL tracking if not present
+        if response.url is None and url:
+            return GeminiResponse(
+                status=response.status,
+                meta=response.meta,
+                body=response.body,
+                url=url,
+            )
+        return response
+
+    # Plain string -> success with text/gemini
+    if isinstance(result, str):
+        return GeminiResponse(
+            status=StatusCode.SUCCESS,
+            meta="text/gemini",
+            body=result,
+            url=url,
+        )
+
+    # Tuple: (body, status) or (body, status, meta)
+    if isinstance(result, tuple):
+        if len(result) == 2:
+            body, status = result
+            meta = "text/gemini" if status == StatusCode.SUCCESS else ""
+        elif len(result) == 3:
+            body, status, meta = result
+        else:
+            msg = f"Tuple must have 2 or 3 elements, got {len(result)}"
+            raise TypeError(msg)
+
+        return GeminiResponse(
+            status=status,
+            meta=meta,
+            body=body if 20 <= status < 30 else None,
+            url=url,
+        )
+
+    # None -> empty success
+    if result is None:
+        return GeminiResponse(
+            status=StatusCode.SUCCESS,
+            meta="text/gemini",
+            body="",
+            url=url,
+        )
+
+    msg = f"Cannot convert {type(result).__name__} to GeminiResponse"
+    raise TypeError(msg)

xitzin/routing.py

@@ -0,0 +1,381 @@
+"""Route decorator and path parameter handling.
+
+This module provides the Route class and path parameter extraction logic.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import re
+from typing import TYPE_CHECKING, Any, Callable, get_type_hints
+
+if TYPE_CHECKING:
+    from .requests import Request
+
+# Pattern to match path parameters like {name} or {name:path}
+PATH_PARAM_PATTERN = re.compile(r"\{(\w+)(?::(\w+))?\}")
+
+
+class Route:
+    """Represents a registered route.
+
+    Routes match URL paths and extract parameters based on the path template.
+
+    Example:
+        route = Route("/user/{username}", handler_func)
+        if route.matches("/user/alice"):
+            params = route.extract_params("/user/alice")
+            # params = {"username": "alice"}
+    """
+
+    def __init__(
+        self,
+        path: str,
+        handler: Callable[..., Any],
+        *,
+        name: str | None = None,
+        input_prompt: str | None = None,
+        sensitive_input: bool = False,
+    ) -> None:
+        """Create a new route.
+
+        Args:
+            path: Path template with optional parameters (e.g., "/user/{id}").
+            handler: The handler function to call.
+            name: Route name for URL reversing. Defaults to handler function name.
+            input_prompt: If set, request input with this prompt before calling handler.
+            sensitive_input: If True, use status 11 (sensitive input) instead of 10.
+        """
+        self.path = path
+        self.handler = handler
+        self.name = (
+            name if name is not None else getattr(handler, "__name__", "<anonymous>")
+        )
+        self.input_prompt = input_prompt
+        self.sensitive_input = sensitive_input
+
+        self._param_pattern, self._param_names = self._compile_path(path)
+        self._type_hints = self._get_handler_type_hints(handler)
+        self._is_async = asyncio.iscoroutinefunction(handler)
+
+    def _compile_path(self, path: str) -> tuple[re.Pattern[str], list[str]]:
+        """Convert a path template to a regex pattern.
+
+        Args:
+            path: Path template like "/user/{id}" or "/files/{path:path}".
+
+        Returns:
+            Tuple of (compiled regex, list of parameter names).
+        """
+        param_names: list[str] = []
+
+        def replace_param(match: re.Match[str]) -> str:
+            name = match.group(1)
+            param_type = match.group(2)
+            param_names.append(name)
+
+            # :path captures everything including slashes
+            if param_type == "path":
+                return f"(?P<{name}>.+)"
+            # Default: capture until next slash
+            return f"(?P<{name}>[^/]+)"
+
+        # Escape regex special chars except our parameter syntax
+        escaped = re.escape(path)
+        # Unescape our parameter syntax
+        escaped = escaped.replace(r"\{", "{").replace(r"\}", "}")
+        # Replace parameters with capture groups
+        regex_path = PATH_PARAM_PATTERN.sub(replace_param, escaped)
+
+        return re.compile(f"^{regex_path}$"), param_names
+
+    def _get_handler_type_hints(self, handler: Callable[..., Any]) -> dict[str, type]:
+        """Extract type hints from handler function.
+
+        Excludes 'request' and 'return' from the hints.
+        """
+        try:
+            hints = get_type_hints(handler)
+            # Remove non-parameter hints
+            hints.pop("request", None)
+            hints.pop("return", None)
+            return hints
+        except Exception:
+            return {}
+
+    def matches(self, path: str) -> bool:
+        """Check if this route matches the given path.
+
+        Args:
+            path: URL path to match.
+
+        Returns:
+            True if the path matches this route's pattern.
+        """
+        return self._param_pattern.match(path) is not None
+
+    def extract_params(self, path: str) -> dict[str, Any]:
+        """Extract and type-convert path parameters.
+
+        Args:
+            path: URL path to extract parameters from.
+
+        Returns:
+            Dictionary of parameter names to values.
+        """
+        match = self._param_pattern.match(path)
+        if not match:
+            return {}
+
+        params: dict[str, Any] = {}
+        for name, value in match.groupdict().items():
+            # Apply type conversion based on handler annotations
+            target_type = self._type_hints.get(name, str)
+            try:
+                if target_type is int:
+                    params[name] = int(value)
+                elif target_type is float:
+                    params[name] = float(value)
+                elif target_type is bool:
+                    params[name] = value.lower() in ("true", "1", "yes")
+                else:
+                    params[name] = value
+            except (ValueError, TypeError):
+                # Keep as string if conversion fails
+                params[name] = value
+
+        return params
+
+    async def call_handler(self, request: Request, params: dict[str, Any]) -> Any:
+        """Call the handler with the request and extracted parameters.
+
+        Args:
+            request: The current request.
+            params: Extracted path parameters.
+
+        Returns:
+            The handler's return value.
+        """
+        if self._is_async:
+            return await self.handler(request, **params)
+        # Wrap sync handler in executor to avoid blocking
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(None, lambda: self.handler(request, **params))
+
+    def reverse(self, **params: Any) -> str:
+        """Build URL from this route's path template.
+
+        Args:
+            **params: Path parameters to substitute.
+
+        Returns:
+            URL path string.
+
+        Raises:
+            ValueError: If required parameters are missing.
+
+        Example:
+            route = Route("/user/{username}", handler)
+            route.reverse(username="alice")  # Returns "/user/alice"
+        """
+        missing = set(self._param_names) - set(params.keys())
+        if missing:
+            missing_params = ", ".join(sorted(missing))
+            raise ValueError(
+                f"Route '{self.name}' missing required parameters: {missing_params}"
+            )
+
+        url = self.path
+        for name in self._param_names:
+            value = str(params[name])
+            # Handle both {name} and {name:path} patterns
+            url = url.replace(f"{{{name}}}", value)
+            url = url.replace(f"{{{name}:path}}", value)
+
+        return url
+
+    def __repr__(self) -> str:
+        return f"Route({self.path!r}, name={self.name!r})"
+
+
+class MountedRoute:
+    """Route that delegates to a mounted handler at a path prefix.
+
+    Unlike regular Route, this matches path prefixes and passes the
+    remaining path to the handler, enabling directory-style mounting.
+
+    Example:
+        mounted = MountedRoute("/cgi-bin", cgi_handler)
+        if mounted.matches("/cgi-bin/script.py"):
+            # Calls handler with path_info="script.py"
+    """
+
+    def __init__(
+        self,
+        path_prefix: str,
+        handler: Callable[..., Any],
+        *,
+        name: str | None = None,
+    ) -> None:
+        """Create a mounted route.
+
+        Args:
+            path_prefix: Path prefix to match (e.g., "/cgi-bin").
+            handler: Handler that receives (request, path_info) where
+                path_info is the path after the prefix.
+            name: Optional name for the mount.
+        """
+        # Normalize prefix: ensure it starts with / and doesn't end with /
+        self.path_prefix = "/" + path_prefix.strip("/")
+        self.handler = handler
+        self.name = name or getattr(handler, "__name__", "<mounted>")
+        self._is_async = asyncio.iscoroutinefunction(handler) or (
+            hasattr(handler, "__call__")
+            and asyncio.iscoroutinefunction(handler.__call__)
+        )
+
+    def matches(self, path: str) -> bool:
+        """Check if this mount matches the given path.
+
+        Args:
+            path: URL path to match.
+
+        Returns:
+            True if path starts with this mount's prefix.
+        """
+        # Exact match or prefix with /
+        return path == self.path_prefix or path.startswith(self.path_prefix + "/")
+
+    def extract_path_info(self, path: str) -> str:
+        """Extract the path info (remaining path after prefix).
+
+        Args:
+            path: Full URL path.
+
+        Returns:
+            The path after the mount prefix.
+        """
+        if path == self.path_prefix:
+            return ""
+        # Remove prefix, keep the leading /
+        return path[len(self.path_prefix) :]
+
+    async def call_handler(self, request: Request, path_info: str) -> Any:
+        """Call the handler with the request and path info.
+
+        Args:
+            request: The current request.
+            path_info: Path after the mount prefix.
+
+        Returns:
+            The handler's return value.
+        """
+        if self._is_async:
+            return await self.handler(request, path_info)
+        # Wrap sync handler in executor to avoid blocking
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(
+            None, lambda: self.handler(request, path_info)
+        )
+
+    def __repr__(self) -> str:
+        return f"MountedRoute({self.path_prefix!r}, name={self.name!r})"
+
+
+class Router:
+    """Collection of routes with matching logic.
+
+    Routes are matched in registration order; first match wins.
+    Mounted routes are checked before regular routes.
+    """
+
+    def __init__(self) -> None:
+        self._routes: list[Route] = []
+        self._routes_by_name: dict[str, Route] = {}
+        self._mounted_routes: list[MountedRoute] = []
+
+    def add_route(self, route: Route) -> None:
+        """Add a route to the router.
+
+        Raises:
+            ValueError: If a route with the same name already exists.
+        """
+        if route.name in self._routes_by_name:
+            existing = self._routes_by_name[route.name]
+            msg = (
+                f"Route name '{route.name}' already registered "
+                f"for path '{existing.path}'. "
+                f"Use the name= parameter to provide a unique name."
+            )
+            raise ValueError(msg)
+        self._routes.append(route)
+        self._routes_by_name[route.name] = route
+
+    def add_mounted_route(self, route: MountedRoute) -> None:
+        """Add a mounted route to the router.
+
+        Mounted routes are checked before regular routes.
+
+        Args:
+            route: The mounted route to add.
+        """
+        self._mounted_routes.append(route)
+
+    def match_mount(self, path: str) -> tuple[MountedRoute, str] | None:
+        """Find a matching mounted route and extract path info.
+
+        Args:
+            path: URL path to match.
+
+        Returns:
+            Tuple of (mounted_route, path_info) if found, None otherwise.
+        """
+        for mounted in self._mounted_routes:
+            if mounted.matches(path):
+                path_info = mounted.extract_path_info(path)
+                return mounted, path_info
+        return None
+
+    def match(self, path: str) -> tuple[Route, dict[str, Any]] | None:
+        """Find a matching route and extract parameters.
+
+        Args:
+            path: URL path to match.
+
+        Returns:
+            Tuple of (route, params) if found, None otherwise.
+        """
+        for route in self._routes:
+            if route.matches(path):
+                params = route.extract_params(path)
+                return route, params
+        return None
+
+    def reverse(self, name: str, **params: Any) -> str:
+        """Build URL for a named route.
+
+        Args:
+            name: Route name.
+            **params: Path parameters.
+
+        Returns:
+            URL path string.
+
+        Raises:
+            ValueError: If route name not found or parameters missing.
+
+        Example:
+            router.reverse("user_profile", username="alice")
+            # Returns "/user/alice"
+        """
+        if name not in self._routes_by_name:
+            available = ", ".join(sorted(self._routes_by_name.keys()))
+            raise ValueError(f"No route named '{name}'. Available routes: {available}")
+        route = self._routes_by_name[name]
+        return route.reverse(**params)
+
+    def __iter__(self):
+        return iter(self._routes)
+
+    def __len__(self):
+        return len(self._routes)