django-flex 26.1.0__py3-none-any.whl

django_flex/views.py

@@ -0,0 +1,236 @@
+"""
+Django-Flex Views
+
+Provides Django class-based views for handling flexible queries.
+
+Features:
+- FlexQueryView for easy integration
+- Automatic permission handling
+- Configurable per-view settings
+"""
+
+from django.http import JsonResponse
+from django.views import View
+from django.views.decorators.csrf import csrf_exempt
+from django.utils.decorators import method_decorator
+
+import json
+
+from django_flex.query import FlexQuery
+from django_flex.response import FlexResponse
+
+
+@method_decorator(csrf_exempt, name="dispatch")
+class FlexQueryView(View):
+    """
+    Generic view for handling flexible queries.
+
+    Subclass this view and configure the model and permissions
+    to create an endpoint for flexible queries.
+
+    Example:
+        # views.py
+        from django_flex.views import FlexQueryView
+        from myapp.models import Entry
+
+        class EntryQueryView(FlexQueryView):
+            model = Entry
+
+            # Optional: custom permissions
+            flex_permissions = {
+                'staff': {
+                    'rows': lambda user: Q(),
+                    'fields': ['*', 'blog.*'],
+                    'filters': ['rating', 'rating.gte', 'blog.name.icontains'],
+                    'order_by': ['pub_date', '-pub_date'],
+                    'ops': ['get', 'query'],
+                },
+            }
+
+        # urls.py
+        from django.urls import path
+        from myapp.views import EntryQueryView
+
+        urlpatterns = [
+            path('api/entries/', EntryQueryView.as_view(), name='entry-query'),
+        ]
+    """
+
+    # Required: the model to query
+    model = None
+
+    # Optional: custom permissions (uses settings.DJANGO_FLEX.PERMISSIONS if not set)
+    flex_permissions = None
+
+    # Optional: require authentication
+    require_auth = True
+
+    # Optional: allowed actions
+    allowed_actions = ["get", "query"]
+
+    def get_model(self):
+        """Get the model to query. Override for dynamic model selection."""
+        return self.model
+
+    def get_permissions(self):
+        """Get permissions configuration. Override for dynamic permissions."""
+        return self.flex_permissions
+
+    def get_user(self, request):
+        """Get the user for permission checking. Override for custom auth."""
+        return request.user if hasattr(request, "user") else None
+
+    def check_auth(self, request):
+        """Check authentication. Override for custom auth logic."""
+        if not self.require_auth:
+            return True
+
+        user = self.get_user(request)
+        return user and user.is_authenticated
+
+    def get_query_spec(self, request):
+        """
+        Extract query specification from request.
+
+        Override to customize how queries are parsed from requests.
+        Default: parse JSON body for POST, query params for GET.
+        """
+        if request.method == "POST":
+            try:
+                return json.loads(request.body)
+            except json.JSONDecodeError:
+                return None
+        else:
+            # Parse from query params
+            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 post(self, request, *args, **kwargs):
+        """Handle POST request for queries."""
+        return self.handle_query(request)
+
+    def get(self, request, *args, **kwargs):
+        """Handle GET request for queries."""
+        return self.handle_query(request)
+
+    def handle_query(self, request):
+        """
+        Main query handler.
+
+        Validates authentication, parses query spec, and executes query.
+        """
+        # Check authentication
+        if not self.check_auth(request):
+            return JsonResponse(
+                FlexResponse.error("PERMISSION_DENIED", "Authentication required").to_dict(),
+                status=401,
+            )
+
+        # Get model
+        model = self.get_model()
+        if model is None:
+            return JsonResponse(
+                FlexResponse.error("MODEL_NOT_FOUND", "Model not configured").to_dict(),
+                status=500,
+            )
+
+        # Get query spec
+        query_spec = self.get_query_spec(request)
+        if query_spec is None:
+            return JsonResponse(
+                FlexResponse.error("INVALID_FILTER", "Invalid query specification").to_dict(),
+                status=400,
+            )
+
+        # Determine action
+        action = "get" if "id" in query_spec else "query"
+        if action not in self.allowed_actions:
+            return JsonResponse(
+                FlexResponse.error("PERMISSION_DENIED", f"Action '{action}' not allowed").to_dict(),
+                status=403,
+            )
+
+        # Execute query
+        user = self.get_user(request)
+        permissions = self.get_permissions()
+
+        query = FlexQuery(model)
+        if permissions:
+            query.set_permissions(self._build_permissions_dict(permissions))
+
+        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)
+
+    def _build_permissions_dict(self, flex_permissions):
+        """Build a permissions dict compatible with the permission system."""
+        model_name = self.get_model().__name__.lower()
+        return {model_name: flex_permissions}
+
+
+class FlexModelView(FlexQueryView):
+    """
+    Model-specific view with URL-based model selection.
+
+    Allows querying multiple models from a single endpoint based on
+    the URL parameter.
+
+    Example:
+        # urls.py
+        urlpatterns = [
+            path('api/<str:model_name>/', FlexModelView.as_view(), name='flex-query'),
+        ]
+
+        # Requests:
+        # POST /api/entry/ -> query Entry model
+        # POST /api/author/ -> query Author model
+    """
+
+    # List of allowed model names (security measure)
+    allowed_models = []
+
+    def get_model(self):
+        """Get model from URL."""
+        model_name = self.kwargs.get("model_name", "")
+
+        # Security check: only allow configured models
+        if self.allowed_models and model_name.lower() not in [m.lower() for m in self.allowed_models]:
+            return None
+
+        from django_flex.query import get_model_by_name
+
+        return get_model_by_name(model_name)

