django-flex 26.1.0__py3-none-any.whl

django_flex/query.py

@@ -0,0 +1,290 @@
+"""
+Django-Flex Core Query Engine
+
+The main query execution engine that ties together field parsing,
+filter building, and permission checking.
+
+Provides:
+- FlexQuery class for OOP-style queries
+- execute_query function for procedural usage
+"""
+
+from django.apps import apps
+
+from django_flex.conf import flex_settings
+from django_flex.fields import parse_fields, expand_fields, extract_relations
+from django_flex.filters import build_q_object, extract_filter_keys
+from django_flex.permissions import (
+    check_permission,
+    check_filter_permission,
+    check_order_permission,
+)
+from django_flex.response import FlexResponse, build_nested_response
+
+
+def get_model_by_name(model_name):
+    """
+    Get Django model class by name (case-insensitive).
+
+    Searches all installed apps for a matching model.
+
+    Args:
+        model_name: Model name to find (case-insensitive)
+
+    Returns:
+        Model class or None if not found
+    """
+    for app_config in apps.get_app_configs():
+        for model in app_config.get_models():
+            if model.__name__.lower() == model_name.lower():
+                return model
+    return None
+
+
+class FlexQuery:
+    """
+    Flexible query builder for Django models.
+
+    Provides a fluent interface for building and executing queries
+    with field selection, filtering, and pagination.
+
+    Example:
+        # Direct usage
+        result = FlexQuery(Entry).execute({
+            'fields': 'id, author.name, status',
+            'filters': {'status': 'confirmed'},
+            'limit': 20,
+        }, user=request.user)
+
+        # With model name
+        result = FlexQuery('entry').execute({...}, user=request.user)
+
+        # Chained configuration
+        query = FlexQuery(Entry)
+        query.set_user(request.user)
+        query.set_permissions(custom_permissions)
+        result = query.execute({...})
+    """
+
+    def __init__(self, model):
+        """
+        Initialize a FlexQuery.
+
+        Args:
+            model: Django model class or model name string
+        """
+        if isinstance(model, str):
+            self.model_name = model.lower()
+            self.model = get_model_by_name(model)
+        else:
+            self.model = model
+            self.model_name = model.__name__.lower()
+
+        self.user = None
+        self.permissions = None
+
+    def set_user(self, user):
+        """Set the user for permission checking."""
+        self.user = user
+        return self
+
+    def set_permissions(self, permissions):
+        """Set custom permissions configuration."""
+        self.permissions = permissions
+        return self
+
+    def execute(self, query_spec, user=None, action=None):
+        """
+        Execute a query with the given specification.
+
+        Args:
+            query_spec: Dict with query parameters (fields, filters, etc.)
+            user: Optional user (overrides set_user)
+            action: Optional action override (defaults to 'get' for id, 'query' for no id)
+
+        Returns:
+            FlexResponse with query results
+        """
+        user = user or self.user
+        permissions = self.permissions
+
+        if self.model is None:
+            return FlexResponse.error("MODEL_NOT_FOUND")
+
+        # Determine action
+        if action:
+            pass
+        elif "id" in query_spec:
+            action = "get"
+        else:
+            action = "query"
+
+        if action == "get":
+            return self._execute_get(query_spec, user, permissions)
+        else:
+            return self._execute_query(query_spec, user, permissions)
+
+    def _execute_get(self, query_spec, user, permissions):
+        """Execute single object retrieval."""
+        # Parse fields
+        field_specs = parse_fields(query_spec.get("fields", "*"))
+        expanded_fields = expand_fields(self.model, field_specs, permissions=permissions)
+
+        # Check permissions
+        try:
+            if user:
+                row_filter, validated_fields = check_permission(user, self.model_name, "get", expanded_fields, permissions)
+            else:
+                row_filter = None
+                validated_fields = expanded_fields
+        except PermissionError as e:
+            return FlexResponse.error("PERMISSION_DENIED", str(e))
+
+        # Extract relations for select_related (avoid N+1)
+        relations = extract_relations(validated_fields)
+
+        # Build queryset
+        try:
+            queryset = self.model.objects.all()
+            if row_filter:
+                queryset = queryset.filter(row_filter)
+            if relations:
+                queryset = queryset.select_related(*relations)
+            obj = queryset.get(pk=query_spec["id"])
+        except self.model.DoesNotExist:
+            return FlexResponse.error("NOT_FOUND")
+
+        # Build response
+        response_data = build_nested_response(obj, validated_fields)
+        return FlexResponse.ok(**response_data)
+
+    def _execute_query(self, query_spec, user, permissions):
+        """Execute paginated query retrieval."""
+        # Parse fields
+        field_specs = parse_fields(query_spec.get("fields", "*"))
+        expanded_fields = expand_fields(self.model, field_specs, permissions=permissions)
+
+        # Check permissions
+        try:
+            if user:
+                row_filter, validated_fields = check_permission(user, self.model_name, "query", expanded_fields, permissions)
+            else:
+                row_filter = None
+                validated_fields = expanded_fields
+        except PermissionError as e:
+            return FlexResponse.error("PERMISSION_DENIED", str(e))
+
+        # Validate filter keys
+        filters = query_spec.get("filters", {})
+        try:
+            if user:
+                filter_keys = extract_filter_keys(filters)
+                check_filter_permission(user, self.model_name, filter_keys, permissions)
+        except PermissionError as e:
+            return FlexResponse.error("PERMISSION_DENIED", str(e))
+
+        # Validate order_by
+        order_by = query_spec.get("order_by")
+        try:
+            if user:
+                check_order_permission(user, self.model_name, order_by, permissions)
+        except PermissionError as e:
+            return FlexResponse.error("PERMISSION_DENIED", str(e))
+
+        # Extract relations for select_related
+        relations = extract_relations(validated_fields)
+
+        # Build query
+        user_filter = build_q_object(filters)
+        queryset = self.model.objects.all()
+        if row_filter:
+            queryset = queryset.filter(row_filter & user_filter)
+        else:
+            queryset = queryset.filter(user_filter)
+
+        # Apply select_related
+        if relations:
+            queryset = queryset.select_related(*relations)
+
+        # Ordering
+        if order_by:
+            order_by_django = order_by.replace(".", "__")
+            queryset = queryset.order_by(order_by_django)
+
+        # Pagination with limit clamping
+        requested_limit = query_spec.get("limit", flex_settings.DEFAULT_LIMIT)
+        max_limit = flex_settings.MAX_LIMIT
+        limit = min(requested_limit, max_limit)
+        limit_clamped = requested_limit > max_limit
+        offset = query_spec.get("offset", 0)
+
+        # Fetch limit + 1 to check for more results (avoids expensive COUNT query)
+        paginated = list(queryset[offset : offset + limit + 1])
+
+        # Determine if there are more results
+        has_more = len(paginated) > limit
+        if has_more:
+            paginated = paginated[:limit]  # Drop the extra row
+
+        # Build results dict keyed by id
+        results = {}
+        for obj in paginated:
+            obj_data = build_nested_response(obj, validated_fields)
+            results[str(obj.pk)] = obj_data
+
+        # Build pagination info
+        pagination = {
+            "offset": offset,
+            "limit": limit,
+            "has_more": has_more,
+        }
+
+        # Build next cursor if more results exist
+        if has_more:
+            pagination["next"] = {
+                "fields": query_spec.get("fields", "*"),
+                "filters": filters,
+                "limit": limit,
+                "offset": offset + limit,
+            }
+            if order_by:
+                pagination["next"]["order_by"] = order_by
+
+        # Return warning if limit was clamped
+        if limit_clamped:
+            return FlexResponse.warning_response(
+                "LIMIT_CLAMPED",
+                results=results,
+                pagination=pagination,
+                requested_limit=requested_limit,
+            )
+
+        return FlexResponse.ok_query(results=results, pagination=pagination)
+
+
+def execute_query(model, query_spec, user=None, permissions=None):
+    """
+    Execute a flexible query on a model.
+
+    Convenience function that wraps FlexQuery.
+
+    Args:
+        model: Django model class or model name string
+        query_spec: Dict with query parameters
+        user: Optional user for permission checking
+        permissions: Optional custom permissions
+
+    Returns:
+        FlexResponse with query results
+
+    Example:
+        result = execute_query(Entry, {
+            'fields': 'id, author.name',
+            'filters': {'status': 'confirmed'},
+            'limit': 20,
+        }, user=request.user)
+    """
+    query = FlexQuery(model)
+    if permissions:
+        query.set_permissions(permissions)
+    return query.execute(query_spec, user=user)

