vega-framework 0.1.34__py3-none-any.whl → 0.2.0__py3-none-any.whl

vega/web/exceptions.py

@@ -0,0 +1,151 @@
+"""HTTP exceptions and status codes for Vega Web Framework"""
+
+from typing import Any, Dict, Optional
+
+
+class HTTPException(Exception):
+    """
+    HTTP exception that can be raised to return an HTTP error response.
+
+    Compatible with FastAPI's HTTPException API for easy migration.
+
+    Args:
+        status_code: HTTP status code
+        detail: Error message or detail object
+        headers: Optional HTTP headers to include in the response
+
+    Example:
+        raise HTTPException(status_code=404, detail="User not found")
+        raise HTTPException(
+            status_code=401,
+            detail="Not authenticated",
+            headers={"WWW-Authenticate": "Bearer"}
+        )
+    """
+
+    def __init__(
+        self,
+        status_code: int,
+        detail: Any = None,
+        headers: Optional[Dict[str, str]] = None
+    ) -> None:
+        self.status_code = status_code
+        self.detail = detail
+        self.headers = headers
+        super().__init__(detail)
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(status_code={self.status_code}, detail={self.detail})"
+
+
+class ValidationError(HTTPException):
+    """Raised when request validation fails (422)"""
+
+    def __init__(self, detail: Any = "Validation Error", headers: Optional[Dict[str, str]] = None):
+        super().__init__(status_code=422, detail=detail, headers=headers)
+
+
+class NotFoundError(HTTPException):
+    """Raised when resource is not found (404)"""
+
+    def __init__(self, detail: Any = "Not Found", headers: Optional[Dict[str, str]] = None):
+        super().__init__(status_code=404, detail=detail, headers=headers)
+
+
+class UnauthorizedError(HTTPException):
+    """Raised when authentication is required (401)"""
+
+    def __init__(self, detail: Any = "Unauthorized", headers: Optional[Dict[str, str]] = None):
+        super().__init__(status_code=401, detail=detail, headers=headers)
+
+
+class ForbiddenError(HTTPException):
+    """Raised when access is forbidden (403)"""
+
+    def __init__(self, detail: Any = "Forbidden", headers: Optional[Dict[str, str]] = None):
+        super().__init__(status_code=403, detail=detail, headers=headers)
+
+
+class BadRequestError(HTTPException):
+    """Raised for bad requests (400)"""
+
+    def __init__(self, detail: Any = "Bad Request", headers: Optional[Dict[str, str]] = None):
+        super().__init__(status_code=400, detail=detail, headers=headers)
+
+
+# HTTP Status codes - compatible with FastAPI's status module
+class status:
+    """HTTP status codes (compatible with fastapi.status)"""
+
+    # 1xx Informational
+    HTTP_100_CONTINUE = 100
+    HTTP_101_SWITCHING_PROTOCOLS = 101
+    HTTP_102_PROCESSING = 102
+    HTTP_103_EARLY_HINTS = 103
+
+    # 2xx Success
+    HTTP_200_OK = 200
+    HTTP_201_CREATED = 201
+    HTTP_202_ACCEPTED = 202
+    HTTP_203_NON_AUTHORITATIVE_INFORMATION = 203
+    HTTP_204_NO_CONTENT = 204
+    HTTP_205_RESET_CONTENT = 205
+    HTTP_206_PARTIAL_CONTENT = 206
+    HTTP_207_MULTI_STATUS = 207
+    HTTP_208_ALREADY_REPORTED = 208
+    HTTP_226_IM_USED = 226
+
+    # 3xx Redirection
+    HTTP_300_MULTIPLE_CHOICES = 300
+    HTTP_301_MOVED_PERMANENTLY = 301
+    HTTP_302_FOUND = 302
+    HTTP_303_SEE_OTHER = 303
+    HTTP_304_NOT_MODIFIED = 304
+    HTTP_305_USE_PROXY = 305
+    HTTP_306_RESERVED = 306
+    HTTP_307_TEMPORARY_REDIRECT = 307
+    HTTP_308_PERMANENT_REDIRECT = 308
+
+    # 4xx Client Error
+    HTTP_400_BAD_REQUEST = 400
+    HTTP_401_UNAUTHORIZED = 401
+    HTTP_402_PAYMENT_REQUIRED = 402
+    HTTP_403_FORBIDDEN = 403
+    HTTP_404_NOT_FOUND = 404
+    HTTP_405_METHOD_NOT_ALLOWED = 405
+    HTTP_406_NOT_ACCEPTABLE = 406
+    HTTP_407_PROXY_AUTHENTICATION_REQUIRED = 407
+    HTTP_408_REQUEST_TIMEOUT = 408
+    HTTP_409_CONFLICT = 409
+    HTTP_410_GONE = 410
+    HTTP_411_LENGTH_REQUIRED = 411
+    HTTP_412_PRECONDITION_FAILED = 412
+    HTTP_413_REQUEST_ENTITY_TOO_LARGE = 413
+    HTTP_414_REQUEST_URI_TOO_LONG = 414
+    HTTP_415_UNSUPPORTED_MEDIA_TYPE = 415
+    HTTP_416_REQUESTED_RANGE_NOT_SATISFIABLE = 416
+    HTTP_417_EXPECTATION_FAILED = 417
+    HTTP_418_IM_A_TEAPOT = 418
+    HTTP_421_MISDIRECTED_REQUEST = 421
+    HTTP_422_UNPROCESSABLE_ENTITY = 422
+    HTTP_423_LOCKED = 423
+    HTTP_424_FAILED_DEPENDENCY = 424
+    HTTP_425_TOO_EARLY = 425
+    HTTP_426_UPGRADE_REQUIRED = 426
+    HTTP_428_PRECONDITION_REQUIRED = 428
+    HTTP_429_TOO_MANY_REQUESTS = 429
+    HTTP_431_REQUEST_HEADER_FIELDS_TOO_LARGE = 431
+    HTTP_451_UNAVAILABLE_FOR_LEGAL_REASONS = 451
+
+    # 5xx Server Error
+    HTTP_500_INTERNAL_SERVER_ERROR = 500
+    HTTP_501_NOT_IMPLEMENTED = 501
+    HTTP_502_BAD_GATEWAY = 502
+    HTTP_503_SERVICE_UNAVAILABLE = 503
+    HTTP_504_GATEWAY_TIMEOUT = 504
+    HTTP_505_HTTP_VERSION_NOT_SUPPORTED = 505
+    HTTP_506_VARIANT_ALSO_NEGOTIATES = 506
+    HTTP_507_INSUFFICIENT_STORAGE = 507
+    HTTP_508_LOOP_DETECTED = 508
+    HTTP_510_NOT_EXTENDED = 510
+    HTTP_511_NETWORK_AUTHENTICATION_REQUIRED = 511

