django-bolt 0.4.2__cp312-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl

django_bolt/__init__.py

@@ -0,0 +1,256 @@
+"""
+Django-Bolt: High-performance API framework for Django.
+
+Provides Rust-powered API endpoints with 60k+ RPS performance, integrating
+with existing Django projects via Actix Web, PyO3, and msgspec.
+
+Quick Start:
+    from django_bolt import BoltAPI, Request
+
+    api = BoltAPI()
+
+    @api.get("/hello")
+    async def hello(request: Request) -> dict:
+        return {"message": "Hello, World!"}
+
+Type-Safe Requests:
+    from django_bolt import BoltAPI, Request
+    from django_bolt.types import JWTClaims
+    from myapp.models import User
+
+    api = BoltAPI()
+
+    @api.get("/profile", guards=[IsAuthenticated()])
+    async def profile(request: Request[User, JWTClaims, dict]) -> dict:
+        return {"email": request.user.email}  # IDE knows User has email
+
+Middleware:
+    from django_bolt import BoltAPI
+    from django_bolt.middleware import (
+        DjangoMiddleware,
+        TimingMiddleware,
+        LoggingMiddleware,
+    )
+    from django.contrib.sessions.middleware import SessionMiddleware
+    from django.contrib.auth.middleware import AuthenticationMiddleware
+
+    api = BoltAPI(
+        middleware=[
+            DjangoMiddleware(SessionMiddleware),
+            DjangoMiddleware(AuthenticationMiddleware),
+            TimingMiddleware(),
+            LoggingMiddleware(),
+        ]
+    )
+"""
+
+from .api import BoltAPI
+
+# Auth module
+from .auth import (
+    # Guards/Permissions
+    AllowAny,
+    APIKeyAuthentication,
+    AuthContext,
+    HasAllPermissions,
+    HasAnyPermission,
+    HasPermission,
+    IsAdminUser,
+    IsAuthenticated,
+    IsStaff,
+    # Authentication backends
+    JWTAuthentication,
+    SessionAuthentication,
+    # JWT Token & Utilities
+    Token,
+    create_jwt_for_user,
+    extract_user_id_from_context,
+    get_auth_context,
+    get_current_user,
+)
+
+# Decorators module
+from .decorators import action
+
+# Middleware module
+from .middleware import (
+    BaseMiddleware,
+    CompressionConfig,
+    # Django compatibility
+    DjangoMiddleware,
+    ErrorHandlerMiddleware,
+    LoggingMiddleware,
+    Middleware,
+    # Protocols and base classes
+    MiddlewareProtocol,
+    # Built-in middleware (Python)
+    TimingMiddleware,
+    cors,
+    # Decorators
+    middleware,
+    no_compress,
+    rate_limit,
+    skip_middleware,
+)
+
+# OpenAPI module
+from .openapi import (
+    JsonRenderPlugin,
+    OpenAPIConfig,
+    RapidocRenderPlugin,
+    RedocRenderPlugin,
+    ScalarRenderPlugin,
+    StoplightRenderPlugin,
+    SwaggerRenderPlugin,
+    YamlRenderPlugin,
+)
+
+# Pagination module
+from .pagination import (
+    CursorPagination,
+    LimitOffsetPagination,
+    PageNumberPagination,
+    PaginatedResponse,
+    PaginationBase,
+    paginate,
+)
+from .params import Depends
+
+# Type-safe Request object
+from .request import Request
+from .responses import JSON, Response, StreamingResponse
+from .router import Router
+from .types import (
+    APIKeyAuth,
+    DjangoModel,
+    JWTClaims,
+    SessionAuth,
+    TimingState,
+    TracingState,
+    UserType,
+)
+
+# Types and protocols
+from .types import (
+    Request as RequestProtocol,  # Protocol for type checking
+)
+
+# Views module
+from .views import (
+    APIView,
+    CreateMixin,
+    DestroyMixin,
+    ListMixin,
+    ModelViewSet,
+    PartialUpdateMixin,
+    ReadOnlyModelViewSet,
+    RetrieveMixin,
+    UpdateMixin,
+    ViewSet,
+)
+
+# WebSocket module
+from .websocket import (
+    CloseCode,
+    WebSocket,
+    WebSocketClose,
+    WebSocketDisconnect,
+    WebSocketException,
+    WebSocketState,
+)
+
+__all__ = [
+    # Core
+    "BoltAPI",
+    "Request",
+    "Response",
+    "JSON",
+    "StreamingResponse",
+    "CompressionConfig",
+    "Depends",
+    # Router
+    "Router",
+    # Types
+    "RequestProtocol",
+    "UserType",
+    "AuthContext",
+    "DjangoModel",
+    "JWTClaims",
+    "APIKeyAuth",
+    "SessionAuth",
+    "TimingState",
+    "TracingState",
+    # Views
+    "APIView",
+    "ViewSet",
+    "ModelViewSet",
+    "ReadOnlyModelViewSet",
+    "ListMixin",
+    "RetrieveMixin",
+    "CreateMixin",
+    "UpdateMixin",
+    "PartialUpdateMixin",
+    "DestroyMixin",
+    # Pagination
+    "PaginationBase",
+    "PageNumberPagination",
+    "LimitOffsetPagination",
+    "CursorPagination",
+    "PaginatedResponse",
+    "paginate",
+    # Decorators
+    "action",
+    # Auth - Authentication
+    "JWTAuthentication",
+    "APIKeyAuthentication",
+    "SessionAuthentication",
+    "AuthContext",
+    # Auth - Guards/Permissions
+    "AllowAny",
+    "IsAuthenticated",
+    "IsAdminUser",
+    "IsStaff",
+    "HasPermission",
+    "HasAnyPermission",
+    "HasAllPermissions",
+    # Middleware - Protocols and base classes
+    "MiddlewareProtocol",
+    "BaseMiddleware",
+    "Middleware",
+    # Middleware - Decorators
+    "middleware",
+    "rate_limit",
+    "cors",
+    "skip_middleware",
+    "no_compress",
+    # Middleware - Built-in (Python)
+    "TimingMiddleware",
+    "LoggingMiddleware",
+    "ErrorHandlerMiddleware",
+    # Middleware - Django compatibility
+    "DjangoMiddleware",
+    # Auth - JWT Token & Utilities
+    "Token",
+    "create_jwt_for_user",
+    "get_current_user",
+    "extract_user_id_from_context",
+    "get_auth_context",
+    # OpenAPI
+    "OpenAPIConfig",
+    "SwaggerRenderPlugin",
+    "RedocRenderPlugin",
+    "ScalarRenderPlugin",
+    "RapidocRenderPlugin",
+    "StoplightRenderPlugin",
+    "JsonRenderPlugin",
+    "YamlRenderPlugin",
+    # WebSocket
+    "WebSocket",
+    "WebSocketState",
+    "WebSocketDisconnect",
+    "WebSocketClose",
+    "WebSocketException",
+    "CloseCode",
+]
+
+default_app_config = 'django_bolt.apps.DjangoBoltConfig'

