vega-framework 0.1.35__py3-none-any.whl → 0.2.1__py3-none-any.whl

vega/web/request.py

@@ -0,0 +1,120 @@
+"""Request wrapper for Vega Web Framework"""
+
+from typing import Any, Dict, Optional
+from starlette.requests import Request as StarletteRequest
+
+
+class Request(StarletteRequest):
+    """
+    HTTP Request wrapper built on Starlette.
+
+    This class extends Starlette's Request to provide a familiar interface
+    for developers coming from FastAPI while maintaining full compatibility
+    with Starlette's ecosystem.
+
+    Attributes:
+        method: HTTP method (GET, POST, etc.)
+        url: Request URL
+        headers: HTTP headers
+        query_params: Query string parameters
+        path_params: Path parameters from URL
+        cookies: Request cookies
+        client: Client address info
+
+    Example:
+        @router.get("/users/{user_id}")
+        async def get_user(request: Request, user_id: str):
+            # Access path parameters
+            assert user_id == request.path_params["user_id"]
+
+            # Access query parameters
+            limit = request.query_params.get("limit", "10")
+
+            # Parse JSON body
+            body = await request.json()
+
+            return {"user_id": user_id, "limit": limit}
+    """
+
+    async def json(self) -> Any:
+        """
+        Parse request body as JSON.
+
+        Returns:
+            Parsed JSON data
+
+        Raises:
+            ValueError: If body is not valid JSON
+        """
+        return await super().json()
+
+    async def form(self) -> Dict[str, Any]:
+        """
+        Parse request body as form data.
+
+        Returns:
+            Form data as dictionary
+        """
+        form_data = await super().form()
+        return dict(form_data)
+
+    async def body(self) -> bytes:
+        """
+        Get raw request body as bytes.
+
+        Returns:
+            Raw body bytes
+        """
+        return await super().body()
+
+    @property
+    def path_params(self) -> Dict[str, Any]:
+        """
+        Get path parameters extracted from URL.
+
+        Returns:
+            Dictionary of path parameters
+        """
+        return self.scope.get("path_params", {})
+
+    def get_header(self, name: str, default: Optional[str] = None) -> Optional[str]:
+        """
+        Get a specific header value.
+
+        Args:
+            name: Header name (case-insensitive)
+            default: Default value if header is not present
+
+        Returns:
+            Header value or default
+        """
+        return self.headers.get(name.lower(), default)
+
+    def get_query_param(self, name: str, default: Optional[str] = None) -> Optional[str]:
+        """
+        Get a specific query parameter value.
+
+        Args:
+            name: Parameter name
+            default: Default value if parameter is not present
+
+        Returns:
+            Parameter value or default
+        """
+        return self.query_params.get(name, default)
+
+    def get_cookie(self, name: str, default: Optional[str] = None) -> Optional[str]:
+        """
+        Get a specific cookie value.
+
+        Args:
+            name: Cookie name
+            default: Default value if cookie is not present
+
+        Returns:
+            Cookie value or default
+        """
+        return self.cookies.get(name, default)
+
+
+__all__ = ["Request"]

vega/web/response.py

