turbodrf 0.1.0__py3-none-any.whl

turbodrf/__init__.py

@@ -0,0 +1,55 @@
+"""
+TurboDRF - Dead simple Django REST API generator with role-based permissions.
+
+TurboDRF automatically generates a complete REST API from your Django models
+with just
+a mixin and a configuration method. It provides:
+
+- Automatic CRUD endpoints for all models
+- Role-based permissions at model and field level
+- Built-in search, filtering, ordering, and pagination
+- Nested field support for relationships
+- Auto-generated API documentation with Swagger/ReDoc
+- Zero boilerplate code required
+
+Quick Start:
+    >>> from django.db import models
+    >>> from turbodrf import TurboDRFMixin
+    >>>
+    >>> class Book(models.Model, TurboDRFMixin):
+    ...     title = models.CharField(max_length=200)
+    ...     author = models.CharField(max_length=100)
+    ...
+    ...     @classmethod
+    ...     def turbodrf(cls):
+    ...         return {'fields': ['title', 'author']}
+
+This automatically creates:
+- GET /api/books/ - List all books
+- POST /api/books/ - Create a new book
+- GET /api/books/{id}/ - Get a specific book
+- PUT /api/books/{id}/ - Update a book
+- DELETE /api/books/{id}/ - Delete a book
+
+For more information, see: https://github.com/yourusername/turbodrf
+"""
+
+__version__ = "0.1.0"
+__author__ = "Alexander Collins"
+__email__ = "your.email@example.com"
+__license__ = "MIT"
+
+from .mixins import TurboDRFMixin
+from .permissions import TurboDRFPermission
+from .router import TurboDRFRouter
+from .serializers import TurboDRFSerializer, TurboDRFSerializerFactory
+from .views import TurboDRFViewSet
+
+__all__ = [
+    "TurboDRFMixin",
+    "TurboDRFRouter",
+    "TurboDRFViewSet",
+    "TurboDRFPermission",
+    "TurboDRFSerializer",
+    "TurboDRFSerializerFactory",
+]

turbodrf/apps.py

@@ -0,0 +1,15 @@
+from django.apps import AppConfig
+
+
+class TurboDRFConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "turbodrf"
+    verbose_name = "TurboDRF"
+
+    def ready(self):
+        """
+        Perform initialization when Django starts.
+        """
+        # This ensures models are discovered when Django starts
+        # You can add any other initialization code here
+        pass

turbodrf/documentation.py

@@ -0,0 +1,94 @@
+"""
+TurboDRF API Documentation Module
+
+This module provides automatic API documentation generation for
+TurboDRF-enabled applications. It integrates with drf-yasg to create
+OpenAPI/Swagger documentation
+that respects TurboDRF's role-based access control system.
+
+The documentation is dynamically filtered based on user roles, showing only
+the endpoints and fields that each role has permission to access.
+"""
+
+from django.conf import settings
+from drf_yasg import openapi
+from drf_yasg.views import get_schema_view
+from rest_framework import permissions
+
+
+def get_turbodrf_schema_view():
+    """
+    Create and configure the schema view for TurboDRF API documentation.
+
+    This function sets up a drf-yasg schema view with TurboDRF's custom
+    schema generator that filters API documentation based on user roles
+    and permissions. The generated documentation will only show endpoints
+    and fields that the viewing user has permission to access.
+
+    Features:
+        - Role-based filtering of API endpoints
+        - Dynamic field visibility based on permissions
+        - Automatic schema generation from model configurations
+        - Support for both Swagger UI and ReDoc interfaces
+
+    Returns:
+        SchemaView: A configured drf-yasg SchemaView instance that can be
+                   used to generate multiple documentation formats:
+                   - Swagger UI (interactive HTML)
+                   - ReDoc (alternative HTML documentation)
+                   - OpenAPI JSON/YAML schemas
+
+        Returns None if TURBODRF_ENABLE_DOCS is set to False.
+
+    Usage:
+        # In your urls.py
+        from turbodrf.documentation import get_turbodrf_schema_view
+
+        schema_view = get_turbodrf_schema_view()
+
+        if schema_view:  # Only add URLs if docs are enabled
+            urlpatterns += [
+                path('swagger/',
+                     schema_view.with_ui('swagger', cache_timeout=0)),
+                path('redoc/', schema_view.with_ui('redoc', cache_timeout=0)),
+                path('swagger.json', schema_view.without_ui(cache_timeout=0)),
+            ]
+
+    Configuration:
+        The schema view uses the following configuration:
+        - Title: "TurboDRF API" (customizable)
+        - Version: "v1"
+        - Generator: RoleBasedSchemaGenerator for permission filtering
+        - Permissions: AllowAny (filtering happens at schema level)
+
+        Set TURBODRF_ENABLE_DOCS = False in settings to disable documentation.
+
+    Note:
+        While the view itself allows any user to access the documentation,
+        the RoleBasedSchemaGenerator ensures that users only see the parts
+        of the API they have permission to use based on their roles.
+    """
+    # Check if documentation is enabled
+    if not getattr(settings, "TURBODRF_ENABLE_DOCS", True):
+        return None
+
+    from .swagger import RoleBasedSchemaGenerator
+
+    schema_view = get_schema_view(
+        openapi.Info(
+            title="TurboDRF API",
+            default_version="v1",
+            description=(
+                "Auto-generated API with role-based access control "
+                "powered by TurboDRF"
+            ),
+            terms_of_service="https://www.example.com/terms/",
+            contact=openapi.Contact(email="contact@example.com"),
+            license=openapi.License(name="MIT License"),
+        ),
+        public=True,
+        permission_classes=[permissions.AllowAny],
+        generator_class=RoleBasedSchemaGenerator,
+    )
+
+    return schema_view