django_bolt/_json.py

@@ -0,0 +1,174 @@
+"""Fast JSON helpers backed by cached msgspec Encoder/Decoder.
+
+This module provides optimized JSON encoding/decoding using msgspec with:
+- Thread-local cached encoder/decoder instances (thread-safe buffer reuse)
+- Support for common non-JSON-native types (datetime, Path, Decimal, UUID, IP addresses)
+- Automatic Serializer.dump() for write_only, computed_field support
+- Type-safe decoding with validation
+- Custom encoder/decoder hooks
+
+Inspired by Litestar's serialization approach.
+"""
+
+from __future__ import annotations
+
+import threading
+from collections.abc import Callable
+from datetime import date, datetime, time
+from decimal import Decimal
+from ipaddress import (
+    IPv4Address,
+    IPv4Interface,
+    IPv4Network,
+    IPv6Address,
+    IPv6Interface,
+    IPv6Network,
+)
+from pathlib import Path, PurePath
+from typing import Any, TypeVar
+from uuid import UUID
+
+import msgspec
+
+T = TypeVar("T")
+
+# Thread-local storage for encoder/decoder instances
+_thread_local = threading.local()
+
+# Default type encoders for non-JSON-native types
+# Maps type -> encoder function
+DEFAULT_TYPE_ENCODERS: dict[type, Callable[[Any], Any]] = {
+    # Paths
+    Path: str,
+    PurePath: str,
+    # Dates/Times -> ISO format
+    datetime: lambda v: v.isoformat(),
+    date: lambda v: v.isoformat(),
+    time: lambda v: v.isoformat(),
+    # Decimals -> int or float
+    Decimal: lambda v: int(v) if v.as_tuple().exponent >= 0 else float(v),
+    # IP addresses
+    IPv4Address: str,
+    IPv4Interface: str,
+    IPv4Network: str,
+    IPv6Address: str,
+    IPv6Interface: str,
+    IPv6Network: str,
+    # UUID
+    UUID: str,
+
+}
+
+
+def default_serializer(value: Any) -> Any:
+    """Transform values non-natively supported by msgspec.
+
+    Walks the MRO (Method Resolution Order) to support subclasses.
+    Raises TypeError if type is unsupported.
+
+    Note: Serializer instances are handled in serialization.py before reaching
+    this hook, since msgspec.Struct is natively supported by msgspec.
+    """
+    # Walk MRO to support polymorphic types
+    for base in value.__class__.__mro__[:-1]:  # Skip 'object'
+        encoder = DEFAULT_TYPE_ENCODERS.get(base)
+        if encoder is not None:
+            return encoder(value)
+
+    raise TypeError(f"Unsupported type: {type(value)!r}")
+
+
+def _get_encoder() -> msgspec.json.Encoder:
+    """Return a thread-local msgspec JSON Encoder instance.
+
+    Using a per-thread encoder is thread-safe and avoids cross-thread contention
+    while still reusing the internal buffer for repeated encodes on the same thread.
+    """
+    encoder = getattr(_thread_local, "encoder", None)
+    if encoder is None:
+        encoder = msgspec.json.Encoder(enc_hook=default_serializer)
+        _thread_local.encoder = encoder
+    return encoder
+
+
+def _get_decoder() -> msgspec.json.Decoder:
+    """Return a thread-local msgspec JSON Decoder instance.
+
+    Using a per-thread decoder is thread-safe and reuses the internal buffer.
+    """
+    decoder = getattr(_thread_local, "decoder", None)
+    if decoder is None:
+        decoder = msgspec.json.Decoder()
+        _thread_local.decoder = decoder
+    return decoder
+
+
+def encode(value: Any, serializer: Callable[[Any], Any] | None = None) -> bytes:
+    """Encode a Python object to JSON bytes.
+
+    Args:
+        value: Object to encode
+        serializer: Optional custom encoder hook (overrides default)
+
+    Returns:
+        JSON bytes
+
+    Raises:
+        TypeError: If value contains unsupported types
+        msgspec.EncodeError: If encoding fails
+    """
+    if serializer is not None:
+        # Custom serializer provided - use one-off encoder
+        return msgspec.json.encode(value, enc_hook=serializer)
+
+    # Use thread-local cached encoder with default serializer
+    return _get_encoder().encode(value)
+
+
+def decode(value: bytes | str) -> Any:
+    """Decode JSON bytes/string to Python object.
+
+    Args:
+        value: JSON bytes or string
+
+    Returns:
+        Decoded Python object
+
+    Raises:
+        msgspec.DecodeError: If decoding fails
+    """
+    return _get_decoder().decode(value)
+
+
+def decode_typed[T](
+    value: bytes | str,
+    target_type: type[T],
+    strict: bool = True,
+) -> T:
+    """Decode JSON with type validation and coercion.
+
+    Args:
+        value: JSON bytes or string
+        target_type: Expected type (e.g., msgspec.Struct subclass)
+        strict: If False, enables lenient type coercion (e.g., "123" -> 123)
+
+    Returns:
+        Decoded and validated object of target_type
+
+    Raises:
+        msgspec.DecodeError: If decoding or validation fails
+        msgspec.ValidationError: If type validation fails
+
+    Examples:
+        >>> class User(msgspec.Struct):
+        ...     id: int
+        ...     name: str
+        >>> decode_typed(b'{"id": 1, "name": "Alice"}', User)
+        User(id=1, name='Alice')
+    """
+    return msgspec.json.decode(value, type=target_type, strict=strict)
+
+
+__all__ = ["encode", "decode", "decode_typed", "DEFAULT_TYPE_ENCODERS", "default_serializer"]
+
+