django_flex-26.1.0.dist-info/METADATA

@@ -0,0 +1,300 @@
+Metadata-Version: 2.4
+Name: django-flex
+Version: 26.1.0
+Summary: A flexible query language for Django - enable frontends to dynamically construct database queries
+Author: Nehemiah Jacob
+Maintainer: Nehemiah Jacob
+License: MIT
+Project-URL: Homepage, https://github.com/your-org/django-flex
+Project-URL: Documentation, https://github.com/your-org/django-flex#readme
+Project-URL: Repository, https://github.com/your-org/django-flex.git
+Project-URL: Issues, https://github.com/your-org/django-flex/issues
+Project-URL: Changelog, https://github.com/your-org/django-flex/blob/main/CHANGELOG.md
+Keywords: django,query,api,flexible,dynamic,graphql-alternative,rest,orm
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 3.2
+Classifier: Framework :: Django :: 4.0
+Classifier: Framework :: Django :: 4.1
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: django>=3.2
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-django>=4.5; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: isort>=5.12; extra == "dev"
+Requires-Dist: flake8>=6.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: django-stubs>=4.0; extra == "dev"
+Dynamic: license-file
+
+# Django-Flex
+
+[![PyPI version](https://badge.fury.io/py/django-flex.svg)](https://pypi.org/project/django-flex/)
+[![Python versions](https://img.shields.io/pypi/pyversions/django-flex.svg)](https://pypi.org/project/django-flex/)
+[![Django versions](https://img.shields.io/badge/django-3.2%20%7C%204.x%20%7C%205.x%20%7C%206.x-blue.svg)](https://www.djangoproject.com/)
+
+**A flexible query language for Django** — Enable frontends to dynamically construct database queries with built-in security.
+
+## Features
+
+- 🔍 **Dynamic Field Selection** — Request only the fields you need
+- 🔬 **Rich Filtering** — Full Django ORM operator support
+- 📄 **Built-in Pagination** — Limit/offset with smart cursor support
+- 🔐 **Layered Security** — Row, field, filter, and operation-level access control
+- ⚡ **N+1 Prevention** — Automatic `select_related` optimization
+- 🎯 **Django Native** — Uses Django's built-in auth (groups, permissions)
+
+## Installation
+
+```bash
+pip install django-flex
+```
+
+```python
+# settings.py
+INSTALLED_APPS = [
+    ...
+    'django_flex',
+]
+```
+
+## Quick Start
+
+Using Django's official documentation models: Blog, Author, Entry.
+
+### 1. Create a View
+
+```python
+# views.py
+from datetime import date
+from django.db.models import Q
+from django_flex import FlexQueryView
+from .models import Entry
+
+class EntryQueryView(FlexQueryView):
+    model = Entry
+
+    flex_permissions = {
+        'staff': {
+            'rows': lambda user: Q(),  # All entries
+            'fields': ['*', 'blog.*'],
+            'filters': ['id', 'rating.gte', 'blog.id', 'headline.icontains'],
+            'order_by': ['-pub_date', 'rating'],
+            'ops': ['get', 'query'],
+        },
+        'authenticated': {
+            'rows': lambda user: Q(pub_date__lte=date.today()),
+            'fields': ['id', 'headline', 'pub_date', 'blog.name'],
+            'filters': ['id', 'headline.icontains'],
+            'order_by': ['-pub_date'],
+            'ops': ['get', 'query'],
+        },
+    }
+```
+
+### 2. Add URL Route
+
+```python
+# urls.py
+from .views import EntryQueryView
+
+urlpatterns = [
+    path('api/entries/', EntryQueryView.as_view()),
+]
+```
+
+### 3. Query from Frontend
+
+```javascript
+// Query entries
+const response = await fetch('/api/entries/', {
+    method: 'POST',
+    headers: {'Content-Type': 'application/json'},
+    body: JSON.stringify({
+        fields: 'id, headline, pub_date, blog.name',
+        filters: { 'rating.gte': 4 },
+        order_by: '-pub_date',
+        limit: 20
+    })
+});
+
+// Response
+{
+    "success": true,
+    "code": "FLEX_OK_QUERY",
+    "pagination": {"offset": 0, "limit": 20, "has_more": false},
+    "results": {
+        "1": {"id": 1, "headline": "Django 5.0 Released", "pub_date": "2024-01-15", "blog": {"name": "Django News"}},
+        "2": {"id": 2, "headline": "Getting Started Guide", "pub_date": "2024-01-14", "blog": {"name": "Tutorials"}}
+    }
+}
+```
+
+## Query Language
+
+### Field Selection
+
+```javascript
+fields: 'id, headline'              // Specific fields
+fields: '*'                          // All model fields
+fields: '*, blog.*'                  // All fields + related
+fields: 'id, blog.name, blog.tagline'  // Nested fields
+```
+
+### Filtering
+
+```javascript
+// Simple equality
+filters: { rating: 5 }
+
+// Operators
+filters: { 'rating.gte': 4 }           // Greater than or equal
+filters: { 'rating.in': [4, 5] }       // In list
+filters: { 'headline.icontains': 'django' }  // Case-insensitive search
+filters: { 'pub_date.gte': '2024-01-01' }    // Date comparison
+
+// Composition
+filters: { or: { rating: 5, 'number_of_comments.gte': 100 } }
+filters: { not: { 'rating.lt': 3 } }
+```
+
+### Pagination
+
+```javascript
+limit: 20       // Max results
+offset: 40      // Skip first 40
+
+// Response includes next cursor
+pagination: {
+    offset: 40,
+    limit: 20,
+    has_more: true,
+    next: { fields: '...', limit: 20, offset: 60 }
+}
+```
+
+## Security Configuration
+
+Django-Flex uses Django's built-in auth for role resolution:
+
+1. `superuser` → bypasses all checks
+2. `staff` → `user.is_staff`
+3. `<group_name>` → first Django group
+4. `authenticated` → logged in, no group
+
+```python
+# settings.py
+DJANGO_FLEX = {
+    'DEFAULT_LIMIT': 50,
+    'MAX_LIMIT': 200,
+    'MAX_RELATION_DEPTH': 2,
+
+    'PERMISSIONS': {
+        'entry': {
+            'exclude': ['internal_notes'],
+
+            'staff': {
+                'rows': lambda user: Q(),
+                'fields': ['*', 'blog.*'],
+                'filters': ['id', 'rating.gte', 'pub_date.gte', 'blog.id'],
+                'order_by': ['-pub_date', '-rating'],
+                'ops': ['get', 'query', 'create', 'update', 'delete'],
+            },
+            'authenticated': {
+                'rows': lambda user: Q(pub_date__lte=date.today()),
+                'fields': ['id', 'headline', 'pub_date', 'rating'],
+                'filters': ['id'],
+                'order_by': ['-pub_date'],
+                'ops': ['get', 'query'],
+            },
+        },
+    },
+}
+```
+
+## Usage Patterns
+
+### Class-Based View
+
+```python
+from django_flex import FlexQueryView
+
+class EntryQueryView(FlexQueryView):
+    model = Entry
+    flex_permissions = {...}
+```
+
+### Decorator
+
+```python
+from django_flex import flex_query
+
+@flex_query(
+    model=Entry,
+    allowed_fields=['id', 'headline', 'blog.name'],
+    allowed_filters=['id', 'headline.icontains'],
+    allowed_actions=['get', 'query'],
+)
+def entry_query(request, result, query_spec):
+    return JsonResponse(result.to_dict())
+```
+
+### Programmatic
+
+```python
+from django_flex import FlexQuery
+
+result = FlexQuery(Entry).execute({
+    'fields': 'id, headline, blog.name',
+    'filters': {'rating.gte': 4},
+}, user=request.user)
+```
+
+## Supported Operators
+
+| Category | Operators |
+|----------|-----------|
+| Comparison | `lt`, `lte`, `gt`, `gte`, `exact`, `in`, `isnull`, `range` |
+| Text | `contains`, `icontains`, `startswith`, `endswith`, `regex` |
+| Date/Time | `date`, `year`, `month`, `day`, `hour`, `minute`, `second` |
+| Composition | `and`, `or`, `not` |
+
+## Response Codes
+
+| Code | Description |
+|------|-------------|
+| `FLEX_OK` | Single object retrieved |
+| `FLEX_OK_QUERY` | Query results returned |
+| `FLEX_LIMIT_CLAMPED` | Results returned, limit was reduced |
+| `FLEX_NOT_FOUND` | Object not found |
+| `FLEX_PERMISSION_DENIED` | Access denied |
+| `FLEX_INVALID_FILTER` | Invalid filter syntax |
+
+## Documentation
+
+- [Installation Guide](docs/installation.md)
+- [Quick Start](docs/quickstart.md)
+- [Permissions Guide](docs/permissions.md)
+- [API Reference](docs/api_reference.md)
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.

django_flex-26.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+django_flex/__init__.py,sha256=m_7w1s_pKA2V6XJmCs2OI2zztIn4Gh7PMXQHY5rnE4s,1929
+django_flex/conf.py,sha256=yZZfu-7UhEAdV6YdDfHHxiR52LoR9OKPn62SO3rM4Ow,2460
+django_flex/decorators.py,sha256=07kUaZ1K0ko5dNmH53krEtzpmZtPswIWA468-jk9BGg,6251
+django_flex/fields.py,sha256=Q-pNpg2xIJ4rUJh9YG2hMjCZQYW7KX-cmRDrvh5Rn4g,7162
+django_flex/filters.py,sha256=XDwDsGP3V0NVZRWma5ZD82f4hWo1n8FGjwWwRTuHPJc,5595
+django_flex/middleware.py,sha256=EcjvagijCW5cZ5XYjt6-6-lfFNr1fyyJYUR6_IFSni8,4232
+django_flex/permissions.py,sha256=4Fyki_3FtTo5QDe9IRIc6MFF2ZvK8ia4D7p46ubF76U,11019
+django_flex/query.py,sha256=nqMmoFygD_t308LpmzbOgMIEcsOp_aKsEDYqcZKfFPM,9380
+django_flex/response.py,sha256=9iTT-FMimAeRTm5X4WyYO6fc_EbL9yw7uJxb8pIDQ70,5496
+django_flex/views.py,sha256=ZHxBtPKyGeQ3I_2jVXSz_F1KuEyqFNy7Laq5wknyPxY,7399
+django_flex-26.1.0.dist-info/licenses/LICENSE,sha256=iMZHDgZuRwKZQjbArgnHtDAWCBr7fzln345UATCMat4,1071
+django_flex-26.1.0.dist-info/METADATA,sha256=37UW4rLUBSOy_AtevCAqEThPI57M_cJGQD3OsfefLBY,8685
+django_flex-26.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+django_flex-26.1.0.dist-info/top_level.txt,sha256=Zgjf1KylVfiV2cXdAQNyPzz5zXSgU4lmKG8aGhSxXuE,12
+django_flex-26.1.0.dist-info/RECORD,,

django_flex-26.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

django_flex-26.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nehemiah Jacob
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

django_flex-26.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+django_flex