turbodrf/filters.py

@@ -0,0 +1,64 @@
+"""
+Advanced filtering support for TurboDRF
+"""
+
+from django.db.models import Q
+
+
+class TurboDRFFilter:
+    """Advanced filtering with support for complex queries."""
+
+    @classmethod
+    def parse_filters(cls, queryset, params):
+        """
+        Parse query parameters and apply filters.
+
+        Supports:
+        - field=value (exact match)
+        - field__gt=value (greater than)
+        - field__contains=value (contains)
+        - field__in=value1,value2 (in list)
+        - etc.
+        """
+        for key, value in params.items():
+            if key in ["page", "page_size", "search", "ordering", "format"]:
+                continue
+
+            # Handle special operators
+            if "__in" in key:
+                # Convert comma-separated values to list
+                value = value.split(",")
+
+            try:
+                queryset = queryset.filter(**{key: value})
+            except Exception:
+                # Skip invalid filters
+                pass
+
+        return queryset
+
+    @classmethod
+    def parse_search(cls, queryset, search_term, search_fields):
+        """
+        Apply search across multiple fields.
+
+        Supports:
+        - Simple search: searches all fields
+        - Field-specific: field:term
+        - Quoted: "exact phrase"
+        """
+        if not search_term or not search_fields:
+            return queryset
+
+        # Check for field-specific search
+        if ":" in search_term:
+            field, term = search_term.split(":", 1)
+            if field in search_fields:
+                return queryset.filter(**{f"{field}__icontains": term})
+
+        # Build OR query for all search fields
+        q_objects = Q()
+        for field in search_fields:
+            q_objects |= Q(**{f"{field}__icontains": search_term})
+
+        return queryset.filter(q_objects)

turbodrf/metadata.py