django_bolt/admin/__init__.py

@@ -0,0 +1,24 @@
+"""
+Django admin integration for django-bolt.
+
+This module provides ASGI bridge functionality to integrate Django's admin
+interface with django-bolt's high-performance routing system.
+"""
+
+from .admin_detection import (
+    detect_admin_url_prefix,
+    get_admin_info,
+    get_admin_route_patterns,
+    is_admin_installed,
+    should_enable_admin,
+)
+from .asgi_bridge import ASGIFallbackHandler
+
+__all__ = [
+    "is_admin_installed",
+    "detect_admin_url_prefix",
+    "get_admin_route_patterns",
+    "should_enable_admin",
+    "get_admin_info",
+    "ASGIFallbackHandler",
+]

django_bolt/admin/admin_detection.py

@@ -0,0 +1,182 @@
+"""
+Utilities for detecting and configuring Django admin integration.
+"""
+
+import logging
+import sys
+
+from django.conf import settings
+from django.urls import get_resolver
+
+logger = logging.getLogger(__name__)
+
+
+def is_admin_installed() -> bool:
+    """
+    Check if Django admin is installed and configured.
+
+    Returns:
+        True if admin is in INSTALLED_APPS, False otherwise
+    """
+    try:
+        return 'django.contrib.admin' in settings.INSTALLED_APPS
+    except Exception:
+        return False
+
+
+def detect_admin_url_prefix() -> str | None:
+    """
+    Detect the URL prefix for Django admin by parsing urlpatterns.
+
+    Returns:
+        Admin URL prefix (e.g., 'admin' or 'dashboard') or None if not found
+    """
+    if not is_admin_installed():
+        return None
+
+    try:
+        # Get root URL resolver
+        resolver = get_resolver(getattr(settings, 'ROOT_URLCONF', None))
+
+        # Search for admin patterns
+        for url_pattern in resolver.url_patterns:
+            # Check if this is admin.site.urls
+            if hasattr(url_pattern, 'app_name') and url_pattern.app_name == 'admin':
+                # Extract the pattern prefix
+                pattern_str = str(url_pattern.pattern)
+                # Remove trailing slash and special regex chars
+                prefix = pattern_str.rstrip('/^$')
+                return prefix if prefix else 'admin'
+
+            # Also check URLResolver with admin urlconf
+            if hasattr(url_pattern, 'urlconf_name'):
+                urlconf = url_pattern.urlconf_name
+                # Check if urlconf module contains admin.site
+                if hasattr(urlconf, '__name__') and 'admin' in str(urlconf.__name__):
+                    pattern_str = str(url_pattern.pattern)
+                    prefix = pattern_str.rstrip('/^$')
+                    return prefix if prefix else 'admin'
+
+                # Check if urlconf is a list containing admin patterns
+                if isinstance(urlconf, (list, tuple)):
+                    for sub_pattern in urlconf:
+                        if hasattr(sub_pattern, 'callback') and hasattr(sub_pattern.callback, '__module__') and 'admin' in sub_pattern.callback.__module__:
+                            pattern_str = str(url_pattern.pattern)
+                            prefix = pattern_str.rstrip('/^$')
+                            return prefix if prefix else 'admin'
+
+    except Exception as e:
+        # If detection fails, log warning and return default
+        print(f"[django-bolt] Warning: Could not auto-detect admin URL prefix: {e}", file=sys.stderr)
+
+    # Default fallback
+    return 'admin'
+
+
+def get_admin_route_patterns() -> list[tuple[str, list[str]]]:
+    """
+    Get route patterns to register for Django admin.
+
+    Returns:
+        List of (path_pattern, methods) tuples for admin routes
+        Example: [('/admin/{path:path}', ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'])]
+    """
+    if not is_admin_installed():
+        return []
+
+    # Detect admin URL prefix
+    admin_prefix = detect_admin_url_prefix()
+    if not admin_prefix:
+        return []
+
+    # Build catch-all pattern for admin routes
+    # Use {path:path} syntax for catch-all parameter
+    admin_pattern = f'/{admin_prefix}/{{path:path}}'
+
+    # Admin needs to handle common HTTP methods
+    # Only use methods supported by django-bolt's router (GET, POST, PUT, PATCH, DELETE)
+    methods = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH']
+
+    # Also add exact /admin route (without trailing slash)
+    # NOTE: NormalizePath::trim() in Rust strips trailing slashes from incoming requests,
+    # so we register routes WITHOUT trailing slashes to match the normalized paths.
+    # However, for TestClient with use_http_layer=True, we also need the trailing slash version.
+    admin_root = f'/{admin_prefix}'
+    admin_root_slash = f'/{admin_prefix}/'
+
+    return [
+        (admin_root, methods),
+        (admin_root_slash, methods),
+        (admin_pattern, methods),
+    ]
+
+
+def get_static_url_prefix() -> str | None:
+    """
+    Get the STATIC_URL prefix from Django settings.
+
+    Returns:
+        Static URL prefix (e.g., 'static') or None if not configured
+    """
+    try:
+        if hasattr(settings, 'STATIC_URL') and settings.STATIC_URL:
+            static_url = settings.STATIC_URL
+            # Remove leading/trailing slashes
+            return static_url.strip('/')
+    except Exception as e:
+        logger.warning(
+            "Failed to get STATIC_URL from Django settings. "
+            "Static file serving may not work correctly. Error: %s",
+            e
+        )
+
+    return None
+
+
+def should_enable_admin() -> bool:
+    """
+    Determine if admin should be auto-enabled.
+
+    Returns:
+        True if admin is installed and can be enabled, False otherwise
+    """
+    if not is_admin_installed():
+        return False
+
+    # Check if required dependencies are installed
+    try:
+        required_apps = [
+            'django.contrib.auth',
+            'django.contrib.contenttypes',
+            'django.contrib.sessions',
+        ]
+
+        for app in required_apps:
+            if app not in settings.INSTALLED_APPS:
+                print(
+                    f"[django-bolt] Warning: Django admin is installed but {app} is missing. "
+                    f"Admin integration disabled.",
+                    file=sys.stderr
+                )
+                return False
+
+        return True
+
+    except Exception as e:
+        print(f"[django-bolt] Warning: Could not check admin dependencies: {e}", file=sys.stderr)
+        return False
+
+
+def get_admin_info() -> dict:
+    """
+    Get information about Django admin configuration.
+
+    Returns:
+        Dict with admin configuration details
+    """
+    return {
+        'installed': is_admin_installed(),
+        'enabled': should_enable_admin(),
+        'url_prefix': detect_admin_url_prefix(),
+        'static_url': get_static_url_prefix(),
+    }