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

django_bolt/binding.py

@@ -0,0 +1,363 @@
+"""
+Parameter binding and extraction with pre-compiled extractors.
+
+This module provides high-performance parameter extraction using pre-compiled
+extractor functions that avoid runtime type checking.
+"""
+import inspect
+import msgspec
+from typing import Any, Dict, List, Tuple, Callable, Optional
+from functools import lru_cache
+
+from .typing import is_msgspec_struct, is_optional, unwrap_optional
+
+__all__ = [
+    "convert_primitive",
+    "create_extractor",
+    "coerce_to_response_type",
+    "coerce_to_response_type_async",
+]
+
+
+# Cache for msgspec decoders (performance optimization)
+_DECODER_CACHE: Dict[Any, msgspec.json.Decoder] = {}
+
+
+def get_msgspec_decoder(type_: Any) -> msgspec.json.Decoder:
+    """Get or create a cached msgspec decoder for a type."""
+    if type_ not in _DECODER_CACHE:
+        _DECODER_CACHE[type_] = msgspec.json.Decoder(type_)
+    return _DECODER_CACHE[type_]
+
+
+def convert_primitive(value: str, annotation: Any) -> Any:
+    """
+    Convert string value to the appropriate type based on annotation.
+
+    Args:
+        value: Raw string value from request
+        annotation: Target type annotation
+
+    Returns:
+        Converted value
+    """
+    tp = unwrap_optional(annotation)
+
+    if tp is str or tp is Any or tp is None or tp is inspect._empty:
+        return value
+
+    if tp is int:
+        try:
+            return int(value)
+        except ValueError:
+            from .exceptions import HTTPException
+            raise HTTPException(422, detail=f"Invalid integer value: '{value}'")
+
+    if tp is float:
+        try:
+            return float(value)
+        except ValueError:
+            from .exceptions import HTTPException
+            raise HTTPException(422, detail=f"Invalid float value: '{value}'")
+
+    if tp is bool:
+        v = value.lower()
+        if v in ("1", "true", "t", "yes", "y", "on"):
+            return True
+        if v in ("0", "false", "f", "no", "n", "off"):
+            return False
+        return bool(value)
+
+    # Fallback: try msgspec decode for JSON in value
+    try:
+        return msgspec.json.decode(value.encode())
+    except Exception:
+        return value
+
+
+def create_path_extractor(name: str, annotation: Any, alias: Optional[str] = None) -> Callable:
+    """Create a pre-compiled extractor for path parameters."""
+    key = alias or name
+    converter = lambda v: convert_primitive(str(v), annotation)
+
+    def extract(params_map: Dict[str, Any]) -> Any:
+        if key not in params_map:
+            raise ValueError(f"Missing required path parameter: {key}")
+        return converter(params_map[key])
+
+    return extract
+
+
+def create_query_extractor(
+    name: str,
+    annotation: Any,
+    default: Any,
+    alias: Optional[str] = None
+) -> Callable:
+    """Create a pre-compiled extractor for query parameters."""
+    key = alias or name
+    optional = default is not inspect.Parameter.empty or is_optional(annotation)
+    converter = lambda v: convert_primitive(str(v), annotation)
+
+    if optional:
+        default_value = None if default is inspect.Parameter.empty else default
+        def extract(query_map: Dict[str, Any]) -> Any:
+            return converter(query_map[key]) if key in query_map else default_value
+    else:
+        def extract(query_map: Dict[str, Any]) -> Any:
+            if key not in query_map:
+                raise ValueError(f"Missing required query parameter: {key}")
+            return converter(query_map[key])
+
+    return extract
+
+
+def create_header_extractor(
+    name: str,
+    annotation: Any,
+    default: Any,
+    alias: Optional[str] = None
+) -> Callable:
+    """Create a pre-compiled extractor for HTTP headers."""
+    key = (alias or name).lower()
+    optional = default is not inspect.Parameter.empty or is_optional(annotation)
+    converter = lambda v: convert_primitive(str(v), annotation)
+
+    if optional:
+        default_value = None if default is inspect.Parameter.empty else default
+        def extract(headers_map: Dict[str, str]) -> Any:
+            return converter(headers_map[key]) if key in headers_map else default_value
+    else:
+        def extract(headers_map: Dict[str, str]) -> Any:
+            if key not in headers_map:
+                raise ValueError(f"Missing required header: {key}")
+            return converter(headers_map[key])
+
+    return extract
+
+
+def create_cookie_extractor(
+    name: str,
+    annotation: Any,
+    default: Any,
+    alias: Optional[str] = None
+) -> Callable:
+    """Create a pre-compiled extractor for cookies."""
+    key = alias or name
+    optional = default is not inspect.Parameter.empty or is_optional(annotation)
+    converter = lambda v: convert_primitive(str(v), annotation)
+
+    if optional:
+        default_value = None if default is inspect.Parameter.empty else default
+        def extract(cookies_map: Dict[str, str]) -> Any:
+            return converter(cookies_map[key]) if key in cookies_map else default_value
+    else:
+        def extract(cookies_map: Dict[str, str]) -> Any:
+            if key not in cookies_map:
+                raise ValueError(f"Missing required cookie: {key}")
+            return converter(cookies_map[key])
+
+    return extract
+
+
+def create_form_extractor(
+    name: str,
+    annotation: Any,
+    default: Any,
+    alias: Optional[str] = None
+) -> Callable:
+    """Create a pre-compiled extractor for form fields."""
+    key = alias or name
+    optional = default is not inspect.Parameter.empty or is_optional(annotation)
+    converter = lambda v: convert_primitive(str(v), annotation)
+
+    if optional:
+        default_value = None if default is inspect.Parameter.empty else default
+        def extract(form_map: Dict[str, Any]) -> Any:
+            return converter(form_map[key]) if key in form_map else default_value
+    else:
+        def extract(form_map: Dict[str, Any]) -> Any:
+            if key not in form_map:
+                raise ValueError(f"Missing required form field: {key}")
+            return converter(form_map[key])
+
+    return extract
+
+
+def create_file_extractor(
+    name: str,
+    annotation: Any,
+    default: Any,
+    alias: Optional[str] = None
+) -> Callable:
+    """Create a pre-compiled extractor for file uploads."""
+    key = alias or name
+    optional = default is not inspect.Parameter.empty or is_optional(annotation)
+
+    if optional:
+        default_value = None if default is inspect.Parameter.empty else default
+        def extract(files_map: Dict[str, Any]) -> Any:
+            return files_map.get(key, default_value)
+    else:
+        def extract(files_map: Dict[str, Any]) -> Any:
+            if key not in files_map:
+                raise ValueError(f"Missing required file: {key}")
+            return files_map[key]
+
+    return extract
+
+
+def create_body_extractor(name: str, annotation: Any) -> Callable:
+    """
+    Create a pre-compiled extractor for request body.
+
+    Uses cached msgspec decoder for maximum performance.
+    Converts msgspec.DecodeError (JSON parsing errors) to RequestValidationError for proper 422 responses.
+    """
+    from .exceptions import RequestValidationError, parse_msgspec_decode_error
+
+    if is_msgspec_struct(annotation):
+        decoder = get_msgspec_decoder(annotation)
+        def extract(body_bytes: bytes) -> Any:
+            try:
+                return decoder.decode(body_bytes)
+            except msgspec.ValidationError:
+                # Re-raise ValidationError as-is (field validation errors handled by error_handlers.py)
+                # IMPORTANT: Must catch ValidationError BEFORE DecodeError since ValidationError subclasses DecodeError
+                raise
+            except msgspec.DecodeError as e:
+                # JSON parsing error (malformed JSON) - return 422 with error details including line/column
+                error_detail = parse_msgspec_decode_error(e, body_bytes)
+                raise RequestValidationError(
+                    errors=[error_detail],
+                    body=body_bytes,
+                ) from e
+    else:
+        # Fallback to generic msgspec decode
+        def extract(body_bytes: bytes) -> Any:
+            try:
+                return msgspec.json.decode(body_bytes, type=annotation)
+            except msgspec.ValidationError:
+                # Re-raise ValidationError as-is (field validation errors handled by error_handlers.py)
+                # IMPORTANT: Must catch ValidationError BEFORE DecodeError since ValidationError subclasses DecodeError
+                raise
+            except msgspec.DecodeError as e:
+                # JSON parsing error (malformed JSON) - return 422 with error details including line/column
+                error_detail = parse_msgspec_decode_error(e, body_bytes)
+                raise RequestValidationError(
+                    errors=[error_detail],
+                    body=body_bytes,
+                ) from e
+
+    return extract
+
+
+def create_extractor(field: Dict[str, Any]) -> Callable:
+    """
+    Create an optimized extractor function for a parameter field.
+
+    This is a factory that returns a specialized extractor based on the
+    parameter source. The returned function is optimized to avoid runtime
+    type checking.
+
+    Args:
+        field: Field metadata dictionary
+
+    Returns:
+        Extractor function that takes request data and returns parameter value
+    """
+    source = field["source"]
+    name = field["name"]
+    annotation = field["annotation"]
+    default = field["default"]
+    alias = field.get("alias")
+
+    # Return appropriate extractor based on source
+    if source == "path":
+        return create_path_extractor(name, annotation, alias)
+    elif source == "query":
+        return create_query_extractor(name, annotation, default, alias)
+    elif source == "header":
+        return create_header_extractor(name, annotation, default, alias)
+    elif source == "cookie":
+        return create_cookie_extractor(name, annotation, default, alias)
+    elif source == "form":
+        return create_form_extractor(name, annotation, default, alias)
+    elif source == "file":
+        return create_file_extractor(name, annotation, default, alias)
+    elif source == "body":
+        return create_body_extractor(name, annotation)
+    elif source == "request":
+        # Request object is passed through directly
+        return lambda request: request
+    else:
+        # Fallback for unknown sources
+        def extract(*args, **kwargs):
+            if default is not inspect.Parameter.empty:
+                return default
+            raise ValueError(f"Cannot extract parameter {name} with source {source}")
+        return extract
+
+
+async def coerce_to_response_type_async(value: Any, annotation: Any) -> Any:
+    """
+    Async version that handles Django QuerySets.
+
+    Args:
+        value: Value to coerce
+        annotation: Target type annotation
+
+    Returns:
+        Coerced value
+    """
+    # Check if value is a Django QuerySet
+    if hasattr(value, '_iterable_class') and hasattr(value, 'model'):
+        # It's a QuerySet - convert to list asynchronously
+        result = []
+        async for item in value:
+            result.append(item)
+        value = result
+
+    return coerce_to_response_type(value, annotation)
+
+
+def coerce_to_response_type(value: Any, annotation: Any) -> Any:
+    """
+    Coerce arbitrary Python objects (including Django models) into the
+    declared response type using msgspec.
+
+    Supports:
+      - msgspec.Struct: build mapping from attributes if needed
+      - list[T]: recursively coerce elements
+      - dict/primitive: defer to msgspec.convert
+
+    Args:
+        value: Value to coerce
+        annotation: Target type annotation
+
+    Returns:
+        Coerced value
+    """
+    from typing import get_origin, get_args, List
+
+    origin = get_origin(annotation)
+
+    # Handle List[T]
+    if origin in (list, List):
+        args = get_args(annotation)
+        elem_type = args[0] if args else Any
+        return [coerce_to_response_type(elem, elem_type) for elem in (value or [])]
+
+    # Handle Struct
+    if is_msgspec_struct(annotation):
+        if isinstance(value, annotation):
+            return value
+        if isinstance(value, dict):
+            return msgspec.convert(value, annotation)
+        # Build mapping from attributes based on struct annotations
+        fields = getattr(annotation, "__annotations__", {})
+        mapped = {name: getattr(value, name, None) for name in fields.keys()}
+        return msgspec.convert(mapped, annotation)
+
+    # Default convert path
+    return msgspec.convert(value, annotation)