@@ -0,0 +1,110 @@
+from rest_framework.metadata import SimpleMetadata
+
+
+class TurboDRFMetadata(SimpleMetadata):
+    """Custom metadata handler for TurboDRF OPTIONS requests."""
+
+    def determine_metadata(self, request, view):
+        """Return metadata for OPTIONS requests."""
+        metadata = super().determine_metadata(request, view)
+
+        if hasattr(view, "model"):
+            model = view.model
+            view_type = (
+                "detail"
+                if view.action in ["retrieve", "update", "partial_update"]
+                else "list"
+            )
+            fields = model.get_api_fields(view_type)
+
+            # Add model info
+            metadata["model"] = {
+                "name": model._meta.verbose_name,
+                "app_label": model._meta.app_label,
+                "fields": self._get_field_metadata(model, fields, request.user),
+            }
+
+            # Add allowed actions based on permissions
+            metadata["actions"] = self._get_allowed_actions(model, request.user)
+
+        return metadata
+
+    def _get_field_metadata(self, model, fields, user):
+        """Get metadata for each field."""
+        from .settings import TURBODRF_ROLES
+
+        user_permissions = set()
+        if hasattr(user, "roles"):
+            for role in user.roles:
+                user_permissions.update(TURBODRF_ROLES.get(role, []))
+
+        field_metadata = {}
+        app_label = model._meta.app_label
+        model_name = model._meta.model_name
+
+        for field_name in fields:
+            if "__" in field_name:
+                # Handle nested fields
+                base_field = field_name.split("__")[0]
+                if base_field not in field_metadata:
+                    field_metadata[base_field] = {"type": "nested", "fields": []}
+                field_metadata[base_field]["fields"].append(
+                    field_name.split("__", 1)[1]
+                )
+            else:
+                try:
+                    field = model._meta.get_field(field_name)
+                    can_read = (
+                        f"{app_label}.{model_name}.{field_name}.read"
+                        in user_permissions
+                    )
+                    can_write = (
+                        f"{app_label}.{model_name}.{field_name}.write"
+                        in user_permissions
+                    )
+
+                    field_info = {
+                        "type": field.__class__.__name__,
+                        "required": (
+                            not field.blank if hasattr(field, "blank") else True
+                        ),
+                        "read_only": not can_write,
+                        "write_only": not can_read and can_write,
+                        "label": field.verbose_name,
+                        "help_text": field.help_text or "",
+                    }
+
+                    # Add field-specific metadata
+                    if hasattr(field, "max_length"):
+                        field_info["max_length"] = field.max_length
+                    if hasattr(field, "choices") and field.choices:
+                        field_info["choices"] = [
+                            {"value": k, "display": v} for k, v in field.choices
+                        ]
+
+                    field_metadata[field_name] = field_info
+                except Exception:
+                    field_metadata[field_name] = {"type": "unknown"}
+
+        return field_metadata
+
+    def _get_allowed_actions(self, model, user):
+        """Get allowed actions based on user permissions."""
+        from .settings import TURBODRF_ROLES
+
+        user_permissions = set()
+        if hasattr(user, "roles"):
+            for role in user.roles:
+                user_permissions.update(TURBODRF_ROLES.get(role, []))
+
+        app_label = model._meta.app_label
+        model_name = model._meta.model_name
+
+        return {
+            "list": f"{app_label}.{model_name}.read" in user_permissions,
+            "retrieve": f"{app_label}.{model_name}.read" in user_permissions,
+            "create": f"{app_label}.{model_name}.create" in user_permissions,
+            "update": f"{app_label}.{model_name}.update" in user_permissions,
+            "partial_update": (f"{app_label}.{model_name}.update" in user_permissions),
+            "destroy": f"{app_label}.{model_name}.delete" in user_permissions,
+        }

turbodrf/mixins.py

