django-flex 26.1.0__py3-none-any.whl

django_flex/__init__.py

@@ -0,0 +1,92 @@
+"""
+Django-Flex: Flexible Query Language for Django
+
+A Django-native query builder that enables frontends to send JSON query
+specifications to the backend, supporting field selection, filtering,
+pagination, and comprehensive security controls.
+
+Example:
+    from django_flex import FlexQuery
+
+    result = FlexQuery(Entry).execute({
+        'fields': 'id, author.name, status',
+        'filters': {'status': 'confirmed'},
+        'limit': 20,
+    })
+"""
+
+__version__ = "26.1.0"
+__author__ = "Nehemiah Jacob"
+
+# Core query execution
+from django_flex.query import FlexQuery, execute_query
+
+# Field utilities
+from django_flex.fields import (
+    parse_fields,
+    expand_fields,
+    get_model_fields,
+    get_model_relations,
+    extract_relations,
+)
+
+# Filter utilities
+from django_flex.filters import (
+    parse_filter_key,
+    build_q_object,
+    extract_filter_keys,
+    OPERATORS,
+)
+
+# Permissions
+from django_flex.permissions import (
+    FlexPermission,
+    check_permission,
+    check_filter_permission,
+    check_order_permission,
+)
+
+# Views
+from django_flex.views import FlexQueryView
+
+# Decorators
+from django_flex.decorators import flex_query
+
+# Response utilities
+from django_flex.response import FlexResponse, build_nested_response
+
+# Configuration
+from django_flex.conf import flex_settings
+
+__all__ = [
+    # Version
+    "__version__",
+    # Query
+    "FlexQuery",
+    "execute_query",
+    # Fields
+    "parse_fields",
+    "expand_fields",
+    "get_model_fields",
+    "get_model_relations",
+    "extract_relations",
+    # Filters
+    "parse_filter_key",
+    "build_q_object",
+    "extract_filter_keys",
+    "OPERATORS",
+    # Permissions
+    "FlexPermission",
+    "check_permission",
+    "check_filter_permission",
+    "check_order_permission",
+    # Views
+    "FlexQueryView",
+    # Decorators
+    "flex_query",
+    # Response
+    "FlexResponse",
+    "build_nested_response",
+    # Settings
+    "flex_settings",
+]

django_flex/conf.py

@@ -0,0 +1,92 @@
+"""
+Django-Flex Settings
+
+Configuration is read from Django settings under the DJANGO_FLEX key.
+All settings have sensible defaults.
+
+Example:
+    # settings.py
+    DJANGO_FLEX = {
+        'DEFAULT_LIMIT': 50,
+        'MAX_LIMIT': 200,
+        'MAX_RELATION_DEPTH': 2,
+        'PERMISSIONS': {...},
+    }
+"""
+
+from django.conf import settings
+
+DEFAULTS = {
+    # Pagination
+    "DEFAULT_LIMIT": 50,
+    "MAX_LIMIT": 200,
+    # Security
+    "MAX_RELATION_DEPTH": 2,
+    "REQUIRE_AUTHENTICATION": True,
+    "AUDIT_QUERIES": False,
+    # Model permissions
+    "PERMISSIONS": {},
+    # Response
+    "RESPONSE_CODES": {
+        "OK": "FLEX_OK",
+        "OK_QUERY": "FLEX_OK_QUERY",
+        "LIMIT_CLAMPED": "FLEX_LIMIT_CLAMPED",
+        "NOT_FOUND": "FLEX_NOT_FOUND",
+        "MODEL_NOT_FOUND": "FLEX_MODEL_NOT_FOUND",
+        "PERMISSION_DENIED": "FLEX_PERMISSION_DENIED",
+        "INVALID_FIELD": "FLEX_INVALID_FIELD",
+        "INVALID_FILTER": "FLEX_INVALID_FILTER",
+    },
+}
+
+
+class FlexSettings:
+    """
+    A settings object that allows django-flex settings to be accessed as
+    properties. For example:
+
+        from django_flex.conf import flex_settings
+        print(flex_settings.DEFAULT_LIMIT)
+
+    Settings can be overridden in Django settings.py under DJANGO_FLEX key.
+    """
+
+    def __init__(self, defaults=None):
+        self.defaults = defaults or DEFAULTS
+        self._cached_attrs = set()
+
+    @property
+    def user_settings(self):
+        if not hasattr(self, "_user_settings"):
+            self._user_settings = getattr(settings, "DJANGO_FLEX", {})
+        return self._user_settings
+
+    def __getattr__(self, attr):
+        if attr not in self.defaults:
+            raise AttributeError(f"Invalid django-flex setting: '{attr}'")
+
+        try:
+            # Check if present in user settings
+            val = self.user_settings[attr]
+        except KeyError:
+            # Fall back to defaults
+            val = self.defaults[attr]
+
+        # Cache the result
+        self._cached_attrs.add(attr)
+        setattr(self, attr, val)
+        return val
+
+    def reload(self):
+        """Reload settings (useful for testing)."""
+        for attr in self._cached_attrs:
+            try:
+                delattr(self, attr)
+            except AttributeError:
+                pass
+        self._cached_attrs.clear()
+        if hasattr(self, "_user_settings"):
+            delattr(self, "_user_settings")
+
+
+flex_settings = FlexSettings(DEFAULTS)