django_bolt/bootstrap.py

@@ -0,0 +1,77 @@
+import importlib
+import os
+import sys
+from pathlib import Path
+
+from django.conf import settings
+
+
+def ensure_django_ready() -> dict:
+    """Ensure Django is properly configured using the project's settings module."""
+    if settings.configured:
+        return _info()
+
+    settings_module = os.getenv("DJANGO_SETTINGS_MODULE")
+    if not settings_module:
+        # Try to detect settings module from manage.py location
+        settings_module = _detect_settings_module()
+        if settings_module:
+            os.environ["DJANGO_SETTINGS_MODULE"] = settings_module
+    
+    if not settings_module:
+        raise RuntimeError(
+            "Django settings module not found. Please ensure:\n"
+            "1. You are running from a Django project directory (with manage.py)\n"
+            "2. DJANGO_SETTINGS_MODULE environment variable is set\n"
+            "3. Your project has a valid settings.py file"
+        )
+    
+    try:
+        importlib.import_module(settings_module)
+        import django
+        django.setup()
+        return _info()
+    except ImportError as e:
+        raise RuntimeError(
+            f"Failed to import Django settings module '{settings_module}': {e}\n"
+            "Please check that your settings module exists and is valid."
+        )
+
+
+def _detect_settings_module() -> str | None:
+    """Try to auto-detect Django settings module from project structure."""
+    # Look for manage.py in current directory or parent directories
+    current = Path.cwd()
+    for path in [current] + list(current.parents)[:3]:  # Check up to 3 levels up
+        manage_py = path / "manage.py"
+        if manage_py.exists():
+            # Read manage.py to find settings module
+            content = manage_py.read_text()
+            if "DJANGO_SETTINGS_MODULE" in content:
+                # Extract the settings module from manage.py
+                for line in content.split('\n'):
+                    if "DJANGO_SETTINGS_MODULE" in line and "setdefault" in line:
+                        # Parse line like: os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'myproject.settings')
+                        parts = line.split("'")
+                        if len(parts) >= 4:
+                            return parts[3]  # Return the settings module string
+                        parts = line.split('"')
+                        if len(parts) >= 4:
+                            return parts[3]
+    return None
+
+
+def _info() -> dict:
+    """Get information about the current Django configuration."""
+    from django.conf import settings as dj_settings
+    db = dj_settings.DATABASES.get("default", {})
+    return {
+        "mode": "django_project",
+        "debug": bool(getattr(dj_settings, "DEBUG", False)),
+        "database": db.get("ENGINE"),
+        "database_name": db.get("NAME"),
+        "settings_module": os.getenv("DJANGO_SETTINGS_MODULE"),
+        "base_dir": str(getattr(dj_settings, "BASE_DIR", "")),
+    }
+
+