@@ -0,0 +1,160 @@
+"""
+Core mixins for TurboDRF.
+
+This module provides the TurboDRFMixin that enables automatic API generation
+for Django models.
+"""
+
+from django.core.exceptions import FieldDoesNotExist
+
+
+class TurboDRFMixin:
+    """
+    Mixin to add TurboDRF capabilities to Django models.
+
+    This mixin enables automatic REST API generation for any Django model.
+    By inheriting from this mixin and defining a turbodrf() classmethod,
+    models will be automatically discovered and exposed via REST endpoints.
+
+    Example:
+        >>> class Book(models.Model, TurboDRFMixin):
+        ...     title = models.CharField(max_length=200)
+        ...     author = models.CharField(max_length=100)
+        ...     price = models.DecimalField(max_digits=10, decimal_places=2)
+        ...
+        ...     # Optional: Define searchable fields
+        ...     searchable_fields = ['title', 'author']
+        ...
+        ...     @classmethod
+        ...     def turbodrf(cls):
+        ...         return {
+        ...             'fields': ['title', 'author', 'price']
+        ...         }
+
+    The mixin provides several helper methods for field introspection and
+    configuration that are used internally by TurboDRF.
+    """
+
+    @classmethod
+    def turbodrf(cls):
+        """
+        Configure the API for this model.
+
+        This method should be overridden in subclasses to provide
+        model-specific configuration for the auto-generated API.
+
+        Returns:
+            dict: Configuration dictionary with the following keys:
+                - 'enabled' (bool): Whether to enable API for this model.
+                  Defaults to True.
+                - 'endpoint' (str): Custom endpoint name. If not provided,
+                  defaults to the pluralized model name.
+                - 'fields' (list|dict|str): Fields to expose in the API.
+                  Can be:
+                  - A list of field names: ['title', 'author', 'price']
+                  - A dict with different fields for list/detail views:
+                    {'list': ['title', 'author'], 'detail': '__all__'}
+                  - The string '__all__' to include all fields
+
+        Example:
+            >>> @classmethod
+            ... def turbodrf(cls):
+            ...     return {
+            ...         'fields': {
+            ...             'list': ['title', 'author__name', 'price'],
+            ...             'detail': ['title', 'author__name',
+            ...                       'author__email', 'price',
+            ...                       'description', 'created_at']
+            ...         },
+            ...         'endpoint': 'books',
+            ...         'enabled': True
+            ...     }
+        """
+        return {
+            "enabled": True,
+            "endpoint": f"{cls._meta.model_name}s",
+            "fields": "__all__",
+        }
+
+    @classmethod
+    def get_api_fields(cls, view_type="list"):
+        """
+        Get fields for a specific view type.
+
+        This method resolves the fields configuration based on the view type
+        (list or detail). It handles the various field configuration formats
+        supported by TurboDRF.
+
+        Args:
+            view_type (str): The type of view ('list' or 'detail').
+                Defaults to 'list'.
+
+        Returns:
+            list: List of field names to include in the API response.
+
+        Example:
+            >>> Book.get_api_fields('list')
+            ['title', 'author', 'price']
+            >>> Book.get_api_fields('detail')
+            ['title', 'author', 'price', 'description', 'created_at']
+        """
+        config = cls.turbodrf()
+        fields = config.get("fields", "__all__")
+
+        if fields == "__all__":
+            # Get all model fields except reverse relations
+            return [
+                f.name
+                for f in cls._meta.get_fields()
+                if not f.many_to_many and not f.one_to_many
+            ]
+
+        if isinstance(fields, dict):
+            # Different fields for list/detail views
+            return fields.get(view_type, [])
+
+        # If it's a list, use for both views
+        return fields
+
+    @classmethod
+    def get_field_type(cls, field_path):
+        """
+        Resolve field type for nested fields.
+
+        This method traverses relationships to determine the type of a field
+        specified using Django's double-underscore notation
+        (e.g., 'author__name').
+
+        Args:
+            field_path (str): Field path using double-underscore notation.
+                Example: 'author__name' or 'category__parent__name'
+
+        Returns:
+            Field: The Django field instance, or None if the field
+            doesn't exist.
+
+        Example:
+            >>> Book.get_field_type('author__name')
+            <django.db.models.fields.CharField: name>
+            >>> Book.get_field_type('nonexistent__field')
+            None
+        """
+        parts = field_path.split("__")
+        model = cls
+
+        # Traverse relationships
+        for part in parts[:-1]:
+            try:
+                field = model._meta.get_field(part)
+                if hasattr(field, "related_model"):
+                    model = field.related_model
+                else:
+                    return None
+            except FieldDoesNotExist:
+                return None
+
+        # Get the final field
+        try:
+            return model._meta.get_field(parts[-1])
+        except FieldDoesNotExist:
+            return None

turbodrf/permissions.py

