django-bolt 0.1.0__cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

django_bolt/decorators.py

@@ -0,0 +1,159 @@
+"""
+Decorators for Django-Bolt.
+
+Provides decorators for ViewSet custom actions similar to Django REST Framework's @action decorator.
+"""
+from typing import Any, Callable, List, Optional
+
+
+class ActionHandler:
+    """
+    Marker class for ViewSet custom actions decorated with @action.
+
+    When @action is used inside a ViewSet class, it returns an ActionHandler instance
+    that stores metadata about the action. The api.viewset() method discovers these
+    ActionHandler instances and auto-generates routes.
+
+    Similar to Django REST Framework's @action decorator approach.
+
+    Attributes:
+        fn: The wrapped function
+        methods: List of HTTP methods (e.g., ["GET", "POST"])
+        detail: Whether this is a detail (instance-level) or list (collection-level) action
+        path: Custom path segment (defaults to function name)
+        auth: Optional authentication backends
+        guards: Optional permission guards
+        response_model: Optional response model for serialization
+        status_code: Optional HTTP status code
+    """
+
+    __slots__ = ('fn', 'methods', 'detail', 'path', 'auth', 'guards', 'response_model', 'status_code')
+
+    def __init__(
+        self,
+        fn: Callable,
+        methods: List[str],
+        detail: bool,
+        path: Optional[str] = None,
+        auth: Optional[List[Any]] = None,
+        guards: Optional[List[Any]] = None,
+        response_model: Optional[Any] = None,
+        status_code: Optional[int] = None,
+    ):
+        self.fn = fn
+        self.methods = [m.upper() for m in methods]  # Normalize to uppercase
+        self.detail = detail
+        self.path = path or fn.__name__  # Default to function name
+        self.auth = auth
+        self.guards = guards
+        self.response_model = response_model
+        self.status_code = status_code
+   
+
+    def __call__(self, *args, **kwargs):
+        """Make the handler callable (delegates to wrapped function)."""
+        return self.fn(*args, **kwargs)
+
+    def __repr__(self):
+        methods_str = '|'.join(self.methods)
+        detail_str = 'detail' if self.detail else 'list'
+        return f"ActionHandler({methods_str}, {detail_str}, path={self.path}, fn={self.fn.__name__})"
+
+
+def action(
+    methods: List[str],
+    detail: bool,
+    path: Optional[str] = None,
+    *,
+    auth: Optional[List[Any]] = None,
+    guards: Optional[List[Any]] = None,
+    response_model: Optional[Any] = None,
+    status_code: Optional[int] = None
+) -> Callable:
+    """
+    Decorator for ViewSet custom actions (DRF-style).
+
+    Marks a ViewSet method as a custom action with automatic route generation.
+
+    Auto-generated paths:
+    - detail=True (instance-level):  /{resource}/{pk}/{action_name}
+      Example: @action(methods=["POST"], detail=True) -> POST /users/{id}/activate
+
+    - detail=False (collection-level): /{resource}/{action_name}
+      Example: @action(methods=["GET"], detail=False) -> GET /users/active
+
+    Multiple methods on single action:
+    - @action(methods=["GET", "POST"], detail=True, path="preferences")
+      Generates both: GET /users/{id}/preferences and POST /users/{id}/preferences
+
+    Args:
+        methods: List of HTTP methods (e.g., ["GET"], ["POST"], ["GET", "POST"])
+        detail: True for instance-level (requires pk), False for collection-level
+        path: Optional custom action name (defaults to function name)
+        auth: Optional authentication backends (overrides class-level auth)
+        guards: Optional permission guards (overrides class-level guards)
+        response_model: Optional response model for serialization
+        status_code: Optional HTTP status code
+
+    Returns:
+        ActionHandler instance that wraps the function with metadata
+
+    Example:
+        @api.viewset("/users")
+        class UserViewSet(ViewSet):
+            async def list(self, request) -> list[UserMini]:
+                return User.objects.all()[:100]
+
+            # Instance-level action: POST /users/{id}/activate
+            @action(methods=["POST"], detail=True)
+            async def activate(self, request, id: int) -> UserFull:
+                user = await User.objects.aget(id=id)
+                user.is_active = True
+                await user.asave()
+                return user
+
+            # Collection-level action: GET /users/active
+            @action(methods=["GET"], detail=False)
+            async def active(self, request) -> list[UserMini]:
+                return User.objects.filter(is_active=True)[:100]
+
+            # Custom path: GET/POST /users/{id}/preferences
+            @action(methods=["GET", "POST"], detail=True, path="preferences")
+            async def user_preferences(self, request, id: int, data: dict | None = None):
+                if data:  # POST
+                    # update preferences
+                    pass
+                else:  # GET
+                    # return preferences
+                    pass
+
+    Notes:
+        - Actions inherit class-level auth and guards unless explicitly overridden
+        - The function must be async
+        - Path parameters are automatically extracted from the route
+        - For detail=True actions, the lookup field parameter (e.g., 'id', 'pk') is required
+    """
+    def decorator(fn: Callable) -> ActionHandler:
+        """Wrap the function with ActionHandler metadata."""
+        # Validate methods
+        valid_methods = {'GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'}
+        for method in methods:
+            if method.upper() not in valid_methods:
+                raise ValueError(
+                    f"Invalid HTTP method '{method}'. "
+                    f"Valid methods: {', '.join(sorted(valid_methods))}"
+                )
+
+        # Create and return ActionHandler
+        return ActionHandler(
+            fn=fn,
+            methods=methods,
+            detail=detail,
+            path=path,
+            auth=auth,
+            guards=guards,
+            response_model=response_model,
+            status_code=status_code
+        )
+
+    return decorator

