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

vega/web/__init__.py

@@ -66,6 +66,10 @@ from .route_middleware import (
     middleware,
 )
 
+# OpenAPI / Documentation
+from .openapi import get_openapi_schema
+from .docs import get_swagger_ui_html, get_redoc_html
+
 __all__ = [
     # Version
     "__version__",
@@ -97,4 +101,8 @@ __all__ = [
     "RouteMiddleware",
     "MiddlewarePhase",
     "middleware",
+    # OpenAPI / Docs
+    "get_openapi_schema",
+    "get_swagger_ui_html",
+    "get_redoc_html",
 ]

vega/web/application.py

@@ -7,10 +7,13 @@ from starlette.middleware import Middleware
 from starlette.middleware.cors import CORSMiddleware
 from starlette.routing import Mount, Route as StarletteRoute
 from starlette.types import ASGIApp
+from starlette.responses import JSONResponse as StarletteJSONResponse
 
 from .router import Router
 from .exceptions import HTTPException
 from .response import JSONResponse
+from .openapi import get_openapi_schema
+from .docs import get_swagger_ui_html, get_redoc_html
 
 
 class VegaApp:
@@ -59,12 +62,20 @@ class VegaApp:
         middleware: Optional[Sequence[Middleware]] = None,
         on_startup: Optional[Sequence[Callable]] = None,
         on_shutdown: Optional[Sequence[Callable]] = None,
+        docs_url: Optional[str] = "/docs",
+        redoc_url: Optional[str] = "/redoc",
+        openapi_url: Optional[str] = "/openapi.json",
     ):
         self.title = title
         self.description = description
         self.version = version
         self.debug = debug
 
+        # Documentation URLs (None to disable)
+        self.docs_url = docs_url
+        self.redoc_url = redoc_url
+        self.openapi_url = openapi_url
+
         # Internal router for top-level routes
         self._router = Router()
 
@@ -78,6 +89,9 @@ class VegaApp:
         # Starlette app (created lazily)
         self._starlette_app: Optional[Starlette] = None
 