@@ -0,0 +1,181 @@
+"""
+Role-based permissions for TurboDRF.
+
+This module provides the permission classes that enforce role-based
+access control for the auto-generated APIs.
+"""
+
+from rest_framework.permissions import BasePermission, DjangoModelPermissions
+
+
+class TurboDRFPermission(BasePermission):
+    """
+    Permission class that checks against role-based permissions.
+
+    This permission class implements a flexible role-based access control
+    system for TurboDRF. It checks user roles against configured permissions
+    to determine access to API endpoints.
+
+    Permission Format:
+        Permissions follow the pattern: app_label.model_name.action
+
+        Model-level permissions:
+        - 'books.book.read' - Can view books
+        - 'books.book.create' - Can create books
+        - 'books.book.update' - Can update books
+        - 'books.book.delete' - Can delete books
+
+        Field-level permissions (checked separately):
+        - 'books.book.price.read' - Can view price field
+        - 'books.book.price.write' - Can modify price field
+
+    Configuration:
+        Define roles and permissions in Django settings:
+
+        TURBODRF_ROLES = {
+            'admin': [
+                'books.book.read',
+                'books.book.create',
+                'books.book.update',
+                'books.book.delete',
+                'books.book.price.read',
+                'books.book.price.write',
+            ],
+            'editor': [
+                'books.book.read',
+                'books.book.update',
+                'books.book.price.read',  # Read-only access to price
+            ],
+            'viewer': [
+                'books.book.read',
+                # No access to price field
+            ]
+        }
+
+    Special Cases:
+        - Unauthenticated users are allowed read-only access (GET requests)
+        - Users must have a 'roles' property that returns a list of role names
+    """
+
+    def has_permission(self, request, view):
+        """
+        Check if the user has permission to perform the requested action.
+
+        Args:
+            request: The incoming HTTP request.
+            view: The view being accessed.
+
+        Returns:
+            bool: True if permission is granted, False otherwise.
+        """
+        # Allow read access for unauthenticated users (viewer role)
+        if not request.user or not request.user.is_authenticated:
+            # Only allow GET and OPTIONS requests for unauthenticated users
+            return request.method in ["GET", "OPTIONS"]
+
+        if not hasattr(request.user, "roles"):
+            return False
+
+        user_permissions = self._get_user_permissions(request.user)
+        model = view.model
+        app_label = model._meta.app_label
+        model_name = model._meta.model_name
+
+        # Map HTTP methods to permission types
+        permission_map = {
+            "GET": "read",
+            "POST": "create",
+            "PUT": "update",
+            "PATCH": "update",
+            "DELETE": "delete",
+            "OPTIONS": "read",  # OPTIONS should have same permission as read
+        }
+
+        permission_type = permission_map.get(request.method)
+        if not permission_type:
+            return False
+
+        # Check model-level permission
+        required_permission = f"{app_label}.{model_name}.{permission_type}"
+        return required_permission in user_permissions
+
+    def _get_user_permissions(self, user):
+        """
+        Get all permissions for a user based on their roles.
+
+        This method aggregates permissions from all roles assigned to a user.
+
+        Args:
+            user: The user object, which must have a 'roles' property.
+
+        Returns:
+            set: Set of permission strings the user has.
+
+        Example:
+            If a user has roles ['admin', 'editor'], this method returns
+            the union of all permissions defined for both roles.
+        """
+        from django.conf import settings
+
+        from .settings import TURBODRF_ROLES as default_roles
+
+        # Use Django settings if available, otherwise fall back to defaults
+        TURBODRF_ROLES = getattr(settings, "TURBODRF_ROLES", default_roles)
+
+        permissions = set()
+        for role in user.roles:
+            permissions.update(TURBODRF_ROLES.get(role, []))
+
+        return permissions
+
+
+class DefaultDjangoPermission(DjangoModelPermissions):
+    """
+    Default permission class using Django's built-in model permissions.
+
+    This permission class provides a simpler alternative to TurboDRF's role-based
+    permissions by using Django's standard permission system. When a user has
+    write permission for a model, they have write access to all fields.
+
+    Features:
+        - Uses Django's built-in auth permissions (add, change, delete, view)
+        - Integrates with Django admin permissions
+        - No field-level permissions (all fields are accessible based on
+          model permissions)
+        - Works with Django's User and Group models out of the box
+
+    Usage:
+        To use Django's default permissions instead of TurboDRF's
+        role-based system,
+        set TURBODRF_USE_DEFAULT_PERMISSIONS = True in your settings.
+
+    Permission Mapping:
+        - GET: requires 'view' permission
+        - POST: requires 'add' permission
+        - PUT/PATCH: requires 'change' permission
+        - DELETE: requires 'delete' permission
+    """
+
+    # Extend the default perms map to include OPTIONS
+    perms_map = {
+        "GET": ["%(app_label)s.view_%(model_name)s"],
+        "OPTIONS": ["%(app_label)s.view_%(model_name)s"],
+        "HEAD": ["%(app_label)s.view_%(model_name)s"],
+        "POST": ["%(app_label)s.add_%(model_name)s"],
+        "PUT": ["%(app_label)s.change_%(model_name)s"],
+        "PATCH": ["%(app_label)s.change_%(model_name)s"],
+        "DELETE": ["%(app_label)s.delete_%(model_name)s"],
+    }
+
+    def has_permission(self, request, view):
+        """
+        Check if the user has permission to perform the requested action.
+
+        For unauthenticated users, allows read-only access by default.
+        """
+        # Allow read access for unauthenticated users
+        if not request.user or not request.user.is_authenticated:
+            return request.method in ["GET", "OPTIONS", "HEAD"]
+
+        # For authenticated users, use Django's permission system
+        return super().has_permission(request, view)