django_bolt/cli.py

@@ -0,0 +1,133 @@
+import os
+import sys
+from pathlib import Path
+import click
+
+from .api import BoltAPI
+
+
+@click.group(context_settings={"help_option_names": ["-h", "--help"]})
+def main():
+    """Django-Bolt command line interface."""
+
+
+@main.command()
+def init():
+    """Initialize Django-Bolt in an existing Django project."""
+    # Find Django project root (look for manage.py)
+    current_dir = Path.cwd()
+    project_root = None
+    for path in [current_dir] + list(current_dir.parents):
+        if (path / "manage.py").exists():
+            project_root = path
+            break
+    
+    if not project_root:
+        click.echo("Error: No Django project found (manage.py not found)", err=True)
+        click.echo("Please run this command from within a Django project directory.")
+        return
+    
+    click.echo(f"Found Django project at: {project_root}")
+    
+    # Find settings.py to determine project name
+    settings_files = list(project_root.glob("*/settings.py"))
+    if not settings_files:
+        click.echo("Error: Could not find settings.py", err=True)
+        return
+    
+    project_name = settings_files[0].parent.name
+    settings_file = settings_files[0]
+    
+    click.echo(f"Project name: {project_name}")
+    
+    # 1. Add django_bolt to INSTALLED_APPS
+    settings_content = settings_file.read_text()
+    if "'django_bolt'" not in settings_content and '"django_bolt"' not in settings_content:
+        if "INSTALLED_APPS" in settings_content:
+            # Find INSTALLED_APPS and add django_bolt
+            lines = settings_content.splitlines()
+            new_lines = []
+            in_installed_apps = False
+            added = False
+            
+            for line in lines:
+                if "INSTALLED_APPS" in line and "=" in line:
+                    in_installed_apps = True
+                elif in_installed_apps and not added:
+                    # Look for the first app entry and add django_bolt before it
+                    if line.strip().startswith(("'", '"')) and not added:
+                        new_lines.append('    "django_bolt",')
+                        added = True
+                    elif "]" in line and not added:
+                        # End of INSTALLED_APPS, add before closing
+                        new_lines.append('    "django_bolt",')
+                        added = True
+                        in_installed_apps = False
+                
+                new_lines.append(line)
+            
+            if added:
+                settings_file.write_text("\n".join(new_lines))
+                click.echo("✓ Added 'django_bolt' to INSTALLED_APPS")
+            else:
+                click.echo("Warning: Could not automatically add to INSTALLED_APPS. Please add 'django_bolt' manually.")
+        else:
+            click.echo("Warning: INSTALLED_APPS not found in settings.py. Please add 'django_bolt' manually.")
+    else:
+        click.echo("✓ 'django_bolt' already in INSTALLED_APPS")
+    
+    # 2. Create api.py template
+    api_file = project_root / project_name / "api.py"
+    if not api_file.exists():
+        api_template = '''"""Django-Bolt API routes."""
+from django_bolt import BoltAPI
+import msgspec
+from typing import Optional
+
+api = BoltAPI()
+
+
+@api.get("/")
+async def root():
+    """Root endpoint."""
+    return {"message": "Welcome to Django-Bolt!"}
+
+
+@api.get("/health")
+async def health():
+    """Health check endpoint."""
+    return {"status": "ok", "service": "django-bolt"}
+
+
+# Example with path parameters
+@api.get("/items/{item_id}")
+async def get_item(item_id: int, q: Optional[str] = None):
+    """Get an item by ID."""
+    return {"item_id": item_id, "q": q}
+
+
+# Example with request body validation using msgspec
+class Item(msgspec.Struct):
+    name: str
+    price: float
+    is_offer: Optional[bool] = None
+
+
+@api.post("/items")
+async def create_item(item: Item):
+    """Create a new item."""
+    return {"item": item, "created": True}
+'''
+        api_file.write_text(api_template)
+        click.echo(f"✓ Created {api_file.relative_to(project_root)}")
+    else:
+        click.echo(f"✓ {api_file.relative_to(project_root)} already exists")
+    
+    click.echo("\n🚀 Django-Bolt initialization complete!")
+    click.echo("\nNext steps:")
+    click.echo("1. Run migrations: python manage.py migrate")
+    click.echo("2. Start the server: python manage.py runbolt")
+    click.echo(f"3. Edit your API routes in {project_name}/api.py")
+    click.echo("\nFor more information, visit: https://github.com/yourusername/django-bolt")
+
+

