django-bolt 0.1.0__cp310-abi3-win_amd64.whl → 0.1.2__cp310-abi3-win_amd64.whl

django_bolt/__init__.py

@@ -34,7 +34,7 @@ from .auth import (
     # Authentication backends
     JWTAuthentication,
     APIKeyAuthentication,
-    SessionAuthentication,
+    SessionAuthentication, # Session authentication is not implemented
     AuthContext,
     # Guards/Permissions
     AllowAny,
@@ -107,7 +107,7 @@ __all__ = [
     # Auth - Authentication
     "JWTAuthentication",
     "APIKeyAuthentication",
-    "SessionAuthentication",
+    "SessionAuthentication", # Session authentication is not implemented
     "AuthContext",
     # Auth - Guards/Permissions
     "AllowAny",

django_bolt/_json.py

@@ -0,0 +1,169 @@
+"""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)
+- Type-safe decoding with validation
+- Custom encoder/decoder hooks
+
+Inspired by Litestar's serialization approach.
+"""
+
+from __future__ import annotations
+
+import threading
+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, Callable, 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.
+    """
+    # 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(
+    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/static_routes.py

@@ -81,31 +81,25 @@ class StaticRouteRegistrar:
         self.api._handlers[handler_id] = handler
 
         # Create metadata for static handler
-        # Extract path parameter metadata
+        # Extract path parameter metadata using FieldDefinition
+        from django_bolt.typing import FieldDefinition
+
         sig = inspect.signature(handler)
+        path_field = FieldDefinition(
+            name="path",
+            annotation=str,
+            default=inspect.Parameter.empty,
+            source="path",
+            alias=None,
+            embed=False,
+            dependency=None,
+            kind=inspect.Parameter.POSITIONAL_OR_KEYWORD,
+        )
+
         meta = {
             "mode": "mixed",
             "sig": sig,
-            "fields": [{
-                "name": "path",
-                "annotation": str,
-                "default": inspect.Parameter.empty,
-                "kind": inspect.Parameter.POSITIONAL_OR_KEYWORD,
-                "source": "path",
-                "alias": None,
-                "embed": False,
-                "dependency": None,
-            }],
+            "fields": [path_field],
             "path_params": {"path"},
-            "params": [{
-                "name": "path",
-                "annotation": str,
-                "default": inspect.Parameter.empty,
-                "kind": inspect.Parameter.POSITIONAL_OR_KEYWORD,
-                "source": "path",
-                "alias": None,
-                "embed": False,
-                "dependency": None,
-            }],
         }
         self.api._handler_meta[handler] = meta

django_bolt/api.py

@@ -18,7 +18,7 @@ from .binding import (
     convert_primitive,
     create_extractor,
 )
-from .typing import is_msgspec_struct, is_optional
+from .typing import is_msgspec_struct, is_optional, unwrap_optional
 from .request_parsing import parse_form_data
 from .dependencies import resolve_dependency
 from .serialization import serialize_response
@@ -43,7 +43,7 @@ def _extract_path_params(path: str) -> set[str]:
 
 
 def extract_parameter_value(
-    param: Dict[str, Any],
+    field: "FieldDefinition",
     request: Dict[str, Any],
     params_map: Dict[str, Any],
     query_map: Dict[str, Any],
@@ -56,16 +56,29 @@ def extract_parameter_value(
     body_loaded: bool
 ) -> Tuple[Any, Any, bool]:
     """
-    Extract value for a handler parameter (backward compatibility function).
-
-    This function maintains backward compatibility while using the new
-    extractor-based system internally.
+    Extract value for a handler parameter using FieldDefinition.
+
+    Args:
+        field: FieldDefinition object describing the parameter
+        request: Request dictionary
+        params_map: Path parameters
+        query_map: Query parameters
+        headers_map: Request headers
+        cookies_map: Request cookies
+        form_map: Form data
+        files_map: Uploaded files
+        meta: Handler metadata
+        body_obj: Cached body object
+        body_loaded: Whether body has been loaded
+
+    Returns:
+        Tuple of (value, body_obj, body_loaded)
     """
-    name = param["name"]
-    annotation = param["annotation"]
-    default = param["default"]
-    source = param["source"]
-    alias = param.get("alias")
+    name = field.name
+    annotation = field.annotation
+    default = field.default
+    source = field.source
+    alias = field.alias
     key = alias or name
 
     # Handle different sources
@@ -105,7 +118,32 @@ def extract_parameter_value(
 
     elif source == "file":
         if key in files_map:
-            return files_map[key], body_obj, body_loaded
+            file_info = files_map[key]
+            # Extract appropriate value based on annotation type
+            unwrapped_type = unwrap_optional(annotation) if is_optional(annotation) else annotation
+
+            # Get the origin type (list, dict, etc.)
+            origin = get_origin(unwrapped_type)
+
+            if unwrapped_type is bytes:
+                # For bytes annotation, extract content from single file
+                if isinstance(file_info, list):
+                    # Multiple files, but bytes expects single - take first
+                    return file_info[0].get("content", b""), body_obj, body_loaded
+                return file_info.get("content", b""), body_obj, body_loaded
+            elif origin is list:
+                # For list annotation, ensure value is a list
+                if isinstance(file_info, list):
+                    return file_info, body_obj, body_loaded
+                else:
+                    # Wrap single file in list
+                    return [file_info], body_obj, body_loaded
+            else:
+                # Return full file info for dict/Any annotations
+                if isinstance(file_info, list):
+                    # List but annotation doesn't expect list - take first
+                    return file_info[0], body_obj, body_loaded
+                return file_info, body_obj, body_loaded
         elif default is not inspect.Parameter.empty or is_optional(annotation):
             return (None if default is inspect.Parameter.empty else default), body_obj, body_loaded
         raise ValueError(f"Missing required file: {key}")
@@ -247,26 +285,103 @@ class BoltAPI:
         # Register this instance globally for autodiscovery
         _BOLT_API_REGISTRY.append(self)
 
-    def get(self, path: str, *, response_model: Optional[Any] = None, status_code: Optional[int] = None, guards: Optional[List[Any]] = None, auth: Optional[List[Any]] = None):
-        return self._route_decorator("GET", path, response_model=response_model, status_code=status_code, guards=guards, auth=auth)
+    def get(
+        self,
+        path: str,
+        *,
+        response_model: Optional[Any] = None,
+        status_code: Optional[int] = None,
+        guards: Optional[List[Any]] = None,
+        auth: Optional[List[Any]] = None,
+        tags: Optional[List[str]] = None,
+        summary: Optional[str] = None,
+        description: Optional[str] = None,
+    ):
+        return self._route_decorator("GET", path, response_model=response_model, status_code=status_code, guards=guards, auth=auth, tags=tags, summary=summary, description=description)
 
-    def post(self, path: str, *, response_model: Optional[Any] = None, status_code: Optional[int] = None, guards: Optional[List[Any]] = None, auth: Optional[List[Any]] = None):
-        return self._route_decorator("POST", path, response_model=response_model, status_code=status_code, guards=guards, auth=auth)
+    def post(
+        self,
+        path: str,
+        *,
+        response_model: Optional[Any] = None,
+        status_code: Optional[int] = None,
+        guards: Optional[List[Any]] = None,
+        auth: Optional[List[Any]] = None,
+        tags: Optional[List[str]] = None,
+        summary: Optional[str] = None,
+        description: Optional[str] = None,
+    ):
+        return self._route_decorator("POST", path, response_model=response_model, status_code=status_code, guards=guards, auth=auth, tags=tags, summary=summary, description=description)
 
-    def put(self, path: str, *, response_model: Optional[Any] = None, status_code: Optional[int] = None, guards: Optional[List[Any]] = None, auth: Optional[List[Any]] = None):
-        return self._route_decorator("PUT", path, response_model=response_model, status_code=status_code, guards=guards, auth=auth)
+    def put(
+        self,
+        path: str,
+        *,
+        response_model: Optional[Any] = None,
+        status_code: Optional[int] = None,
+        guards: Optional[List[Any]] = None,
+        auth: Optional[List[Any]] = None,
+        tags: Optional[List[str]] = None,
+        summary: Optional[str] = None,
+        description: Optional[str] = None,
+    ):
+        return self._route_decorator("PUT", path, response_model=response_model, status_code=status_code, guards=guards, auth=auth, tags=tags, summary=summary, description=description)
 
-    def patch(self, path: str, *, response_model: Optional[Any] = None, status_code: Optional[int] = None, guards: Optional[List[Any]] = None, auth: Optional[List[Any]] = None):
-        return self._route_decorator("PATCH", path, response_model=response_model, status_code=status_code, guards=guards, auth=auth)
+    def patch(
+        self,
+        path: str,
+        *,
+        response_model: Optional[Any] = None,
+        status_code: Optional[int] = None,
+        guards: Optional[List[Any]] = None,
+        auth: Optional[List[Any]] = None,
+        tags: Optional[List[str]] = None,
+        summary: Optional[str] = None,
+        description: Optional[str] = None,
+    ):
+        return self._route_decorator("PATCH", path, response_model=response_model, status_code=status_code, guards=guards, auth=auth, tags=tags, summary=summary, description=description)
 
-    def delete(self, path: str, *, response_model: Optional[Any] = None, status_code: Optional[int] = None, guards: Optional[List[Any]] = None, auth: Optional[List[Any]] = None):
-        return self._route_decorator("DELETE", path, response_model=response_model, status_code=status_code, guards=guards, auth=auth)
+    def delete(
+        self,
+        path: str,
+        *,
+        response_model: Optional[Any] = None,
+        status_code: Optional[int] = None,
+        guards: Optional[List[Any]] = None,
+        auth: Optional[List[Any]] = None,
+        tags: Optional[List[str]] = None,
+        summary: Optional[str] = None,
+        description: Optional[str] = None,
+    ):
+        return self._route_decorator("DELETE", path, response_model=response_model, status_code=status_code, guards=guards, auth=auth, tags=tags, summary=summary, description=description)
 
-    def head(self, path: str, *, response_model: Optional[Any] = None, status_code: Optional[int] = None, guards: Optional[List[Any]] = None, auth: Optional[List[Any]] = None):
-        return self._route_decorator("HEAD", path, response_model=response_model, status_code=status_code, guards=guards, auth=auth)
+    def head(
+        self,
+        path: str,
+        *,
+        response_model: Optional[Any] = None,
+        status_code: Optional[int] = None,
+        guards: Optional[List[Any]] = None,
+        auth: Optional[List[Any]] = None,
+        tags: Optional[List[str]] = None,
+        summary: Optional[str] = None,
+        description: Optional[str] = None,
+    ):
+        return self._route_decorator("HEAD", path, response_model=response_model, status_code=status_code, guards=guards, auth=auth, tags=tags, summary=summary, description=description)
 
-    def options(self, path: str, *, response_model: Optional[Any] = None, status_code: Optional[int] = None, guards: Optional[List[Any]] = None, auth: Optional[List[Any]] = None):
-        return self._route_decorator("OPTIONS", path, response_model=response_model, status_code=status_code, guards=guards, auth=auth)
+    def options(
+        self,
+        path: str,
+        *,
+        response_model: Optional[Any] = None,
+        status_code: Optional[int] = None,
+        guards: Optional[List[Any]] = None,
+        auth: Optional[List[Any]] = None,
+        tags: Optional[List[str]] = None,
+        summary: Optional[str] = None,
+        description: Optional[str] = None,
+    ):
+        return self._route_decorator("OPTIONS", path, response_model=response_model, status_code=status_code, guards=guards, auth=auth, tags=tags, summary=summary, description=description)
 
     def view(
         self,
@@ -588,11 +703,26 @@ class BoltAPI:
                         response_model=attr.response_model,
                         status_code=attr.status_code,
                         guards=final_guards,
-                        auth=final_auth
+                        auth=final_auth,
+                        tags=attr.tags,
+                        summary=attr.summary,
+                        description=attr.description,
                     )
                     decorator(custom_action_handler)
 
-    def _route_decorator(self, method: str, path: str, *, response_model: Optional[Any] = None, status_code: Optional[int] = None, guards: Optional[List[Any]] = None, auth: Optional[List[Any]] = None):
+    def _route_decorator(
+        self,
+        method: str,
+        path: str,
+        *,
+        response_model: Optional[Any] = None,
+        status_code: Optional[int] = None,
+        guards: Optional[List[Any]] = None,
+        auth: Optional[List[Any]] = None,
+        tags: Optional[List[str]] = None,
+        summary: Optional[str] = None,
+        description: Optional[str] = None,
+    ):
         def decorator(fn: Callable):
             # Enforce async handlers
             if not inspect.iscoroutinefunction(fn):
@@ -614,6 +744,13 @@ class BoltAPI:
                 meta["response_type"] = response_model
             if status_code is not None:
                 meta["default_status_code"] = int(status_code)
+            # Store OpenAPI metadata
+            if tags is not None:
+                meta["openapi_tags"] = tags
+            if summary is not None:
+                meta["openapi_summary"] = summary
+            if description is not None:
+                meta["openapi_description"] = description
             self._handler_meta[fn] = meta
 
             # Compile middleware metadata for this handler (including guards and auth)
@@ -717,20 +854,8 @@ class BoltAPI:
                 f"  3. Use simple types (str, int) which auto-infer as query params"
             )
 
-        # Convert FieldDefinitions to dict format for backward compatibility
-        # (We'll optimize this away in Phase 4)
-        for field in field_definitions:
-            meta["fields"].append({
-                "name": field.name,
-                "annotation": field.annotation,
-                "default": field.default,
-                "kind": field.kind,
-                "source": field.source,
-                "alias": field.alias,
-                "embed": field.embed,
-                "dependency": field.dependency,
-                "field_def": field,  # Store FieldDefinition for future use
-            })
+        # Store FieldDefinition objects directly (Phase 4: completed migration)
+        meta["fields"] = field_definitions
 
         # Detect single body parameter for fast path
         if len(body_fields) == 1:
@@ -745,9 +870,6 @@ class BoltAPI:
 
         meta["mode"] = "mixed"
 
-        # Maintain backward compatibility with old "params" key
-        meta["params"] = meta["fields"]
-
         # Performance: Check if handler needs form/file parsing
         # This allows us to skip expensive form parsing for 95% of endpoints
         needs_form_parsing = any(f.source in ("form", "file") for f in field_definitions)
@@ -778,34 +900,31 @@ class BoltAPI:
         body_loaded: bool = False
         dep_cache: Dict[Any, Any] = {}
 
-        for p in meta["params"]:
-            name = p["name"]
-            source = p["source"]
-            depends_marker = p.get("dependency")
-
-            if source == "request":
+        # Use FieldDefinition objects directly
+        fields = meta["fields"]
+        for field in fields:
+            if field.source == "request":
                 value = request
-            elif source == "dependency":
-                dep_fn = depends_marker.dependency if depends_marker else None
-                if dep_fn is None:
-                    raise ValueError(f"Depends for parameter {name} requires a callable")
+            elif field.source == "dependency":
+                if field.dependency is None:
+                    raise ValueError(f"Depends for parameter {field.name} requires a callable")
                 value = await resolve_dependency(
-                    dep_fn, depends_marker, request, dep_cache,
+                    field.dependency.dependency, field.dependency, request, dep_cache,
                     params_map, query_map, headers_map, cookies_map,
                     self._handler_meta, self._compile_binder,
                     meta.get("http_method", ""), meta.get("path", "")
                 )
             else:
                 value, body_obj, body_loaded = extract_parameter_value(
-                    p, request, params_map, query_map, headers_map, cookies_map,
+                    field, request, params_map, query_map, headers_map, cookies_map,
                     form_map, files_map, meta, body_obj, body_loaded
                 )
 
             # Respect positional-only/keyword-only kinds
-            if p["kind"] in (inspect.Parameter.POSITIONAL_ONLY, inspect.Parameter.POSITIONAL_OR_KEYWORD):
+            if field.kind in (inspect.Parameter.POSITIONAL_ONLY, inspect.Parameter.POSITIONAL_OR_KEYWORD):
                 args.append(value)
             else:
-                kwargs[name] = value
+                kwargs[field.name] = value
 
         return args, kwargs
 
@@ -813,7 +932,8 @@ class BoltAPI:
     def _handle_http_exception(self, he: HTTPException) -> Response:
         """Handle HTTPException and return response."""
         try:
-            body = msgspec.json.encode({"detail": he.detail})
+            from . import _json
+            body = _json.encode({"detail": he.detail})
             headers = [("content-type", "application/json")]
         except Exception:
             body = str(he.detail).encode()
@@ -828,7 +948,7 @@ class BoltAPI:
         """Handle generic exception using error_handlers module."""
         from . import error_handlers
         # Use the error handler which respects Django DEBUG setting
-        return error_handlers.handle_exception(e, debug=False, request=request)  # debug will be checked dynamically
+        return error_handlers.handle_exception(e, debug=None, request=request)  # debug will be checked dynamically
 
     async def _dispatch(self, handler: Callable, request: Dict[str, Any], handler_id: int = None) -> Response:
         """Async dispatch that calls the handler and returns response tuple.

django_bolt/auth/__init__.py

@@ -10,7 +10,7 @@ from .backends import (
     BaseAuthentication,
     JWTAuthentication,
     APIKeyAuthentication,
-    SessionAuthentication,
+    SessionAuthentication, # Session authentication is not implemented
     AuthContext,
     get_default_authentication_classes,
 )
@@ -53,7 +53,7 @@ __all__ = [
     "BaseAuthentication",
     "JWTAuthentication",
     "APIKeyAuthentication",
-    "SessionAuthentication",
+    "SessionAuthentication", # Session authentication is not implemented
     "AuthContext",
     "get_default_authentication_classes",
 

django_bolt/decorators.py

@@ -27,7 +27,7 @@ class ActionHandler:
         status_code: Optional HTTP status code
     """
 
-    __slots__ = ('fn', 'methods', 'detail', 'path', 'auth', 'guards', 'response_model', 'status_code')
+    __slots__ = ('fn', 'methods', 'detail', 'path', 'auth', 'guards', 'response_model', 'status_code', 'tags', 'summary', 'description')
 
     def __init__(
         self,
@@ -39,6 +39,9 @@ class ActionHandler:
         guards: Optional[List[Any]] = None,
         response_model: Optional[Any] = None,
         status_code: Optional[int] = None,
+        tags: Optional[List[str]] = None,
+        summary: Optional[str] = None,
+        description: Optional[str] = None,
     ):
         self.fn = fn
         self.methods = [m.upper() for m in methods]  # Normalize to uppercase
@@ -48,6 +51,9 @@ class ActionHandler:
         self.guards = guards
         self.response_model = response_model
         self.status_code = status_code
+        self.tags = tags
+        self.summary = summary
+        self.description = description
    
 
     def __call__(self, *args, **kwargs):
@@ -68,7 +74,10 @@ def action(
     auth: Optional[List[Any]] = None,
     guards: Optional[List[Any]] = None,
     response_model: Optional[Any] = None,
-    status_code: Optional[int] = None
+    status_code: Optional[int] = None,
+    tags: Optional[List[str]] = None,
+    summary: Optional[str] = None,
+    description: Optional[str] = None,
 ) -> Callable:
     """
     Decorator for ViewSet custom actions (DRF-style).
@@ -153,7 +162,10 @@ def action(
             auth=auth,
             guards=guards,
             response_model=response_model,
-            status_code=status_code
+            status_code=status_code,
+            tags=tags,
+            summary=summary,
+            description=description,
         )
 
     return decorator