vega/web/middleware.py

@@ -0,0 +1,185 @@
+"""Middleware utilities for Vega Web Framework"""
+
+from typing import Callable
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import Response
+
+
+class VegaMiddleware(BaseHTTPMiddleware):
+    """
+    Base middleware class for Vega applications.
+
+    Extend this class to create custom middleware.
+
+    Example:
+        class LoggingMiddleware(VegaMiddleware):
+            async def dispatch(self, request: Request, call_next: Callable) -> Response:
+                print(f"Request: {request.method} {request.url.path}")
+                response = await call_next(request)
+                print(f"Response: {response.status_code}")
+                return response
+
+        app.add_middleware(LoggingMiddleware)
+    """
+
+    async def dispatch(self, request: Request, call_next: Callable) -> Response:
+        """
+        Process the request.
+
+        Args:
+            request: Incoming request
+            call_next: Function to call next middleware or endpoint
+
+        Returns:
+            Response object
+        """
+        return await call_next(request)
+
+
+class CORSMiddleware:
+    """
+    CORS (Cross-Origin Resource Sharing) middleware.
+
+    This is a re-export of Starlette's CORSMiddleware for convenience.
+
+    Example:
+        from vega.web import VegaApp
+        from vega.web.middleware import CORSMiddleware
+
+        app = VegaApp()
+        app.add_middleware(
+            CORSMiddleware,
+            allow_origins=["*"],
+            allow_credentials=True,
+            allow_methods=["*"],
+            allow_headers=["*"],
+        )
+    """
+
+    # This will be imported from Starlette
+    from starlette.middleware.cors import CORSMiddleware as _CORSMiddleware
+
+    def __new__(cls, *args, **kwargs):
+        return cls._CORSMiddleware(*args, **kwargs)
+
+
+class TrustedHostMiddleware:
+    """
+    Middleware to validate the Host header.
+
+    This is a re-export of Starlette's TrustedHostMiddleware.
+
+    Example:
+        app.add_middleware(
+            TrustedHostMiddleware,
+            allowed_hosts=["example.com", "*.example.com"]
+        )
+    """
+
+    from starlette.middleware.trustedhost import TrustedHostMiddleware as _TrustedHostMiddleware
+
+    def __new__(cls, *args, **kwargs):
+        return cls._TrustedHostMiddleware(*args, **kwargs)
+
+
+class GZipMiddleware:
+    """
+    Middleware to compress responses using GZip.
+
+    This is a re-export of Starlette's GZipMiddleware.
+
+    Example:
+        app.add_middleware(GZipMiddleware, minimum_size=1000)
+    """
+
+    from starlette.middleware.gzip import GZipMiddleware as _GZipMiddleware
+
+    def __new__(cls, *args, **kwargs):
+        return cls._GZipMiddleware(*args, **kwargs)
+
+
+class RateLimitMiddleware(VegaMiddleware):
+    """
+    Simple rate limiting middleware (example implementation).
+
+    Args:
+        requests_per_minute: Maximum requests per minute per IP
+
+    Example:
+        app.add_middleware(RateLimitMiddleware, requests_per_minute=60)
+    """
+
+    def __init__(self, app, requests_per_minute: int = 60):
+        super().__init__(app)
+        self.requests_per_minute = requests_per_minute
+        self.requests: dict = {}  # IP -> [timestamps]
+
+    async def dispatch(self, request: Request, call_next: Callable) -> Response:
+        """Check rate limit before processing request"""
+        from datetime import datetime, timedelta
+
+        client_ip = request.client.host if request.client else "unknown"
+        now = datetime.now()
+
+        # Clean old entries
+        if client_ip in self.requests:
+            cutoff = now - timedelta(minutes=1)
+            self.requests[client_ip] = [
+                ts for ts in self.requests[client_ip] if ts > cutoff
+            ]
+
+        # Check rate limit
+        if client_ip in self.requests:
+            if len(self.requests[client_ip]) >= self.requests_per_minute:
+                from ..response import JSONResponse
+                return JSONResponse(
+                    content={"detail": "Rate limit exceeded"},
+                    status_code=429,
+                )
+
+        # Record request
+        if client_ip not in self.requests:
+            self.requests[client_ip] = []
+        self.requests[client_ip].append(now)
+
+        return await call_next(request)
+
+
+class RequestLoggingMiddleware(VegaMiddleware):
+    """
+    Middleware to log all requests.
+
+    Example:
+        app.add_middleware(RequestLoggingMiddleware)
+    """
+
+    async def dispatch(self, request: Request, call_next: Callable) -> Response:
+        """Log request and response"""
+        import logging
+        import time
+
+        logger = logging.getLogger("vega.web")
+
+        start_time = time.time()
+        logger.info(f"→ {request.method} {request.url.path}")
+
+        response = await call_next(request)
+
+        process_time = time.time() - start_time
+        logger.info(
+            f"← {request.method} {request.url.path} "
+            f"[{response.status_code}] {process_time:.3f}s"
+        )
+
+        return response
+
+
+__all__ = [
+    "VegaMiddleware",
+    "CORSMiddleware",
+    "TrustedHostMiddleware",
+    "GZipMiddleware",
+    "RateLimitMiddleware",
+    "RequestLoggingMiddleware",
+]

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",
+]