django-flex 26.1.0__py3-none-any.whl

django_flex/filters.py

@@ -0,0 +1,207 @@
+"""
+Django-Flex Filter Utilities
+
+Handles filter parsing and Q object construction for flexible queries.
+
+Supports:
+- Simple equality filters
+- Django ORM operators (lt, gte, icontains, etc.)
+- Composable filters (and, or, not)
+- Nested relation filtering
+"""
+
+from django.db.models import Q
+
+
+# Django ORM operators supported in filters
+OPERATORS = {
+    # Comparisons
+    "lt",
+    "lte",
+    "gt",
+    "gte",
+    "exact",
+    "iexact",
+    "in",
+    "isnull",
+    "range",
+    # Text
+    "contains",
+    "icontains",
+    "startswith",
+    "istartswith",
+    "endswith",
+    "iendswith",
+    "regex",
+    "iregex",
+    # Date/Time
+    "date",
+    "year",
+    "month",
+    "day",
+    "week_day",
+    "hour",
+    "minute",
+    "second",
+}
+
+
+def parse_filter_key(key):
+    """
+    Parse a filter key into (field_path, operator).
+
+    Converts dot notation to Django's double underscore format and
+    extracts any operator suffix.
+
+    Args:
+        key: Filter key string (e.g., "author.name.icontains")
+
+    Returns:
+        Tuple of (field_path, operator) where operator may be None
+
+    Examples:
+        >>> parse_filter_key("status")
+        ('status', None)
+        >>> parse_filter_key("author.name")
+        ('author__name', None)
+        >>> parse_filter_key("author.name.icontains")
+        ('author__name', 'icontains')
+        >>> parse_filter_key("author.address.zip.lt")
+        ('author__address__zip', 'lt')
+    """
+    parts = key.split(".")
+
+    # Check if last part is an operator
+    if parts[-1] in OPERATORS:
+        operator = parts[-1]
+        field_parts = parts[:-1]
+    else:
+        operator = None
+        field_parts = parts
+
+    # Convert dot notation to Django's double underscore
+    field_path = "__".join(field_parts)
+
+    return field_path, operator
+
+
+def build_q_object(filters):
+    """
+    Build Django Q object from filter specification.
+
+    Supports:
+    - Simple equality: {"status": "confirmed"}
+    - Operators: {"status.in": ["confirmed", "completed"]}
+    - Composable: {"or": {...}, "and": {...}, "not": {...}}
+    - Mixed combinations of the above
+
+    Args:
+        filters: Dict of filter specifications
+
+    Returns:
+        Django Q object representing the filter
+
+    Examples:
+        >>> build_q_object({"status": "confirmed"})
+        <Q: (AND: ('status', 'confirmed'))>
+
+        >>> build_q_object({"price.gte": 100, "price.lte": 500})
+        <Q: (AND: ('price__gte', 100), ('price__lte', 500))>
+
+        >>> build_q_object({"or": {"status": "pending", "status": "confirmed"}})
+        <Q: (OR: ('status', 'pending'), ('status', 'confirmed'))>
+    """
+    if not filters:
+        return Q()
+
+    q_objects = []
+
+    for key, value in filters.items():
+        if key == "or":
+            # OR composition
+            if isinstance(value, dict):
+                sub_q = Q()
+                for sub_key, sub_value in value.items():
+                    field_path, operator = parse_filter_key(sub_key)
+                    if operator:
+                        sub_q |= Q(**{f"{field_path}__{operator}": sub_value})
+                    else:
+                        sub_q |= Q(**{field_path: sub_value})
+                q_objects.append(sub_q)
+            elif isinstance(value, list):
+                # OR as list of conditions
+                sub_q = Q()
+                for item in value:
+                    sub_q |= build_q_object(item)
+                q_objects.append(sub_q)
+        elif key == "and":
+            # AND composition (explicit)
+            if isinstance(value, dict):
+                sub_q = build_q_object(value)
+                q_objects.append(sub_q)
+            elif isinstance(value, list):
+                sub_q = Q()
+                for item in value:
+                    sub_q &= build_q_object(item)
+                q_objects.append(sub_q)
+        elif key == "not":
+            # NOT composition
+            sub_q = ~build_q_object(value)
+            q_objects.append(sub_q)
+        else:
+            # Regular field filter
+            field_path, operator = parse_filter_key(key)
+            if operator:
+                q_objects.append(Q(**{f"{field_path}__{operator}": value}))
+            else:
+                q_objects.append(Q(**{field_path: value}))
+
+    # Combine all with AND (default)
+    result = Q()
+    for q in q_objects:
+        result &= q
+
+    return result
+
+
+def extract_filter_keys(filters, keys=None):
+    """
+    Recursively extract all filter keys from a filter specification.
+
+    Used for permission validation to ensure all filter keys are allowed.
+
+    Args:
+        filters: Dict of filter specification
+        keys: Running list of keys (internal use)
+
+    Returns:
+        List of filter keys (e.g., ["name", "status.in", "blog.name.icontains"])
+
+    Examples:
+        >>> extract_filter_keys({"name": "Test", "status": "active"})
+        ['name', 'status']
+        >>> extract_filter_keys({"or": {"name": "A", "status": "B"}})
+        ['name', 'status']
+    """
+    if keys is None:
+        keys = []
+
+    if not filters:
+        return keys
+
+    for key, value in filters.items():
+        if key in ("or", "and"):
+            # Handle dict or list of sub-filters
+            if isinstance(value, dict):
+                extract_filter_keys(value, keys)
+            elif isinstance(value, list):
+                for item in value:
+                    extract_filter_keys(item, keys)
+        elif key == "not":
+            # NOT composition
+            extract_filter_keys(value, keys)
+        else:
+            # Regular filter key
+            keys.append(key)
+
+    return keys