django_bolt/compression.py

@@ -0,0 +1,104 @@
+"""
+Compression configuration for Django-Bolt.
+
+Provides configuration options for response compression (gzip, brotli, zstd).
+Inspired by Litestar's compression config.
+"""
+from typing import Optional, Literal
+from dataclasses import dataclass
+
+
+@dataclass
+class CompressionConfig:
+    """Configuration for response compression.
+
+    To enable response compression, pass an instance of this class to the BoltAPI
+    constructor using the compression parameter.
+
+    Args:
+        backend: The compression backend to use (default: "brotli")
+            If the value is "gzip", "brotli", or "zstd", built-in compression is used.
+        minimum_size: Minimum response size in bytes to enable compression (default: 500)
+            Responses smaller than this will not be compressed.
+        gzip_compress_level: Range [0-9] for gzip compression (default: 9)
+            Higher values provide better compression but are slower.
+        brotli_quality: Range [0-11] for brotli compression (default: 5)
+            Controls compression-speed vs compression-density tradeoff.
+        brotli_lgwin: Base 2 logarithm of window size for brotli (default: 22)
+            Range is 10 to 24. Larger values can improve compression for large files.
+        zstd_level: Range [1-22] for zstd compression (default: 3)
+            Higher values provide better compression but are slower.
+        gzip_fallback: Use GZIP if the client doesn't support the configured backend (default: True)
+
+    Examples:
+        # Default compression (brotli with gzip fallback)
+        api = BoltAPI(compression=CompressionConfig())
+
+        # Aggressive brotli compression
+        api = BoltAPI(compression=CompressionConfig(
+            backend="brotli",
+            brotli_quality=11,
+            minimum_size=256
+        ))
+
+        # Gzip only (maximum compression)
+        api = BoltAPI(compression=CompressionConfig(
+            backend="gzip",
+            gzip_compress_level=9,
+            gzip_fallback=False
+        ))
+
+        # Fast zstd compression
+        api = BoltAPI(compression=CompressionConfig(
+            backend="zstd",
+            zstd_level=1
+        ))
+
+        # Disable compression
+        api = BoltAPI(compression=None)
+    """
+    backend: Literal["gzip", "brotli", "zstd"] = "brotli"
+    minimum_size: int = 500
+    gzip_compress_level: int = 9
+    brotli_quality: int = 5
+    brotli_lgwin: int = 22
+    zstd_level: int = 3
+    gzip_fallback: bool = True
+
+    def __post_init__(self):
+        # Validate backend
+        valid_backends = {"gzip", "brotli", "zstd"}
+        if self.backend not in valid_backends:
+            raise ValueError(f"Invalid backend: {self.backend}. Must be one of {valid_backends}")
+
+        # Validate minimum_size
+        if self.minimum_size < 0:
+            raise ValueError("minimum_size must be non-negative")
+
+        # Validate gzip_compress_level
+        if not (0 <= self.gzip_compress_level <= 9):
+            raise ValueError("gzip_compress_level must be between 0 and 9")
+
+        # Validate brotli_quality
+        if not (0 <= self.brotli_quality <= 11):
+            raise ValueError("brotli_quality must be between 0 and 11")
+
+        # Validate brotli_lgwin
+        if not (10 <= self.brotli_lgwin <= 24):
+            raise ValueError("brotli_lgwin must be between 10 and 24")
+
+        # Validate zstd_level
+        if not (1 <= self.zstd_level <= 22):
+            raise ValueError("zstd_level must be between 1 and 22")
+
+    def to_rust_config(self) -> dict:
+        """Convert to dictionary for passing to Rust."""
+        return {
+            "backend": self.backend,
+            "minimum_size": self.minimum_size,
+            "gzip_compress_level": self.gzip_compress_level,
+            "brotli_quality": self.brotli_quality,
+            "brotli_lgwin": self.brotli_lgwin,
+            "zstd_level": self.zstd_level,
+            "gzip_fallback": self.gzip_fallback,
+        }