+        # OpenAPI schema (cached)
+        self._openapi_schema: Optional[Dict[str, Any]] = None
+
     def add_middleware(
         self,
         middleware_class: type,
@@ -197,6 +211,22 @@ class VegaApp:
         """
         return self._router.route(path, methods, **kwargs)
 
+    def openapi(self) -> Dict[str, Any]:
+        """
+        Generate and return the OpenAPI schema.
+
+        Returns:
+            OpenAPI schema dictionary
+        """
+        if self._openapi_schema is None:
+            self._openapi_schema = get_openapi_schema(
+                title=self.title,
+                version=self.version,
+                description=self.description,
+                routes=self._router.get_routes(),
+            )
+        return self._openapi_schema
+
     def _build_starlette_app(self) -> Starlette:
         """Build the Starlette application from routes and middleware."""
         # Convert Vega routes to Starlette routes
@@ -204,6 +234,39 @@ class VegaApp:
             route.to_starlette_route() for route in self._router.get_routes()
         ]
 
+        # Add OpenAPI endpoint
+        if self.openapi_url:
+            async def openapi_endpoint(request):
+                return StarletteJSONResponse(self.openapi())
+
+            starlette_routes.append(
+                StarletteRoute(self.openapi_url, endpoint=openapi_endpoint, methods=["GET"])
+            )
+
+        # Add Swagger UI endpoint
+        if self.docs_url:
+            async def swagger_ui_endpoint(request):
+                return get_swagger_ui_html(
+                    openapi_url=self.openapi_url or "/openapi.json",
+                    title=f"{self.title} - Swagger UI"
+                )
+
+            starlette_routes.append(
+                StarletteRoute(self.docs_url, endpoint=swagger_ui_endpoint, methods=["GET"])
+            )
+
+        # Add ReDoc endpoint
+        if self.redoc_url:
+            async def redoc_endpoint(request):
+                return get_redoc_html(
+                    openapi_url=self.openapi_url or "/openapi.json",
+                    title=f"{self.title} - ReDoc"
+                )
+
+            starlette_routes.append(
+                StarletteRoute(self.redoc_url, endpoint=redoc_endpoint, methods=["GET"])
+            )
+
         # Create Starlette app
         app = Starlette(
             debug=self.debug,

vega/web/docs.py

@@ -0,0 +1,104 @@
+"""Documentation endpoints for Vega Web Framework"""
+
+from typing import Callable
+from starlette.responses import HTMLResponse, JSONResponse
+
+
+def get_swagger_ui_html(
+    *,
+    openapi_url: str,
+    title: str,
+    swagger_js_url: str = "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-bundle.js",
+    swagger_css_url: str = "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui.css",
+    swagger_favicon_url: str = "https://fastapi.tiangolo.com/img/favicon.png",
+) -> HTMLResponse:
+    """
+    Generate Swagger UI HTML page.
+
+    Args:
+        openapi_url: URL to OpenAPI schema JSON
+        title: Page title
+        swagger_js_url: URL to Swagger UI JavaScript
+        swagger_css_url: URL to Swagger UI CSS
+        swagger_favicon_url: URL to favicon
+
+    Returns:
+        HTML response with Swagger UI
+    """
+    html = f"""
+    <!DOCTYPE html>
+    <html>
+    <head>
+        <title>{title}</title>
+        <meta charset="utf-8"/>
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+        <link rel="shortcut icon" href="{swagger_favicon_url}">
+        <link rel="stylesheet" type="text/css" href="{swagger_css_url}" />
+    </head>
+    <body>
+        <div id="swagger-ui"></div>
+        <script src="{swagger_js_url}"></script>
+        <script>
+            const ui = SwaggerUIBundle({{
+                url: '{openapi_url}',
+                dom_id: '#swagger-ui',
+                presets: [
+                    SwaggerUIBundle.presets.apis,
+                    SwaggerUIBundle.SwaggerUIStandalonePreset
+                ],
+                layout: "BaseLayout",
+                deepLinking: true,
+                showExtensions: true,
+                showCommonExtensions: true
+            }})
+        </script>
+    </body>
+    </html>
+    """
+    return HTMLResponse(content=html)
+
+
+def get_redoc_html(
+    *,
+    openapi_url: str,
+    title: str,
+    redoc_js_url: str = "https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js",
+    redoc_favicon_url: str = "https://fastapi.tiangolo.com/img/favicon.png",
+) -> HTMLResponse:
+    """
+    Generate ReDoc HTML page.
+
+    Args:
+        openapi_url: URL to OpenAPI schema JSON
+        title: Page title
+        redoc_js_url: URL to ReDoc JavaScript
+        redoc_favicon_url: URL to favicon
+
+    Returns:
+        HTML response with ReDoc
+    """
+    html = f"""
+    <!DOCTYPE html>
+    <html>
+    <head>
+        <title>{title}</title>
+        <meta charset="utf-8"/>
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+        <link rel="shortcut icon" href="{redoc_favicon_url}">
+        <style>
+            body {{
+                margin: 0;
+                padding: 0;
+            }}
+        </style>
+    </head>
+    <body>
+        <redoc spec-url="{openapi_url}"></redoc>
+        <script src="{redoc_js_url}"></script>
+    </body>
+    </html>
+    """
+    return HTMLResponse(content=html)
+
+
+__all__ = ["get_swagger_ui_html", "get_redoc_html"]

vega/web/openapi.py

@@ -0,0 +1,292 @@
+"""OpenAPI schema generation for Vega Web Framework"""
+
+from typing import Any, Dict, List, Optional, Type, get_type_hints
+from inspect import signature, Parameter
+import json
+
+try:
+    from pydantic import BaseModel
+    PYDANTIC_AVAILABLE = True
+except ImportError:
+    PYDANTIC_AVAILABLE = False
+    BaseModel = None  # type: ignore
+
+
+def get_openapi_schema(
+    *,
+    title: str,
+    version: str,
+    description: str = "",
+    routes: List[Any],
+    openapi_version: str = "3.0.2",
+) -> Dict[str, Any]:
+    """
+    Generate OpenAPI 3.0 schema from routes.
+
+    Args:
+        title: API title
+        version: API version
+        description: API description
+        routes: List of Route objects
+        openapi_version: OpenAPI specification version
+
+    Returns:
+        OpenAPI schema dictionary
+    """
+    schema: Dict[str, Any] = {
+        "openapi": openapi_version,
+        "info": {
+            "title": title,
+            "version": version,
+        },
+        "paths": {},
+    }
+
+    if description:
+        schema["info"]["description"] = description
+
+    # Components for reusable schemas
+    components: Dict[str, Any] = {
+        "schemas": {}
+    }
+
+    # Process each route
+    for route in routes:
+        path = route.path
+
+        # Convert path parameters from {param} to OpenAPI format
+        openapi_path = path
+
+        if openapi_path not in schema["paths"]:
+            schema["paths"][openapi_path] = {}
+
+        for method in route.methods:
+            method_lower = method.lower()
+
+            operation: Dict[str, Any] = {
+                "responses": {
+                    "200": {
+                        "description": "Successful Response"
+                    }
+                }
+            }
+
+            # Add summary and description
+            if route.summary:
+                operation["summary"] = route.summary
+
+            if route.description:
+                operation["description"] = route.description
+            elif route.endpoint.__doc__:
+                operation["description"] = route.endpoint.__doc__.strip()
+
+            # Add tags
+            if route.tags:
+                operation["tags"] = route.tags
+
+            # Add operation ID
+            operation["operationId"] = f"{method_lower}_{route.name or route.endpoint.__name__}"
+
+            # Analyze endpoint parameters
+            params = _get_parameters(route)
+            if params:
+                operation["parameters"] = params
+
+            # Analyze request body
+            request_body = _get_request_body(route)
+            if request_body:
+                operation["requestBody"] = request_body
+                # Add request body schemas to components
+                if PYDANTIC_AVAILABLE and "content" in request_body:
+                    for content_type, content_schema in request_body["content"].items():
+                        if "schema" in content_schema and "$ref" in content_schema["schema"]:
+                            model_name = content_schema["schema"]["$ref"].split("/")[-1]
+                            # Model will be added when processing response_model
+
+            # Analyze response model
+            if route.response_model:
+                response_schema = _get_response_schema(route.response_model, components)
+                if response_schema:
+                    operation["responses"]["200"] = {
+                        "description": "Successful Response",
+                        "content": {
+                            "application/json": {
+                                "schema": response_schema
+                            }
+                        }
+                    }
+
+            # Add status code if specified
+            if route.status_code and route.status_code != 200:
+                operation["responses"][str(route.status_code)] = operation["responses"].pop("200")
+
+            # Add error responses
+            operation["responses"]["422"] = {
+                "description": "Validation Error"
+            }
+
+            schema["paths"][openapi_path][method_lower] = operation
+
+    # Add components if we have any schemas
+    if components["schemas"]:
+        schema["components"] = components
+
+    return schema
+
+
+def _get_parameters(route: Any) -> List[Dict[str, Any]]:
+    """Extract path and query parameters from route."""
+    parameters = []
+
+    # Get function signature
+    sig = signature(route.endpoint)
+    type_hints = get_type_hints(route.endpoint)
+
+    # Find which parameters are Pydantic models (request body)
+    request_body_params = set()
+    if PYDANTIC_AVAILABLE:
+        for param_name, param in sig.parameters.items():
+            param_type = type_hints.get(param_name)
+            if param_type and isinstance(param_type, type) and issubclass(param_type, BaseModel):
+                request_body_params.add(param_name)
+
+    for param_name, param in sig.parameters.items():
+        # Skip special parameters
+        if param_name in ("request", "self", "cls"):
+            continue
+
+        # Skip parameters that are Pydantic models (they're in request body)
+        if param_name in request_body_params:
+            continue
+
+        # Check if it's a path parameter
+        if f"{{{param_name}}}" in route.path:
+            param_schema = {
+                "name": param_name,
+                "in": "path",
+                "required": True,
+                "schema": _get_type_schema(type_hints.get(param_name, str))
+            }
+            parameters.append(param_schema)
+        elif param.default == Parameter.empty:
+            # Required query parameter
+            param_schema = {
+                "name": param_name,
+                "in": "query",
+                "required": True,
+                "schema": _get_type_schema(type_hints.get(param_name, str))
+            }
+            parameters.append(param_schema)
+        else:
+            # Optional query parameter
+            param_schema = {
+                "name": param_name,
+                "in": "query",
+                "required": False,
+                "schema": _get_type_schema(type_hints.get(param_name, str))
+            }
+            if param.default is not None and param.default != Parameter.empty:
+                param_schema["schema"]["default"] = param.default
+            parameters.append(param_schema)
+
+    return parameters
+
+
+def _get_request_body(route: Any) -> Optional[Dict[str, Any]]:
+    """Extract request body schema from route."""
+    if not PYDANTIC_AVAILABLE:
+        return None
+
+    # Get function signature
+    sig = signature(route.endpoint)
+    type_hints = get_type_hints(route.endpoint)
+
+    for param_name, param in sig.parameters.items():
+        # Skip special parameters and path parameters
+        if param_name in ("request", "self", "cls"):
+            continue
+        if f"{{{param_name}}}" in route.path:
+            continue
+
+        param_type = type_hints.get(param_name)
+
+        # Check if it's a Pydantic model
+        if param_type and isinstance(param_type, type) and issubclass(param_type, BaseModel):
+            model_schema = param_type.model_json_schema()
+            model_name = param_type.__name__
+
+            return {
+                "required": True,
+                "content": {
+                    "application/json": {
+                        "schema": {
+                            "$ref": f"#/components/schemas/{model_name}"
+                        }
+                    }
+                }
+            }
+
+    return None
+
+
+def _get_response_schema(response_model: Type, components: Dict[str, Any]) -> Dict[str, Any]:
+    """Get response schema from response model."""
+    if not PYDANTIC_AVAILABLE:
+        return {}
+
+    # Handle Pydantic models
+    if isinstance(response_model, type) and issubclass(response_model, BaseModel):
+        model_name = response_model.__name__
+
+        # Add model schema to components
+        if model_name not in components["schemas"]:
+            components["schemas"][model_name] = response_model.model_json_schema()
+
+        return {
+            "$ref": f"#/components/schemas/{model_name}"
+        }
+
+    # Handle List types
+    if hasattr(response_model, "__origin__"):
+        if response_model.__origin__ is list:
+            item_type = response_model.__args__[0]
+            if isinstance(item_type, type) and issubclass(item_type, BaseModel):
+                model_name = item_type.__name__
+
+                # Add model schema to components
+                if model_name not in components["schemas"]:
+                    components["schemas"][model_name] = item_type.model_json_schema()
+
+                return {
+                    "type": "array",
+                    "items": {
+                        "$ref": f"#/components/schemas/{model_name}"
+                    }
+                }
+
+    # Handle dict
+    if response_model is dict:
+        return {"type": "object"}
+
+    return {}
+
+
+def _get_type_schema(param_type: Any) -> Dict[str, Any]:
+    """Convert Python type to OpenAPI schema."""
+    if param_type is str or param_type == "str":
+        return {"type": "string"}
+    elif param_type is int or param_type == "int":
+        return {"type": "integer"}
+    elif param_type is float or param_type == "float":
+        return {"type": "number"}
+    elif param_type is bool or param_type == "bool":
+        return {"type": "boolean"}
+    elif param_type is list or (hasattr(param_type, "__origin__") and param_type.__origin__ is list):
+        return {"type": "array", "items": {}}
+    elif param_type is dict:
+        return {"type": "object"}
+    else:
+        return {"type": "string"}
+
+
+__all__ = ["get_openapi_schema"]

vega/web/routing.py

@@ -6,6 +6,7 @@ from functools import wraps
 
 from starlette.routing import Route as StarletteRoute, Mount
 from starlette.requests import Request as StarletteRequest
+from pydantic import BaseModel, ValidationError
 
 from .exceptions import HTTPException
 from .request import Request
@@ -13,6 +14,14 @@ from .response import JSONResponse, Response, create_response
 from .route_middleware import MiddlewareChain
 
 
+def _is_pydantic_model(type_hint: Any) -> bool:
+    """Check if a type hint is a Pydantic BaseModel"""
+    try:
+        return inspect.isclass(type_hint) and issubclass(type_hint, BaseModel)
+    except (TypeError, AttributeError):
+        return False
+
+
 class Route:
     """
     Represents a single route in the application.
@@ -73,6 +82,12 @@ class Route:
                 sig = inspect.signature(self.endpoint)
                 params = sig.parameters
 
+                # Get type hints for the function
+                try:
+                    type_hints = get_type_hints(self.endpoint)
+                except Exception:
+                    type_hints = {}
+
                 # Prepare kwargs for function call
                 kwargs = {}
 
@@ -93,6 +108,37 @@ class Route:
                     if param_name in params:
                         kwargs[param_name] = param_value
 
+                # Check for Pydantic model parameters (body parsing)
+                # Only parse the first Pydantic model found
+                body_parsed = False
+                for param_name, param in params.items():
+                    # Skip if already processed (request or path param)
+                    if param_name in kwargs or param_name == "request":
+                        continue
+
+                    # Get type hint for this parameter
+                    param_type = type_hints.get(param_name, param.annotation)
+
+                    # If it's a Pydantic model, parse the request body (only once)
+                    if _is_pydantic_model(param_type) and not body_parsed:
+                        try:
+                            body_data = await request.json()
+                            # Validate and parse using Pydantic
+                            kwargs[param_name] = param_type(**body_data)
+                            body_parsed = True
+                        except ValidationError as e:
+                            # Return validation errors in a user-friendly format
+                            return JSONResponse(
+                                content={"detail": e.errors()},
+                                status_code=422,
+                            )
+                        except Exception as e:
+                            # Handle JSON parsing errors
+                            return JSONResponse(
+                                content={"detail": f"Invalid JSON body: {str(e)}"},
+                                status_code=400,
+                            )
+
                 # Execute middleware chain if present
                 if self.middlewares:
                     middleware_chain = MiddlewareChain(self.middlewares)
@@ -113,6 +159,9 @@ class Route:
                 # Handle different return types
                 if isinstance(result, (Response, JSONResponse)):
                     return result
+                elif isinstance(result, BaseModel):
+                    # Serialize Pydantic models using model_dump()
+                    return JSONResponse(content=result.model_dump(), status_code=self.status_code)
                 elif isinstance(result, dict):
                     return JSONResponse(content=result, status_code=self.status_code)
                 elif isinstance(result, (list, tuple)):

{vega_framework-0.2.1.dist-info → vega_framework-0.2.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vega-framework
-Version: 0.2.1
+Version: 0.2.3
 Summary: Enterprise-ready Python framework that enforces Clean Architecture for building maintainable and scalable applications.
 License: MIT
 License-File: LICENSE

{vega_framework-0.2.1.dist-info → vega_framework-0.2.3.dist-info}/RECORD

@@ -84,18 +84,20 @@ vega/patterns/repository.py,sha256=uYUyLs-O8OqW1Wb9ZqIo8UUcCjZ5UFuHors_F2iDg9A,1
 vega/patterns/service.py,sha256=buFRgJoeQtZQK22Upb4vh84c1elWKFXWBaB0X4RaruE,1374
 vega/settings/__init__.py,sha256=Eb8PMUyXAlCAQIcL2W8QhTTUHUbVlkAfXdpTUlADo1I,786
 vega/settings/base.py,sha256=bL45hyoa3t-hQOvur860eSo7O833sQMsXJJPwbTVbwE,1321
-vega/web/__init__.py,sha256=grAuMNHY1Z0uPXJVDdyyBt_X6JbKzdubG-7FAizW7Ws,2032
-vega/web/application.py,sha256=OIupZT_Q3Lad74Zr-fzl1oxgbBc0cl1NEDR3Nz0TxTY,7004
+vega/web/__init__.py,sha256=ZwWpk5eXXOsV6wWT03JqtadzNrcfD9h4eFELmvZOOuY,2249
+vega/web/application.py,sha256=tlq-StqFdBZlV3AIo4ETvvEGSskg3BJXTVMaWuNjXNo,9227
 vega/web/builtin_middlewares.py,sha256=01iSy-pZL-Y1R-f-GHzT2GVtdRuYK_-wZFv0VP_S9BU,9356
+vega/web/docs.py,sha256=yTIgJLcqNz4Zca5AbtKYJsqCz-5UJevjJ7_g04XrwVo,2979
 vega/web/exceptions.py,sha256=QxfhHntAIMwfqCvaCRro8MqKvxZxARjSoL9eTNWa5Qc,4897
 vega/web/middleware.py,sha256=DZLlkcuKOV1uPGYnaT4MsbvFWnzFVAiyGcSvi8D2Vnw,5204
+vega/web/openapi.py,sha256=OAdsIWa8jRwgEJruhPaOlHt0lLqW-SIr930NvtIu6ac,9636
 vega/web/request.py,sha256=-xz6cbRAxtY0hZv62UFgg0ces0dtDcCCE_EHcw6cEms,3181
 vega/web/response.py,sha256=h5E7crRepaFRyUecasIbP3ErkRLpFQXRZhYl9OrFLWY,5641
 vega/web/route_middleware.py,sha256=zZzkXsdu7bCRcw-CXvFmTjNuyJ1v4NNM1DbEQo7l0qg,8208
 vega/web/router.py,sha256=6K6TPMZhi92jd030guYh_mdfN3Z9MTSfjy1P3xnFfdg,10575
-vega/web/routing.py,sha256=5uxiroobZb194Vg_MNzJyd-B7BOiitdwQuH2oq9Z5B8,10506
-vega_framework-0.2.1.dist-info/METADATA,sha256=6VpDFAD9nzakWdVxQ1YtHWX2qaisS89opDKe2dcfU8s,11226
-vega_framework-0.2.1.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
-vega_framework-0.2.1.dist-info/entry_points.txt,sha256=p3gyTmPYjNRLbuiKS-hG3ytWd-ssBweFy6VZ-F9FTNk,42
-vega_framework-0.2.1.dist-info/licenses/LICENSE,sha256=wlHh1MBTcs2kSQr99P30mZ61s7uh7Cp9Rk0YiJxots0,1084
-vega_framework-0.2.1.dist-info/RECORD,,
+vega/web/routing.py,sha256=PLytM0eBBoxIkewj6BFJ6f7py3Uqery1H94ANOqQkjs,12840
+vega_framework-0.2.3.dist-info/METADATA,sha256=HtFX2scSAqbbUV113sln9FjQs0DqPdY3nglj4nWAYT4,11226
+vega_framework-0.2.3.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+vega_framework-0.2.3.dist-info/entry_points.txt,sha256=p3gyTmPYjNRLbuiKS-hG3ytWd-ssBweFy6VZ-F9FTNk,42
+vega_framework-0.2.3.dist-info/licenses/LICENSE,sha256=wlHh1MBTcs2kSQr99P30mZ61s7uh7Cp9Rk0YiJxots0,1084
+vega_framework-0.2.3.dist-info/RECORD,,