thrillwiki_django_no_react/core/api/mixins.py

"""
Common mixins for API views following Django styleguide patterns.
"""

from typing import Dict, Any, Optional
from rest_framework.request import Request
from rest_framework.response import Response
from rest_framework import status


class ApiMixin:
    """
    Base mixin for API views providing standardized response formatting.
    """
    
    def create_response(
        self, 
        *, 
        data: Any = None, 
        message: Optional[str] = None,
        status_code: int = status.HTTP_200_OK,
        pagination: Optional[Dict[str, Any]] = None,
        metadata: Optional[Dict[str, Any]] = None
    ) -> Response:
        """
        Create standardized API response.
        
        Args:
            data: Response data
            message: Optional success message
            status_code: HTTP status code
            pagination: Pagination information
            metadata: Additional metadata
            
        Returns:
            Standardized Response object
        """
        response_data = {
            'status': 'success' if status_code < 400 else 'error',
            'data': data,
        }
        
        if message:
            response_data['message'] = message
            
        if pagination:
            response_data['pagination'] = pagination
            
        if metadata:
            response_data['metadata'] = metadata
            
        return Response(response_data, status=status_code)
    
    def create_error_response(
        self,
        *,
        message: str,
        status_code: int = status.HTTP_400_BAD_REQUEST,
        error_code: Optional[str] = None,
        details: Optional[Dict[str, Any]] = None
    ) -> Response:
        """
        Create standardized error response.
        
        Args:
            message: Error message
            status_code: HTTP status code
            error_code: Optional error code
            details: Additional error details
            
        Returns:
            Standardized error Response object
        """
        error_data = {
            'code': error_code or 'GENERIC_ERROR',
            'message': message,
        }
        
        if details:
            error_data['details'] = details
            
        response_data = {
            'status': 'error',
            'error': error_data,
            'data': None,
        }
        
        return Response(response_data, status=status_code)


class CreateApiMixin(ApiMixin):
    """
    Mixin for create API endpoints with standardized input/output handling.
    """
    
    def create(self, request: Request, *args, **kwargs) -> Response:
        """Handle POST requests for creating resources."""
        serializer = self.get_input_serializer(data=request.data)
        serializer.is_valid(raise_exception=True)
        
        # Create the object using the service layer
        obj = self.perform_create(**serializer.validated_data)
        
        # Serialize the output
        output_serializer = self.get_output_serializer(obj)
        
        return self.create_response(
            data=output_serializer.data,
            status_code=status.HTTP_201_CREATED,
            message="Resource created successfully"
        )
    
    def perform_create(self, **validated_data):
        """
        Override this method to implement object creation logic.
        Should use service layer methods.
        """
        raise NotImplementedError("Subclasses must implement perform_create")
    
    def get_input_serializer(self, *args, **kwargs):
        """Get the input serializer for validation."""
        return self.InputSerializer(*args, **kwargs)
    
    def get_output_serializer(self, *args, **kwargs):
        """Get the output serializer for response.""" 
        return self.OutputSerializer(*args, **kwargs)


class UpdateApiMixin(ApiMixin):
    """
    Mixin for update API endpoints with standardized input/output handling.
    """
    
    def update(self, request: Request, *args, **kwargs) -> Response:
        """Handle PUT/PATCH requests for updating resources."""
        instance = self.get_object()
        serializer = self.get_input_serializer(data=request.data, partial=kwargs.get('partial', False))
        serializer.is_valid(raise_exception=True)
        
        # Update the object using the service layer
        updated_obj = self.perform_update(instance, **serializer.validated_data)
        
        # Serialize the output
        output_serializer = self.get_output_serializer(updated_obj)
        
        return self.create_response(
            data=output_serializer.data,
            message="Resource updated successfully"
        )
    
    def perform_update(self, instance, **validated_data):
        """
        Override this method to implement object update logic.
        Should use service layer methods.
        """
        raise NotImplementedError("Subclasses must implement perform_update")
    
    def get_input_serializer(self, *args, **kwargs):
        """Get the input serializer for validation."""
        return self.InputSerializer(*args, **kwargs)
    
    def get_output_serializer(self, *args, **kwargs):
        """Get the output serializer for response."""
        return self.OutputSerializer(*args, **kwargs)


class ListApiMixin(ApiMixin):
    """
    Mixin for list API endpoints with pagination and filtering.
    """
    
    def list(self, request: Request, *args, **kwargs) -> Response:
        """Handle GET requests for listing resources."""
        # Use selector to get filtered queryset
        queryset = self.get_queryset()
        
        # Apply pagination
        page = self.paginate_queryset(queryset)
        if page is not None:
            serializer = self.get_output_serializer(page, many=True)
            return self.get_paginated_response(serializer.data)
        
        # No pagination
        serializer = self.get_output_serializer(queryset, many=True)
        return self.create_response(data=serializer.data)
    
    def get_queryset(self):
        """
        Override this method to use selector patterns.
        Should call selector functions, not access model managers directly.
        """
        raise NotImplementedError("Subclasses must implement get_queryset using selectors")
    
    def get_output_serializer(self, *args, **kwargs):
        """Get the output serializer for response."""
        return self.OutputSerializer(*args, **kwargs)


class RetrieveApiMixin(ApiMixin):
    """
    Mixin for retrieve API endpoints.
    """
    
    def retrieve(self, request: Request, *args, **kwargs) -> Response:
        """Handle GET requests for retrieving a single resource."""
        instance = self.get_object()
        serializer = self.get_output_serializer(instance)
        
        return self.create_response(data=serializer.data)
    
    def get_object(self):
        """
        Override this method to use selector patterns.
        Should call selector functions for optimized queries.
        """
        raise NotImplementedError("Subclasses must implement get_object using selectors")
    
    def get_output_serializer(self, *args, **kwargs):
        """Get the output serializer for response."""
        return self.OutputSerializer(*args, **kwargs)


class DestroyApiMixin(ApiMixin):
    """
    Mixin for delete API endpoints.
    """
    
    def destroy(self, request: Request, *args, **kwargs) -> Response:
        """Handle DELETE requests for destroying resources."""
        instance = self.get_object()
        
        # Delete using service layer
        self.perform_destroy(instance)
        
        return self.create_response(
            status_code=status.HTTP_204_NO_CONTENT,
            message="Resource deleted successfully"
        )
    
    def perform_destroy(self, instance):
        """
        Override this method to implement object deletion logic.
        Should use service layer methods.
        """
        raise NotImplementedError("Subclasses must implement perform_destroy")
    
    def get_object(self):
        """
        Override this method to use selector patterns.
        Should call selector functions for optimized queries.
        """
        raise NotImplementedError("Subclasses must implement get_object using selectors")