@@ -0,0 +1,220 @@
+"""Response classes for Vega Web Framework"""
+
+import json
+from typing import Any, Dict, Optional, Union
+
+from starlette.responses import (
+    Response as StarletteResponse,
+    JSONResponse as StarletteJSONResponse,
+    HTMLResponse as StarletteHTMLResponse,
+    PlainTextResponse as StarlettePlainTextResponse,
+    RedirectResponse as StarletteRedirectResponse,
+    StreamingResponse as StarletteStreamingResponse,
+    FileResponse as StarletteFileResponse,
+)
+
+
+class Response(StarletteResponse):
+    """
+    Base HTTP Response class.
+
+    A thin wrapper around Starlette's Response for API consistency.
+
+    Args:
+        content: Response body content
+        status_code: HTTP status code (default: 200)
+        headers: Optional HTTP headers
+        media_type: Content-Type header value
+
+    Example:
+        return Response(content="Success", status_code=200)
+        return Response(content=b"binary data", media_type="application/octet-stream")
+    """
+
+    pass
+
+
+class JSONResponse(StarletteJSONResponse):
+    """
+    JSON HTTP Response.
+
+    Automatically serializes Python objects to JSON and sets appropriate headers.
+
+    Args:
+        content: Object to serialize as JSON
+        status_code: HTTP status code (default: 200)
+        headers: Optional HTTP headers
+
+    Example:
+        return JSONResponse({"status": "ok", "data": [1, 2, 3]})
+        return JSONResponse({"error": "Not found"}, status_code=404)
+    """
+
+    def render(self, content: Any) -> bytes:
+        """Render content as JSON bytes"""
+        return json.dumps(
+            content,
+            ensure_ascii=False,
+            allow_nan=False,
+            indent=None,
+            separators=(",", ":"),
+        ).encode("utf-8")
+
+
+class HTMLResponse(StarletteHTMLResponse):
+    """
+    HTML HTTP Response.
+
+    Args:
+        content: HTML content as string
+        status_code: HTTP status code (default: 200)
+        headers: Optional HTTP headers
+
+    Example:
+        return HTMLResponse("<h1>Hello World</h1>")
+    """
+
+    pass
+
+
+class PlainTextResponse(StarlettePlainTextResponse):
+    """
+    Plain text HTTP Response.
+
+    Args:
+        content: Text content
+        status_code: HTTP status code (default: 200)
+        headers: Optional HTTP headers
+
+    Example:
+        return PlainTextResponse("Hello, World!")
+    """
+
+    pass
+
+
+class RedirectResponse(StarletteRedirectResponse):
+    """
+    HTTP Redirect Response.
+
+    Args:
+        url: URL to redirect to
+        status_code: HTTP status code (default: 307)
+        headers: Optional HTTP headers
+
+    Example:
+        return RedirectResponse(url="/new-location")
+        return RedirectResponse(url="/login", status_code=302)
+    """
+
+    pass
+
+
+class StreamingResponse(StarletteStreamingResponse):
+    """
+    Streaming HTTP Response.
+
+    Useful for large files or real-time data.
+
+    Args:
+        content: Async generator or iterator
+        status_code: HTTP status code (default: 200)
+        headers: Optional HTTP headers
+        media_type: Content-Type header value
+
+    Example:
+        async def generate():
+            for i in range(10):
+                yield f"data: {i}\\n\\n"
+                await asyncio.sleep(1)
+
+        return StreamingResponse(generate(), media_type="text/event-stream")
+    """
+
+    pass
+
+
+class FileResponse(StarletteFileResponse):
+    """
+    File HTTP Response.
+
+    Efficiently serves files from disk.
+
+    Args:
+        path: Path to file
+        status_code: HTTP status code (default: 200)
+        headers: Optional HTTP headers
+        media_type: Content-Type (auto-detected if not provided)
+        filename: If set, includes Content-Disposition header
+
+    Example:
+        return FileResponse("report.pdf", media_type="application/pdf")
+        return FileResponse("image.jpg", filename="download.jpg")
+    """
+
+    pass
+
+
+def create_response(
+    content: Any = None,
+    status_code: int = 200,
+    headers: Optional[Dict[str, str]] = None,
+    media_type: Optional[str] = None,
+) -> Union[Response, JSONResponse]:
+    """
+    Create an appropriate response based on content type.
+
+    Automatically chooses between Response and JSONResponse based on content.
+
+    Args:
+        content: Response content
+        status_code: HTTP status code
+        headers: Optional HTTP headers
+        media_type: Content-Type header value
+
+    Returns:
+        Response object
+
+    Example:
+        return create_response({"status": "ok"})  # Returns JSONResponse
+        return create_response("text content")     # Returns Response
+    """
+    if content is None:
+        return Response(content=b"", status_code=status_code, headers=headers)
+
+    # If it's a dict, list, or other JSON-serializable type
+    if isinstance(content, (dict, list)):
+        return JSONResponse(content=content, status_code=status_code, headers=headers)
+
+    # If it's a string
+    if isinstance(content, str):
+        return Response(
+            content=content,
+            status_code=status_code,
+            headers=headers,
+            media_type=media_type or "text/plain",
+        )
+
+    # If it's bytes
+    if isinstance(content, bytes):
+        return Response(
+            content=content,
+            status_code=status_code,
+            headers=headers,
+            media_type=media_type or "application/octet-stream",
+        )
+
+    # Default to JSON for other types
+    return JSONResponse(content=content, status_code=status_code, headers=headers)
+
+
+__all__ = [
+    "Response",
+    "JSONResponse",
+    "HTMLResponse",
+    "PlainTextResponse",
+    "RedirectResponse",
+    "StreamingResponse",
+    "FileResponse",
+    "create_response",
+]