django_flex/middleware.py

@@ -0,0 +1,143 @@
+"""
+Django-Flex Middleware
+
+Optional middleware for handling flexible queries through a
+centralized endpoint.
+
+Features:
+- Single endpoint for all flex queries
+- Automatic model routing
+- Request/response logging (optional)
+"""
+
+import json
+import logging
+
+from django.http import JsonResponse
+
+from django_flex.query import FlexQuery, get_model_by_name
+from django_flex.response import FlexResponse
+from django_flex.conf import flex_settings
+
+
+logger = logging.getLogger("django_flex")
+
+
+class FlexQueryMiddleware:
+    """
+    Middleware for handling flexible queries through a single endpoint.
+
+    This middleware intercepts requests to a configured URL path and
+    handles them as flex queries.
+
+    Setup:
+        # settings.py
+        MIDDLEWARE = [
+            ...
+            'django_flex.middleware.FlexQueryMiddleware',
+        ]
+
+        DJANGO_FLEX = {
+            'MIDDLEWARE_PATH': '/api/flex/',
+            'PERMISSIONS': {...},
+        }
+
+    Usage:
+        # Client sends POST to /api/flex/
+        {
+            "_model": "entry",
+            "_action": "query",
+            "fields": "id, author.name",
+            "filters": {"status": "confirmed"},
+            "limit": 20
+        }
+    """
+
+    def __init__(self, get_response):
+        self.get_response = get_response
+        self.path = getattr(flex_settings, "MIDDLEWARE_PATH", "/api/flex/")
+
+    def __call__(self, request):
+        # Check if this is a flex query request
+        if request.path == self.path and request.method == "POST":
+            return self.handle_flex_query(request)
+
+        return self.get_response(request)
+
+    def handle_flex_query(self, request):
+        """Handle a flex query request."""
+        # Check authentication if required
+        if flex_settings.REQUIRE_AUTHENTICATION:
+            if not hasattr(request, "user") or not request.user.is_authenticated:
+                return JsonResponse(
+                    FlexResponse.error("PERMISSION_DENIED", "Authentication required").to_dict(),
+                    status=401,
+                )
+
+        # Parse request body
+        try:
+            body = json.loads(request.body)
+        except json.JSONDecodeError:
+            return JsonResponse(
+                FlexResponse.error("INVALID_FILTER", "Invalid JSON body").to_dict(),
+                status=400,
+            )
+
+        # Extract model and action
+        model_name = body.get("_model")
+        action = body.get("_action", "query")
+
+        if not model_name:
+            return JsonResponse(
+                FlexResponse.error("MODEL_NOT_FOUND", "Missing '_model' in request").to_dict(),
+                status=400,
+            )
+
+        # Normalize action (legacy support)
+        if action == "get+" or action == "list":
+            action = "query"
+
+        # Get model
+        model = get_model_by_name(model_name)
+        if model is None:
+            return JsonResponse(
+                FlexResponse.error("MODEL_NOT_FOUND", f"Model '{model_name}' not found").to_dict(),
+                status=404,
+            )
+
+        # Build query spec (remove internal keys)
+        query_spec = {k: v for k, v in body.items() if not k.startswith("_")}
+
+        # Add id if present in body
+        if "id" in body:
+            query_spec["id"] = body["id"]
+
+        # Log query if auditing enabled
+        if flex_settings.AUDIT_QUERIES:
+            user = getattr(request, "user", None)
+            logger.info(
+                "flex_query",
+                extra={
+                    "user": str(user) if user else "anonymous",
+                    "model": model_name,
+                    "action": action,
+                    "query": query_spec,
+                },
+            )
+
+        # Execute query
+        user = request.user if hasattr(request, "user") else None
+        query = FlexQuery(model)
+        result = query.execute(query_spec, user=user, action=action)
+
+        # Determine HTTP status
+        if result.success:
+            status = 200
+        elif result.code == "NOT_FOUND":
+            status = 404
+        elif result.code == "PERMISSION_DENIED":
+            status = 403
+        else:
+            status = 400
+
+        return JsonResponse(result.to_dict(), status=status)