django_bolt/dependencies.py

@@ -0,0 +1,128 @@
+"""Dependency injection utilities."""
+import inspect
+from typing import Any, Callable, Dict, List
+from .params import Depends as DependsMarker
+from .binding import convert_primitive
+
+
+async def resolve_dependency(
+    dep_fn: Callable,
+    depends_marker: DependsMarker,
+    request: Dict[str, Any],
+    dep_cache: Dict[Any, Any],
+    params_map: Dict[str, Any],
+    query_map: Dict[str, Any],
+    headers_map: Dict[str, str],
+    cookies_map: Dict[str, str],
+    handler_meta: Dict[Callable, Dict[str, Any]],
+    compile_binder: Callable,
+    http_method: str,
+    path: str
+) -> Any:
+    """
+    Resolve a dependency injection.
+
+    Args:
+        dep_fn: Dependency function to resolve
+        depends_marker: Depends marker with cache settings
+        request: Request dict
+        dep_cache: Cache for resolved dependencies
+        params_map: Path parameters
+        query_map: Query parameters
+        headers_map: Request headers
+        cookies_map: Request cookies
+        handler_meta: Metadata cache for handlers
+        compile_binder: Function to compile parameter binding metadata
+        http_method: HTTP method of the handler using this dependency
+        path: Path of the handler using this dependency
+
+    Returns:
+        Resolved dependency value
+    """
+    if depends_marker.use_cache and dep_fn in dep_cache:
+        return dep_cache[dep_fn]
+
+    dep_meta = handler_meta.get(dep_fn)
+    if dep_meta is None:
+        # Compile dependency metadata with the actual HTTP method and path
+        # Dependencies MUST be validated against HTTP method constraints
+        # e.g., a dependency with Body() can't be used in GET handlers
+        dep_meta = compile_binder(dep_fn, http_method, path)
+        handler_meta[dep_fn] = dep_meta
+
+    if dep_meta.get("mode") == "request_only":
+        value = await dep_fn(request)
+    else:
+        value = await call_dependency(
+            dep_fn, dep_meta, request, params_map,
+            query_map, headers_map, cookies_map
+        )
+
+    if depends_marker.use_cache:
+        dep_cache[dep_fn] = value
+
+    return value
+
+
+async def call_dependency(
+    dep_fn: Callable,
+    dep_meta: Dict[str, Any],
+    request: Dict[str, Any],
+    params_map: Dict[str, Any],
+    query_map: Dict[str, Any],
+    headers_map: Dict[str, str],
+    cookies_map: Dict[str, str]
+) -> Any:
+    """Call a dependency function with resolved parameters."""
+    dep_args: List[Any] = []
+    dep_kwargs: Dict[str, Any] = {}
+
+    for dp in dep_meta["params"]:
+        dname = dp["name"]
+        dan = dp["annotation"]
+        dsrc = dp["source"]
+        dalias = dp.get("alias")
+
+        if dsrc == "request":
+            dval = request
+        else:
+            dval = extract_dependency_value(dp, params_map, query_map, headers_map, cookies_map)
+
+        if dp["kind"] in (inspect.Parameter.POSITIONAL_ONLY, inspect.Parameter.POSITIONAL_OR_KEYWORD):
+            dep_args.append(dval)
+        else:
+            dep_kwargs[dname] = dval
+
+    return await dep_fn(*dep_args, **dep_kwargs)
+
+
+def extract_dependency_value(
+    param: Dict[str, Any],
+    params_map: Dict[str, Any],
+    query_map: Dict[str, Any],
+    headers_map: Dict[str, str],
+    cookies_map: Dict[str, str]
+) -> Any:
+    """Extract value for a dependency parameter."""
+    dname = param["name"]
+    dan = param["annotation"]
+    dsrc = param["source"]
+    dalias = param.get("alias")
+    key = dalias or dname
+
+    if key in params_map:
+        return convert_primitive(str(params_map[key]), dan)
+    elif key in query_map:
+        return convert_primitive(str(query_map[key]), dan)
+    elif dsrc == "header":
+        raw = headers_map.get(key.lower())
+        if raw is None:
+            raise ValueError(f"Missing required header: {key}")
+        return convert_primitive(str(raw), dan)
+    elif dsrc == "cookie":
+        raw = cookies_map.get(key)
+        if raw is None:
+            raise ValueError(f"Missing required cookie: {key}")
+        return convert_primitive(str(raw), dan)
+    else:
+        return None