vega/web/route_middleware.py

@@ -0,0 +1,266 @@
+"""Route-level middleware system for Vega Web Framework"""
+
+from typing import Callable, List, Optional, Union, Any
+from enum import Enum
+from functools import wraps
+import inspect
+
+from .request import Request
+from .response import Response, JSONResponse
+
+
+class MiddlewarePhase(str, Enum):
+    """When the middleware should execute"""
+    BEFORE = "before"  # Execute before the handler
+    AFTER = "after"    # Execute after the handler
+    BOTH = "both"      # Execute both before and after
+
+
+class RouteMiddleware:
+    """
+    Base class for route-level middleware.
+
+    Route middleware can execute before or after the handler function,
+    allowing for request preprocessing, response postprocessing, or both.
+
+    Attributes:
+        phase: When to execute (BEFORE, AFTER, or BOTH)
+
+    Example:
+        class AuthMiddleware(RouteMiddleware):
+            def __init__(self):
+                super().__init__(phase=MiddlewarePhase.BEFORE)
+
+            async def before(self, request: Request) -> Optional[Response]:
+                token = request.headers.get("Authorization")
+                if not token:
+                    return JSONResponse(
+                        {"detail": "Missing authorization"},
+                        status_code=401
+                    )
+                # Continue to handler
+                return None
+
+        @router.get("/protected")
+        @middleware(AuthMiddleware())
+        async def protected_route():
+            return {"message": "Protected data"}
+    """
+
+    def __init__(self, phase: MiddlewarePhase = MiddlewarePhase.BEFORE):
+        self.phase = phase
+
+    async def before(self, request: Request) -> Optional[Response]:
+        """
+        Execute before the handler.
+
+        Args:
+            request: The incoming request
+
+        Returns:
+            Optional[Response]: Return a Response to short-circuit,
+                              or None to continue to the handler
+        """
+        return None
+
+    async def after(
+        self,
+        request: Request,
+        response: Response
+    ) -> Response:
+        """
+        Execute after the handler.
+
+        Args:
+            request: The incoming request
+            response: The response from the handler
+
+        Returns:
+            Response: Modified or original response
+        """
+        return response
+
+    async def process(
+        self,
+        request: Request,
+        handler: Callable,
+        **kwargs
+    ) -> Response:
+        """
+        Process the middleware chain.
+
+        Args:
+            request: The incoming request
+            handler: The route handler function
+            **kwargs: Handler keyword arguments
+
+        Returns:
+            Response object
+        """
+        # Execute before phase
+        if self.phase in (MiddlewarePhase.BEFORE, MiddlewarePhase.BOTH):
+            before_response = await self.before(request)
+            if before_response is not None:
+                # Short-circuit: return response without calling handler
+                return before_response
+
+        # Call the handler
+        if inspect.iscoroutinefunction(handler):
+            result = await handler(**kwargs)
+        else:
+            result = handler(**kwargs)
+
+        # Convert result to Response if needed
+        if isinstance(result, (Response, JSONResponse)):
+            response = result
+        elif isinstance(result, dict):
+            response = JSONResponse(content=result)
+        elif isinstance(result, (list, tuple)):
+            response = JSONResponse(content=result)
+        elif isinstance(result, str):
+            response = Response(content=result)
+        elif result is None:
+            response = Response(content=b"")
+        else:
+            response = JSONResponse(content=result)
+
+        # Execute after phase
+        if self.phase in (MiddlewarePhase.AFTER, MiddlewarePhase.BOTH):
+            response = await self.after(request, response)
+
+        return response
+
+
+class MiddlewareChain:
+    """
+    Manages a chain of middleware for a route.
+
+    Example:
+        chain = MiddlewareChain([AuthMiddleware(), LoggingMiddleware()])
+        response = await chain.execute(request, handler, user_id="123")
+    """
+
+    def __init__(self, middlewares: List[RouteMiddleware]):
+        self.middlewares = middlewares
+
+    async def execute(
+        self,
+        request: Request,
+        handler: Callable,
+        **kwargs
+    ) -> Response:
+        """
+        Execute the middleware chain.
+
+        Args:
+            request: The incoming request
+            handler: The route handler
+            **kwargs: Handler arguments
+
+        Returns:
+            Response object
+        """
+        if not self.middlewares:
+            # No middleware, call handler directly
+            if inspect.iscoroutinefunction(handler):
+                result = await handler(**kwargs)
+            else:
+                result = handler(**kwargs)
+
+            # Convert to response
+            if isinstance(result, (Response, JSONResponse)):
+                return result
+            elif isinstance(result, dict):
+                return JSONResponse(content=result)
+            elif isinstance(result, (list, tuple)):
+                return JSONResponse(content=result)
+            elif isinstance(result, str):
+                return Response(content=result)
+            elif result is None:
+                return Response(content=b"")
+            else:
+                return JSONResponse(content=result)
+
+        # Execute BEFORE middleware
+        for mw in self.middlewares:
+            if mw.phase in (MiddlewarePhase.BEFORE, MiddlewarePhase.BOTH):
+                before_response = await mw.before(request)
+                if before_response is not None:
+                    # Short-circuit
+                    return before_response
+
+        # Call handler - check if it needs request parameter
+        sig = inspect.signature(handler)
+        handler_params = sig.parameters
+
+        # Add request to kwargs if handler expects it
+        if "request" in handler_params or any(
+            p.annotation.__name__ == "Request" if hasattr(p.annotation, "__name__") else False
+            for p in handler_params.values()
+        ):
+            kwargs["request"] = request
+
+        if inspect.iscoroutinefunction(handler):
+            result = await handler(**kwargs)
+        else:
+            result = handler(**kwargs)
+
+        # Convert to response
+        if isinstance(result, (Response, JSONResponse)):
+            response = result
+        elif isinstance(result, dict):
+            response = JSONResponse(content=result)
+        elif isinstance(result, (list, tuple)):
+            response = JSONResponse(content=result)
+        elif isinstance(result, str):
+            response = Response(content=result)
+        elif result is None:
+            response = Response(content=b"")
+        else:
+            response = JSONResponse(content=result)
+
+        # Execute AFTER middleware (in reverse order)
+        for mw in reversed(self.middlewares):
+            if mw.phase in (MiddlewarePhase.AFTER, MiddlewarePhase.BOTH):
+                response = await mw.after(request, response)
+
+        return response
+
+
+def middleware(*middlewares: RouteMiddleware) -> Callable:
+    """
+    Decorator to attach middleware to a route handler.
+
+    Args:
+        *middlewares: One or more RouteMiddleware instances
+
+    Example:
+        @router.get("/users/{user_id}")
+        @middleware(AuthMiddleware(), LoggingMiddleware())
+        async def get_user(user_id: str):
+            return {"id": user_id}
+
+        # Or single middleware
+        @router.post("/admin/action")
+        @middleware(AdminOnlyMiddleware())
+        async def admin_action():
+            return {"status": "done"}
+    """
+    middleware_list = list(middlewares)
+
+    def decorator(func: Callable) -> Callable:
+        # Store middleware list on the function
+        if not hasattr(func, '_route_middlewares'):
+            func._route_middlewares = []
+        func._route_middlewares.extend(middleware_list)
+        return func
+
+    return decorator
+
+
+__all__ = [
+    "RouteMiddleware",
+    "MiddlewarePhase",
+    "MiddlewareChain",
+    "middleware",
+]