django_flex/permissions.py

@@ -0,0 +1,365 @@
+"""
+Django-Flex Permission System
+
+Provides row-level, field-level, and operation-level access control
+following the Principle of Least Privilege (deny by default, explicitly grant).
+
+Integrates with Django's built-in auth system:
+- User.groups for role-based access
+- User.is_superuser for admin bypass
+- User.is_staff for staff-level access
+
+Features:
+- Row-level: Which rows can the user see (Q filters)
+- Field-level: Which fields can the user access (including relations)
+- Operation-level: Which actions can the user perform (get, query, create, update, delete)
+- Filter-level: Which fields can the user filter on
+- Order-level: Which fields can the user order by
+
+Usage:
+    from django_flex import check_permission
+
+    row_filter, allowed_fields = check_permission(
+        user, "entry", "query", requested_fields
+    )
+    queryset = Entry.objects.filter(row_filter)
+"""
+
+from django.db.models import Q
+
+from django_flex.conf import flex_settings
+from django_flex.filters import OPERATORS
+
+
+class FlexPermission:
+    """
+    Base permission class for django-flex.
+
+    Subclass this to create custom permission logic, similar to
+    Django REST Framework's permission classes.
+
+    Example:
+        class IsOwnerPermission(FlexPermission):
+            def has_permission(self, request, model_name, action):
+                return request.user.is_authenticated
+
+            def get_row_filter(self, request, model_name):
+                return Q(owner=request.user)
+
+            def get_allowed_fields(self, request, model_name):
+                return ['*', 'owner.name']
+    """
+
+    def has_permission(self, request, model_name, action):
+        """Check if request has permission for action on model."""
+        return True
+
+    def get_row_filter(self, request, model_name):
+        """Return Q object to filter rows user can access."""
+        return Q()
+
+    def get_allowed_fields(self, request, model_name):
+        """Return list of allowed field patterns."""
+        return ["*"]
+
+    def get_allowed_filters(self, request, model_name):
+        """Return list of allowed filter keys."""
+        return []
+
+    def get_allowed_ordering(self, request, model_name):
+        """Return list of allowed order_by values."""
+        return []
+
+
+def field_matches_pattern(field, pattern):
+    """
+    Check if a field matches an allowed pattern.
+
+    Args:
+        field: Field name to check
+        pattern: Pattern to match against
+
+    Returns:
+        True if field matches pattern
+
+    Examples:
+        >>> field_matches_pattern("name", "*")
+        True
+        >>> field_matches_pattern("author.name", "author.*")
+        True
+        >>> field_matches_pattern("author.name", "author.name")
+        True
+        >>> field_matches_pattern("author.email", "author.name")
+        False
+    """
+    if pattern == "*":
+        # Wildcard only matches base fields, not relations
+        return "." not in field
+
+    if pattern.endswith(".*"):
+        # Relation wildcard: author.* matches author.name, author.email
+        prefix = pattern[:-2]
+        return field.startswith(prefix + ".")
+
+    # Exact match
+    return field == pattern
+
+
+def fields_allowed(requested_fields, allowed_patterns):
+    """
+    Check if all requested fields are allowed by the patterns.
+
+    Args:
+        requested_fields: List of field names to check
+        allowed_patterns: List of allowed patterns
+
+    Returns:
+        Tuple of (is_allowed, denied_field)
+    """
+    for field in requested_fields:
+        allowed = False
+        for pattern in allowed_patterns:
+            if field_matches_pattern(field, pattern):
+                allowed = True
+                break
+        if not allowed:
+            return False, field
+    return True, None
+
+
+def get_user_role(user, permissions=None):
+    """
+    Get the user's role using Django's built-in auth system.
+
+    Role resolution order:
+    1. superuser -> 'superuser' (bypasses all checks)
+    2. staff -> 'staff'
+    3. First matching group name (lowercase)
+    4. 'authenticated' if logged in
+    5. None if anonymous
+
+    Args:
+        user: Django User instance
+        permissions: Optional permissions config (for custom role lookup)
+
+    Returns:
+        Role name (string) or None
+    """
+    if user is None:
+        return None
+
+    if not user.is_authenticated:
+        return None
+
+    if user.is_superuser:
+        return "superuser"
+
+    if user.is_staff:
+        return "staff"
+
+    # Use Django's built-in groups
+    if hasattr(user, "groups"):
+        # Get the first group name as the role
+        group = user.groups.first()
+        if group:
+            return group.name.lower()
+
+    # Fallback for authenticated users with no group
+    return "authenticated"
+
+
+def check_permission(user, model_name, action, requested_fields, permissions=None):
+    """
+    Check if user has permission to perform action on model with requested fields.
+
+    This is the main permission check function. It validates:
+    1. User is authenticated
+    2. User has a valid role
+    3. Model is configured in permissions
+    4. Role has access to the model
+    5. Action is allowed for the role
+    6. All requested fields are allowed
+
+    Args:
+        user: Django User instance
+        model_name: Model name (lowercase)
+        action: Action name (get, query, create, update, delete)
+        requested_fields: List of field paths to access
+        permissions: Optional permissions dict (uses settings if not provided)
+
+    Returns:
+        Tuple of (row_filter, fields) - Q object for row filtering, validated fields list
+
+    Raises:
+        PermissionError: If permission denied
+    """
+    if permissions is None:
+        permissions = flex_settings.PERMISSIONS
+
+    model_name = model_name.lower()
+
+    # Check if user is authenticated
+    if user is None or not user.is_authenticated:
+        raise PermissionError("Authentication required")
+
+    # Superuser bypasses all checks
+    if user.is_superuser:
+        return Q(), requested_fields
+
+    # Get user's role
+    role = get_user_role(user, permissions)
+    if not role:
+        raise PermissionError("No role could be determined for user")
+
+    # Check if model is accessible
+    if model_name not in permissions:
+        raise PermissionError(f"Access denied: model '{model_name}' not configured")
+
+    model_perms = permissions[model_name]
+
+    # Check if role has access to this model
+    if role not in model_perms:
+        raise PermissionError(f"Access denied: role '{role}' cannot access '{model_name}'")
+
+    perm = model_perms[role]
+
+    # Check if operation is allowed
+    allowed_ops = perm.get("ops", perm.get("operations", []))
+    if action not in allowed_ops:
+        raise PermissionError(f"Access denied: operation '{action}' not allowed on '{model_name}'")
+
+    # Check if all requested fields are allowed
+    is_allowed, denied_field = fields_allowed(requested_fields, perm["fields"])
+    if not is_allowed:
+        raise PermissionError(f"Access denied: field '{denied_field}' not accessible")
+
+    # Return row filter
+    row_filter_fn = perm.get("rows")
+    if row_filter_fn:
+        row_filter = row_filter_fn(user)
+    else:
+        row_filter = Q()
+
+    return row_filter, requested_fields
+
+
+def check_filter_permission(user, model_name, filter_keys, permissions=None):
+    """
+    Check if user can filter on the given filter keys.
+
+    Args:
+        user: Django User instance
+        model_name: Model name (lowercase)
+        filter_keys: List of filter keys (e.g., ["name", "status.in", "owner.name.icontains"])
+        permissions: Optional permissions dict
+
+    Raises:
+        PermissionError: If filter key not allowed
+    """
+    if not filter_keys:
+        return
+
+    if permissions is None:
+        permissions = flex_settings.PERMISSIONS
+
+    model_name = model_name.lower()
+
+    # Check if user is authenticated
+    if user is None or not user.is_authenticated:
+        raise PermissionError("Authentication required")
+
+    # Superuser bypasses all checks
+    if user.is_superuser:
+        return
+
+    # Get user's role
+    role = get_user_role(user, permissions)
+    if not role:
+        raise PermissionError("No role could be determined for user")
+
+    # Check if model is accessible
+    if model_name not in permissions:
+        raise PermissionError(f"Access denied: model '{model_name}' not configured")
+
+    model_perms = permissions[model_name]
+
+    # Check if role has access to this model
+    if role not in model_perms:
+        raise PermissionError(f"Access denied: role '{role}' cannot access '{model_name}'")
+
+    perm = model_perms[role]
+
+    # Get allowed filters (default to empty = no filtering allowed)
+    allowed_filters = perm.get("filters", [])
+
+    max_depth = flex_settings.MAX_RELATION_DEPTH
+
+    for key in filter_keys:
+        # Skip composite operators (or, and, not) - they're handled recursively
+        if key in ("or", "and", "not"):
+            continue
+
+        # Check relation depth
+        parts = key.split(".")
+        # Remove operator suffix if present
+        if parts[-1] in OPERATORS:
+            parts = parts[:-1]
+        if len(parts) > max_depth:
+            raise PermissionError(f"Filter denied: '{key}' exceeds max relation depth of {max_depth}")
+
+        # Check if filter key is allowed
+        if key not in allowed_filters:
+            raise PermissionError(f"Filter denied: '{key}' not allowed for filtering")
+
+
+def check_order_permission(user, model_name, order_by, permissions=None):
+    """
+    Check if user can order by the given field.
+
+    Args:
+        user: Django User instance
+        model_name: Model name (lowercase)
+        order_by: Order by field (e.g., "name", "-created_at", "owner.name")
+        permissions: Optional permissions dict
+
+    Raises:
+        PermissionError: If order_by not allowed
+    """
+    if not order_by:
+        return
+
+    if permissions is None:
+        permissions = flex_settings.PERMISSIONS
+
+    model_name = model_name.lower()
+
+    # Check if user is authenticated
+    if user is None or not user.is_authenticated:
+        raise PermissionError("Authentication required")
+
+    # Superuser bypasses all checks
+    if user.is_superuser:
+        return
+
+    # Get user's role
+    role = get_user_role(user, permissions)
+    if not role:
+        raise PermissionError("No role could be determined for user")
+
+    # Check if model is accessible
+    if model_name not in permissions:
+        raise PermissionError(f"Access denied: model '{model_name}' not configured")
+
+    model_perms = permissions[model_name]
+
+    # Check if role has access to this model
+    if role not in model_perms:
+        raise PermissionError(f"Access denied: role '{role}' cannot access '{model_name}'")
+
+    perm = model_perms[role]
+
+    # Get allowed order_by fields (default to empty = no ordering allowed)
+    allowed_order = perm.get("order_by", [])
+
+    if order_by not in allowed_order:
+        raise PermissionError(f"Order denied: '{order_by}' not allowed for ordering")