django_flex/response.py

@@ -0,0 +1,212 @@
+"""
+Django-Flex Response Utilities
+
+Handles response building and serialization for flexible queries.
+
+Features:
+- Nested response construction from field paths
+- Automatic serialization of common types
+- Response code management
+"""
+
+from django_flex.conf import flex_settings
+
+
+def get_field_value(obj, field_path):
+    """
+    Get value from object following dot notation path.
+
+    Safely traverses nested objects and returns None if any
+    part of the path is missing.
+
+    Args:
+        obj: Model instance
+        field_path: Dot-notation path (e.g., "author.name")
+
+    Returns:
+        Value at the path, or None if not found
+
+    Examples:
+        >>> get_field_value(entry, "status")
+        "confirmed"
+        >>> get_field_value(entry, "author.name")
+        "Aisha Khan"
+        >>> get_field_value(entry, "author.blog.city")
+        "Sydney"
+    """
+    parts = field_path.split(".")
+    value = obj
+
+    for part in parts:
+        if value is None:
+            return None
+        value = getattr(value, part, None)
+
+    return value
+
+
+def serialize_value(value):
+    """
+    Serialize a value for JSON response.
+
+    Handles common Django types:
+    - DateField, DateTimeField -> ISO format string
+    - ForeignKey -> primary key string
+    - UUID -> string
+
+    Args:
+        value: Value to serialize
+
+    Returns:
+        JSON-serializable value
+    """
+    if value is None:
+        return None
+
+    # DateTime/Date
+    if hasattr(value, "isoformat"):
+        return value.isoformat()
+
+    # UUID
+    if hasattr(value, "hex"):
+        return str(value)
+
+    # Related object not in fields list - just use pk
+    if hasattr(value, "pk"):
+        return str(value.pk)
+
+    return value
+
+
+def build_nested_response(obj, field_paths):
+    """
+    Build nested dict response from object and field paths.
+
+    Constructs a nested dictionary structure from a flat list of
+    dot-notation field paths.
+
+    Args:
+        obj: Model instance
+        field_paths: List of field paths (e.g., ["id", "author.name"])
+
+    Returns:
+        Nested dictionary with field values
+
+    Example:
+        >>> build_nested_response(entry, ["id", "status", "author.name", "author.email"])
+        {
+            "id": "1",
+            "status": "confirmed",
+            "author": {
+                "name": "Aisha Khan",
+                "email": "aisha@example.com"
+            }
+        }
+    """
+    if obj is None:
+        return None
+
+    result = {}
+
+    for field_path in field_paths:
+        parts = field_path.split(".")
+        value = get_field_value(obj, field_path)
+        value = serialize_value(value)
+
+        # Build nested structure
+        current = result
+        for i, part in enumerate(parts[:-1]):
+            if part not in current:
+                current[part] = {}
+            current = current[part]
+
+        current[parts[-1]] = value
+
+    return result
+
+
+class FlexResponse:
+    """
+    Response builder for django-flex queries.
+
+    Provides a consistent response format with success status,
+    response code, and data.
+
+    Example:
+        >>> response = FlexResponse(code="OK", data={"id": 1, "name": "Test"})
+        >>> response.to_dict()
+        {"success": True, "code": "FLEX_OK", "id": 1, "name": "Test"}
+
+        >>> response = FlexResponse.error("NOT_FOUND")
+        >>> response.to_dict()
+        {"success": False, "code": "FLEX_NOT_FOUND"}
+    """
+
+    def __init__(self, code="OK", warning=False, error_message=None, **data):
+        """
+        Initialize a FlexResponse.
+
+        Args:
+            code: Response code key (e.g., "OK", "NOT_FOUND")
+            warning: Whether this is a warning response
+            error_message: Optional error message for error responses
+            **data: Additional data to include in response
+        """
+        self.code = code
+        self.warning = warning
+        self.error_message = error_message
+        self.data = data
+
+    @property
+    def success(self):
+        """Whether the response indicates success."""
+        return self.code in ("OK", "OK_QUERY", "LIMIT_CLAMPED")
+
+    @classmethod
+    def ok(cls, **data):
+        """Create a successful response."""
+        return cls(code="OK", **data)
+
+    @classmethod
+    def ok_query(cls, results, pagination=None, **data):
+        """Create a successful query response."""
+        response_data = {"results": results}
+        if pagination:
+            response_data["pagination"] = pagination
+        response_data.update(data)
+        return cls(code="OK_QUERY", **response_data)
+
+    @classmethod
+    def error(cls, code, message=None):
+        """Create an error response."""
+        return cls(code=code, error_message=message)
+
+    @classmethod
+    def warning_response(cls, code, **data):
+        """Create a warning response (success with warning flag)."""
+        return cls(code=code, warning=True, **data)
+
+    def to_dict(self):
+        """Convert response to dictionary for JSON serialization."""
+        codes = flex_settings.RESPONSE_CODES
+
+        result = {
+            "success": self.success,
+            "code": codes.get(self.code, self.code),
+        }
+
+        if self.warning:
+            result["warning"] = True
+
+        if self.error_message:
+            result["error"] = self.error_message
+
+        result.update(self.data)
+
+        return result
+
+    def to_json_response(self):
+        """Convert to Django JsonResponse."""
+        from django.http import JsonResponse
+
+        return JsonResponse(self.to_dict())