django_flex/decorators.py

@@ -0,0 +1,182 @@
+"""
+Django-Flex Decorators
+
+Provides function decorators for adding flexible query capabilities
+to Django views.
+
+Features:
+- flex_query decorator for function-based views
+- Automatic queryset filtering and field selection
+- Permission integration
+"""
+
+from functools import wraps
+import json
+
+from django.http import JsonResponse
+
+from django_flex.query import FlexQuery
+from django_flex.response import FlexResponse
+
+
+def flex_query(
+    model,
+    allowed_fields=None,
+    allowed_filters=None,
+    allowed_ordering=None,
+    require_auth=True,
+    allowed_actions=None,
+):
+    """
+    Decorator for adding flexible query capabilities to a view.
+
+    The decorated function receives additional arguments:
+    - queryset: Pre-filtered queryset based on permissions
+    - fields: Validated list of field paths
+    - query_spec: The parsed query specification
+
+    Args:
+        model: Django model class
+        allowed_fields: List of allowed field patterns (default: ["*"])
+        allowed_filters: List of allowed filter keys (default: [])
+        allowed_ordering: List of allowed order_by values (default: [])
+        require_auth: Whether authentication is required (default: True)
+        allowed_actions: List of allowed actions (default: ["get", "query"])
+
+    Example:
+        from django_flex import flex_query
+        from myapp.models import Entry
+
+        @flex_query(
+            model=Entry,
+            allowed_fields=['id', 'rating', 'author.name'],
+            allowed_filters=['rating', 'rating.in', 'author.name.icontains'],
+            allowed_ordering=['created_at', '-created_at'],
+        )
+        def entry_list(request, queryset, fields, query_spec):
+            # queryset is pre-filtered
+            # fields is the validated list of fields
+            # Use FlexResponse to build response
+            from django_flex import FlexResponse, build_nested_response
+
+            results = {}
+            for obj in queryset:
+                results[str(obj.pk)] = build_nested_response(obj, fields)
+
+            return JsonResponse(FlexResponse.ok_query(results=results).to_dict())
+    """
+    allowed_fields = allowed_fields or ["*"]
+    allowed_filters = allowed_filters or []
+    allowed_ordering = allowed_ordering or []
+    allowed_actions = allowed_actions or ["get", "query"]
+
+    def decorator(view_func):
+        @wraps(view_func)
+        def wrapped_view(request, *args, **kwargs):
+            # Check authentication
+            if require_auth:
+                if not hasattr(request, "user") or not request.user.is_authenticated:
+                    return JsonResponse(
+                        FlexResponse.error("PERMISSION_DENIED", "Authentication required").to_dict(),
+                        status=401,
+                    )
+
+            # Parse query spec
+            if request.method == "POST":
+                try:
+                    query_spec = json.loads(request.body)
+                except json.JSONDecodeError:
+                    return JsonResponse(
+                        FlexResponse.error("INVALID_FILTER", "Invalid JSON body").to_dict(),
+                        status=400,
+                    )
+            else:
+                query_spec = _parse_query_params(request)
+
+            # Determine action
+            action = "get" if "id" in query_spec else "query"
+            if action not in allowed_actions:
+                return JsonResponse(
+                    FlexResponse.error("PERMISSION_DENIED", f"Action '{action}' not allowed").to_dict(),
+                    status=403,
+                )
+
+            # Build permissions for this view
+            user = request.user if hasattr(request, "user") else None
+            role = _get_user_role(user)
+
+            permissions = {
+                model.__name__.lower(): {
+                    role: {
+                        "rows": lambda u: __import__("django.db.models", fromlist=["Q"]).Q(),
+                        "fields": allowed_fields,
+                        "filters": allowed_filters,
+                        "order_by": allowed_ordering,
+                        "ops": allowed_actions,
+                    },
+                    "exclude": [],
+                }
+            }
+
+            # Execute query
+            query = FlexQuery(model)
+            query.set_permissions(permissions)
+            result = query.execute(query_spec, user=user, action=action)
+
+            if not result.success:
+                status = 404 if result.code == "NOT_FOUND" else 403 if result.code == "PERMISSION_DENIED" else 400
+                return JsonResponse(result.to_dict(), status=status)
+
+            # If successful, we can also pass the raw queryset and fields to the view
+            # for custom processing (optional pattern)
+            return view_func(request, result=result, query_spec=query_spec, *args, **kwargs)
+
+        return wrapped_view
+
+    return decorator
+
+
+def _parse_query_params(request):
+    """Parse query specification from GET parameters."""
+    spec = {}
+    if "fields" in request.GET:
+        spec["fields"] = request.GET["fields"]
+    if "filters" in request.GET:
+        try:
+            spec["filters"] = json.loads(request.GET["filters"])
+        except json.JSONDecodeError:
+            spec["filters"] = {}
+    if "limit" in request.GET:
+        try:
+            spec["limit"] = int(request.GET["limit"])
+        except ValueError:
+            pass
+    if "offset" in request.GET:
+        try:
+            spec["offset"] = int(request.GET["offset"])
+        except ValueError:
+            pass
+    if "order_by" in request.GET:
+        spec["order_by"] = request.GET["order_by"]
+    if "id" in request.GET:
+        try:
+            spec["id"] = int(request.GET["id"])
+        except ValueError:
+            spec["id"] = request.GET["id"]
+    return spec
+
+
+def _get_user_role(user):
+    """Get role using Django's built-in auth system."""
+    if user is None or not user.is_authenticated:
+        return "anonymous"
+    if user.is_superuser:
+        return "superuser"
+    if user.is_staff:
+        return "staff"
+    # Use Django groups
+    if hasattr(user, "groups"):
+        group = user.groups.first()
+        if group:
+            return group.name.lower()
+    return "authenticated"