django_bolt/error_handlers.py

@@ -0,0 +1,305 @@
+"""Error handlers for Django-Bolt.
+
+Provides default exception handlers that convert Python exceptions into
+structured HTTP error responses.
+"""
+
+import msgspec
+import traceback
+from typing import Any, Dict, List, Tuple, Optional
+from .exceptions import (
+    HTTPException,
+    RequestValidationError,
+    ResponseValidationError,
+    ValidationException,
+    InternalServerError,
+)
+
+
+def format_error_response(
+    status_code: int,
+    detail: Any,
+    headers: Optional[Dict[str, str]] = None,
+    extra: Optional[Dict[str, Any] | List[Any]] = None,
+) -> Tuple[int, List[Tuple[str, str]], bytes]:
+    """Format an error response.
+
+    Args:
+        status_code: HTTP status code
+        detail: Error detail (string or structured data)
+        headers: Optional HTTP headers
+        extra: Optional extra data to include in response
+
+    Returns:
+        Tuple of (status_code, headers, body)
+    """
+    error_body: Dict[str, Any] = {"detail": detail}
+
+    if extra is not None:
+        error_body["extra"] = extra
+
+    body_bytes = msgspec.json.encode(error_body)
+
+    response_headers = [("content-type", "application/json")]
+    if headers:
+        response_headers.extend(headers.items())
+
+    return status_code, response_headers, body_bytes
+
+
+def http_exception_handler(exc: HTTPException) -> Tuple[int, List[Tuple[str, str]], bytes]:
+    """Handle HTTPException and convert to error response.
+
+    Args:
+        exc: HTTPException instance
+
+    Returns:
+        Tuple of (status_code, headers, body)
+    """
+    return format_error_response(
+        status_code=exc.status_code,
+        detail=exc.detail,
+        headers=exc.headers,
+        extra=exc.extra,
+    )
+
+
+def msgspec_validation_error_to_dict(error: msgspec.ValidationError) -> List[Dict[str, Any]]:
+    """Convert msgspec ValidationError to structured error list.
+
+    Args:
+        error: msgspec.ValidationError instance
+
+    Returns:
+        List of error dictionaries with 'loc', 'msg', 'type' fields
+    """
+    # msgspec.ValidationError doesn't provide structured error info like pydantic
+    # We'll do our best to parse the error message
+    error_msg = str(error)
+
+    # Try to extract field path from error message
+    # Example: "Expected `int`, got `str` - at `$[0].age`"
+    # Example: "Object missing required field `name`"
+
+    errors = []
+
+    # Check if error message contains field location
+    if " - at `" in error_msg:
+        msg_part, loc_part = error_msg.split(" - at `", 1)
+        loc_path = loc_part.rstrip("`")
+        # Parse location like $[0].age into ["body", 0, "age"]
+        loc_parts = ["body"]
+        # Simple parsing - can be improved
+        loc_parts.append(loc_path.replace("$", "").replace("[", ".").replace("]", "").strip("."))
+    elif "missing required field" in error_msg.lower():
+        # Extract field name from message
+        import re
+        match = re.search(r"`(\w+)`", error_msg)
+        field = match.group(1) if match else "unknown"
+        errors.append({
+            "loc": ["body", field],
+            "msg": error_msg,
+            "type": "missing_field",
+        })
+        return errors
+    else:
+        # Generic error without location
+        errors.append({
+            "loc": ["body"],
+            "msg": error_msg,
+            "type": "validation_error",
+        })
+        return errors
+
+    errors.append({
+        "loc": loc_parts if isinstance(loc_parts, list) else ["body"],
+        "msg": error_msg.split(" - at `")[0] if " - at `" in error_msg else error_msg,
+        "type": "validation_error",
+    })
+
+    return errors
+
+
+def request_validation_error_handler(
+    exc: RequestValidationError,
+) -> Tuple[int, List[Tuple[str, str]], bytes]:
+    """Handle RequestValidationError and convert to 422 response.
+
+    Args:
+        exc: RequestValidationError instance
+
+    Returns:
+        Tuple of (status_code, headers, body)
+    """
+    errors = exc.errors()
+
+    # Convert errors to structured format if needed
+    formatted_errors = []
+    for error in errors:
+        if isinstance(error, dict):
+            formatted_errors.append(error)
+        elif isinstance(error, msgspec.ValidationError):
+            formatted_errors.extend(msgspec_validation_error_to_dict(error))
+        else:
+            # Generic error
+            formatted_errors.append({
+                "loc": ["body"],
+                "msg": str(error),
+                "type": "validation_error",
+            })
+
+    return format_error_response(
+        status_code=422,
+        detail=formatted_errors,
+    )
+
+
+def response_validation_error_handler(
+    exc: ResponseValidationError,
+) -> Tuple[int, List[Tuple[str, str]], bytes]:
+    """Handle ResponseValidationError and convert to 500 response.
+
+    Args:
+        exc: ResponseValidationError instance
+
+    Returns:
+        Tuple of (status_code, headers, body)
+    """
+    # Log the error (if logging is configured)
+    errors = exc.errors()
+
+    formatted_errors = []
+    for error in errors:
+        if isinstance(error, dict):
+            formatted_errors.append(error)
+        elif isinstance(error, msgspec.ValidationError):
+            formatted_errors.extend(msgspec_validation_error_to_dict(error))
+        else:
+            formatted_errors.append({
+                "loc": ["response"],
+                "msg": str(error),
+                "type": "validation_error",
+            })
+
+    return format_error_response(
+        status_code=500,
+        detail="Response validation error",
+        extra={"validation_errors": formatted_errors},
+    )
+
+
+def generic_exception_handler(
+    exc: Exception,
+    debug: bool = False,
+    request: Optional[Any] = None,  # noqa: ARG001 - kept for API compatibility
+) -> Tuple[int, List[Tuple[str, str]], bytes]:
+    """Handle generic exceptions and convert to 500 response.
+
+    Args:
+        exc: Exception instance
+        debug: Whether to include traceback in response
+        request: Optional request dict or Django request object for ExceptionReporter
+
+    Returns:
+        Tuple of (status_code, headers, body)
+    """
+    detail = "Internal Server Error"
+    extra = None
+
+    if debug:
+        # Try to use Django's ExceptionReporter HTML page
+        try:
+            from django.views.debug import ExceptionReporter
+
+            # ExceptionReporter works fine with None request (avoids URL resolution issues)
+            reporter = ExceptionReporter(None, type(exc), exc, exc.__traceback__)
+            html_content = reporter.get_traceback_html()
+
+            # Return HTML response instead of JSON
+            return (
+                500,
+                [("content-type", "text/html; charset=utf-8")],
+                html_content.encode("utf-8")
+            )
+        except Exception:
+            # Fallback to standard traceback formatting in JSON
+            pass
+
+        # Fallback to JSON with traceback
+        tb_lines = traceback.format_exception(type(exc), exc, exc.__traceback__)
+        # Split into individual lines for better JSON display, stripping trailing newlines
+        tb_formatted = [line.rstrip('\n') for line in ''.join(tb_lines).split('\n') if line.strip()]
+        extra = {
+            "exception": str(exc),
+            "exception_type": type(exc).__name__,
+            "traceback": tb_formatted,
+        }
+        detail = f"{type(exc).__name__}: {str(exc)}"
+
+    return format_error_response(
+        status_code=500,
+        detail=detail,
+        extra=extra,
+    )
+
+
+def handle_exception(
+    exc: Exception,
+    debug: Optional[bool] = None,
+    request: Optional[Any] = None,
+) -> Tuple[int, List[Tuple[str, str]], bytes]:
+    """Main exception handler that routes to specific handlers.
+
+    Args:
+        exc: Exception instance
+        debug: Whether to include debug information. If None, will check Django DEBUG setting.
+              If explicitly False, will not show debug info even if Django DEBUG=True.
+        request: Optional request object for Django ExceptionReporter
+
+    Returns:
+        Tuple of (status_code, headers, body)
+    """
+    # Check Django's DEBUG setting dynamically only if debug is not explicitly set
+    if debug is None:
+        try:
+            from django.conf import settings
+            if settings.configured:
+                debug = settings.DEBUG
+            else:
+                debug = False
+        except (ImportError, AttributeError):
+            debug = False
+
+    if isinstance(exc, HTTPException):
+        return http_exception_handler(exc)
+    elif isinstance(exc, RequestValidationError):
+        return request_validation_error_handler(exc)
+    elif isinstance(exc, ResponseValidationError):
+        return response_validation_error_handler(exc)
+    elif isinstance(exc, ValidationException):
+        # Generic validation exception
+        return request_validation_error_handler(
+            RequestValidationError(exc.errors())
+        )
+    elif isinstance(exc, msgspec.ValidationError):
+        # Direct msgspec validation error
+        errors = msgspec_validation_error_to_dict(exc)
+        return format_error_response(
+            status_code=422,
+            detail=errors,
+        )
+    elif isinstance(exc, FileNotFoundError):
+        # FileNotFoundError from FileResponse - return 404
+        return format_error_response(
+            status_code=404,
+            detail=str(exc) or "File not found",
+        )
+    elif isinstance(exc, PermissionError):
+        # PermissionError from FileResponse path validation - return 403
+        return format_error_response(
+            status_code=403,
+            detail=str(exc) or "Permission denied",
+        )
+    else:
+        # Generic exception
+        return generic_exception_handler(exc, debug=debug, request=request)