django_flex/fields.py

@@ -0,0 +1,234 @@
+"""
+Django-Flex Field Utilities
+
+Handles field parsing, expansion, and model introspection for
+flexible queries.
+
+Features:
+- Parse comma-separated field strings
+- Expand wildcards (* and relation.*)
+- Model field introspection
+- Relation extraction for select_related optimization
+"""
+
+from django_flex.conf import flex_settings
+
+
+def parse_fields(fields_str):
+    """
+    Parse comma-separated field string into list of field specs.
+
+    Args:
+        fields_str: Comma-separated field string (e.g., "name, email")
+
+    Returns:
+        List of field specs
+
+    Examples:
+        >>> parse_fields("name, email")
+        ['name', 'email']
+        >>> parse_fields("id, author.name, author.email")
+        ['id', 'author.name', 'author.email']
+        >>> parse_fields("*, author.*")
+        ['*', 'author.*']
+        >>> parse_fields("")
+        ['*']
+        >>> parse_fields(None)
+        ['*']
+    """
+    if not fields_str:
+        return ["*"]  # Default to all fields
+
+    return [f.strip() for f in fields_str.split(",") if f.strip()]
+
+
+def get_model_fields(model):
+    """
+    Get list of concrete field names for a model.
+
+    Only returns fields with database columns (excludes reverse relations,
+    many-to-many through tables, etc.).
+
+    Args:
+        model: Django model class
+
+    Returns:
+        List of field names
+
+    Example:
+        >>> get_model_fields(User)
+        ['id', 'email', 'username', 'first_name', 'last_name', ...]
+    """
+    fields = []
+    for field in model._meta.get_fields():
+        # Only include concrete fields (not relations or reverse relations)
+        if hasattr(field, "column") and field.column:
+            fields.append(field.name)
+    return fields
+
+
+def get_model_relations(model):
+    """
+    Get dict of relation_name -> related_model for a model.
+
+    Only returns forward relations (ForeignKey, OneToOneField) that
+    can be used in select_related.
+
+    Args:
+        model: Django model class
+
+    Returns:
+        Dict mapping relation name to related model class
+
+    Example:
+        >>> get_model_relations(Entry)
+        {'author': <class 'Author'>, 'blog': <class 'Blog'>}
+    """
+    relations = {}
+    for field in model._meta.get_fields():
+        if hasattr(field, "related_model") and field.related_model:
+            # Forward relations (ForeignKey, OneToOneField)
+            if hasattr(field, "column"):
+                relations[field.name] = field.related_model
+    return relations
+
+
+def expand_wildcard(model, prefix=""):
+    """
+    Expand wildcard into concrete field names.
+
+    Args:
+        model: Django model class
+        prefix: Optional prefix for nested relations
+
+    Returns:
+        List of field names (optionally prefixed)
+
+    Examples:
+        >>> expand_wildcard(Author, "")
+        ['id', 'name', 'email', 'phone']
+        >>> expand_wildcard(Author, "author")
+        ['author.id', 'author.name', 'author.email', 'author.phone']
+    """
+    fields = get_model_fields(model)
+    if prefix:
+        return [f"{prefix}.{f}" for f in fields]
+    return fields
+
+
+def filter_safe_wildcard(model_name, fields, permissions=None):
+    """
+    Remove excluded fields from expanded wildcard list.
+
+    Uses the per-model 'exclude' configuration from permissions to
+    prevent sensitive fields from being exposed via wildcard expansion.
+
+    Args:
+        model_name: Model name for looking up exclusions
+        fields: List of field names to filter
+        permissions: Optional permissions dict (uses settings if not provided)
+
+    Returns:
+        List with excluded fields removed
+    """
+    if permissions is None:
+        permissions = flex_settings.PERMISSIONS
+
+    model_name = model_name.lower()
+    if model_name not in permissions:
+        return fields
+
+    exclude = permissions[model_name].get("exclude", [])
+    return [f for f in fields if f not in exclude]
+
+
+def expand_fields(model, field_specs, model_name=None, permissions=None):
+    """
+    Expand field specs, handling wildcards and nested relations.
+
+    Args:
+        model: Django model class
+        field_specs: List of field specs (e.g., ["*", "author.name"])
+        model_name: Model name for exclude lookup (uses model.__name__ if not provided)
+        permissions: Optional permissions dict
+
+    Returns:
+        List of fully qualified field paths (deduplicated, excluded fields removed)
+
+    Examples:
+        >>> expand_fields(Entry, ["*"])
+        ['id', 'status', 'author_id', 'created_at', ...]
+        >>> expand_fields(Entry, ["id", "author.*"])
+        ['id', 'author.id', 'author.name', 'author.email', ...]
+    """
+    if model_name is None:
+        model_name = model.__name__
+
+    if permissions is None:
+        permissions = flex_settings.PERMISSIONS
+
+    expanded = []
+    relations = get_model_relations(model)
+
+    for spec in field_specs:
+        if spec == "*":
+            # Expand base wildcard to model's concrete fields (minus excluded ones)
+            base_fields = get_model_fields(model)
+            safe_fields = filter_safe_wildcard(model_name, base_fields, permissions)
+            expanded.extend(safe_fields)
+        elif spec.endswith(".*"):
+            # Relation wildcard: author.* -> author.id, author.name, etc.
+            relation_path = spec[:-2]
+            parts = relation_path.split(".")
+
+            # Navigate to the related model
+            current_model = model
+            for part in parts:
+                rel_map = get_model_relations(current_model)
+                if part in rel_map:
+                    current_model = rel_map[part]
+                else:
+                    break
+            else:
+                # Successfully navigated, expand the relation's fields (minus excluded ones)
+                rel_fields = get_model_fields(current_model)
+                # Use the related model's name for exclusion lookup
+                safe_rel_fields = filter_safe_wildcard(current_model.__name__, rel_fields, permissions)
+                expanded.extend([f"{relation_path}.{f}" for f in safe_rel_fields])
+        else:
+            # Regular field or dotted field path
+            expanded.append(spec)
+
+    # Deduplicate while preserving order
+    return list(dict.fromkeys(expanded))
+
+
+def extract_relations(field_paths):
+    """
+    Extract relation paths from field paths for select_related.
+
+    This enables automatic N+1 prevention by identifying which relations
+    need to be eagerly loaded.
+
+    Args:
+        field_paths: List of field paths (may include nested paths)
+
+    Returns:
+        Set of relation paths for select_related (using Django's __ notation)
+
+    Examples:
+        >>> extract_relations(["id", "status"])
+        set()
+        >>> extract_relations(["id", "author.name"])
+        {'author'}
+        >>> extract_relations(["id", "author.blog.city"])
+        {'author__blog'}
+    """
+    relations = set()
+    for path in field_paths:
+        parts = path.split(".")
+        if len(parts) > 1:
+            # Convert author.blog.city -> author__blog (exclude last part which is the field)
+            relation_path = "__".join(parts[:-1])
+            relations.add(relation_path)
+    return relations