statezero 0.1.0b4__py3-none-any.whl → 0.1.0b6__py3-none-any.whl

statezero/adaptors/django/urls.py

@@ -1,6 +1,6 @@
 from django.urls import path
 
-from .views import EventsAuthView, ModelListView, ModelView, SchemaView, FileUploadView, FastUploadView
+from .views import EventsAuthView, ModelListView, ModelView, SchemaView, FileUploadView, FastUploadView, ActionSchemaView, ActionView
 
 app_name = "statezero"
 
@@ -9,6 +9,8 @@ urlpatterns = [
     path("models/", ModelListView.as_view(), name="model_list"),
     path("files/upload/", FileUploadView.as_view(), name="file_upload"),
     path("files/fast-upload/", FastUploadView.as_view(), name="fast_file_upload"),
+    path("actions/<str:action_name>/", ActionView.as_view(), name="action"),
+    path("actions-schema/", ActionSchemaView.as_view(), name="actions_schema"),
     path("<str:model_name>/", ModelView.as_view(), name="model_view"),
-    path("<str:model_name>/get-schema/", SchemaView.as_view(), name="schema_view")
-]
+    path("<str:model_name>/get-schema/", SchemaView.as_view(), name="schema_view"),
+]

statezero/adaptors/django/views.py

@@ -12,15 +12,20 @@ from django.utils.module_loading import import_string
 from datetime import datetime
 from django.conf import settings
 from django.core.files.storage import default_storage
+from statezero.core.exceptions import NotFound, PermissionDenied
 import math
+from typing import Type
 import mimetypes
 
 from statezero.adaptors.django.config import config, registry
 from statezero.adaptors.django.exception_handler import \
     explicit_exception_handler
 from statezero.adaptors.django.permissions import ORMBridgeViewAccessGate
-from statezero.core.interfaces import AbstractEventEmitter
+from statezero.adaptors.django.actions import DjangoActionSchemaGenerator
+from statezero.core.interfaces import AbstractEventEmitter, AbstractActionPermission
 from statezero.core.process_request import RequestProcessor
+from statezero.core.actions import action_registry
+from statezero.core.interfaces import AbstractActionPermission
 
 logger = logging.getLogger(__name__)
 logger.setLevel(logging.DEBUG)
@@ -114,7 +119,7 @@ class SchemaView(APIView):
         except Exception as original_exception:
             return explicit_exception_handler(original_exception)
         return Response(result, status=status.HTTP_200_OK)
-    
+
 class FileUploadView(APIView):
     """Standard file upload - returns permanent URL"""
     parser_classes = [MultiPartParser]
@@ -161,17 +166,17 @@ class FileUploadView(APIView):
 class FastUploadView(APIView):
     """Fast upload with S3 presigned URLs - single or multipart based on chunks"""
     permission_classes = [permission_class]
-    
+
     def post(self, request):
         action = request.data.get('action', 'initiate')
-        
+
         if action == 'initiate':
             return self._initiate_upload(request)
         elif action == 'complete':
             return self._complete_upload(request)
         else:
             return Response({'error': 'Invalid action'}, status=400)
-    
+
     def _initiate_upload(self, request):
         """Generate presigned URLs - single or multipart based on num_chunks"""
         filename = request.data.get('filename')
@@ -179,24 +184,24 @@ class FastUploadView(APIView):
         file_size = request.data.get('file_size', 0)
         num_chunks_str = request.data.get('num_chunks', 1)  # Client decides chunking
         num_chunks = int(num_chunks_str)
-        
+
         if not filename:
             return Response({'error': 'filename required'}, status=400)
-        
+
         # Generate file path
         upload_dir = getattr(settings, 'STATEZERO_UPLOAD_DIR', 'statezero')
         file_path = f"{upload_dir}/{filename}"
-        
+
         if not content_type:
             content_type, _ = mimetypes.guess_type(filename)
             content_type = content_type or 'application/octet-stream'
-        
+
         if not self._is_s3_storage():
             return Response({'error': 'Fast upload requires S3 storage backend'}, status=400)
-        
+
         try:
             s3_client = self._get_s3_client()
-            
+
             if num_chunks == 1:
                 # Single upload (existing logic)
                 presigned_url = s3_client.generate_presigned_url(
@@ -209,28 +214,28 @@ class FastUploadView(APIView):
                     ExpiresIn=3600,
                     HttpMethod='PUT',
                 )
-                
+
                 return Response({
                     'upload_type': 'single',
                     'upload_url': presigned_url,
                     'file_path': file_path,
                     'content_type': content_type
                 })
-            
+
             else:
                 # Multipart upload
                 if num_chunks > 10000:
                     return Response({'error': 'Too many chunks (max 10,000)'}, status=400)
-                
+
                 # Initiate multipart upload
                 response = s3_client.create_multipart_upload(
                     Bucket=settings.AWS_STORAGE_BUCKET_NAME,
                     Key=file_path,
                     ContentType=content_type
                 )
-                
+
                 upload_id = response['UploadId']
-                
+
                 # Generate presigned URLs for all parts
                 upload_urls = {}
                 for part_number in range(1, num_chunks + 1):
@@ -246,7 +251,7 @@ class FastUploadView(APIView):
                         HttpMethod='PUT'
                     )
                     upload_urls[part_number] = url
-                
+
                 return Response({
                     'upload_type': 'multipart',
                     'upload_id': upload_id,
@@ -254,51 +259,51 @@ class FastUploadView(APIView):
                     'file_path': file_path,
                     'content_type': content_type
                 })
-                
+
         except Exception as e:
             logger.error(f"Upload initiation failed: {e}")
             return Response({'error': 'Upload unavailable'}, status=500)
-    
+
     def _complete_upload(self, request):
         """Complete upload - single or multipart"""
         file_path = request.data.get('file_path')
         original_name = request.data.get('original_name')
         upload_id = request.data.get('upload_id')  # Only present for multipart
         parts = request.data.get('parts', [])  # Only present for multipart
-        
+
         if not file_path:
             return Response({'error': 'file_path required'}, status=400)
-        
+
         try:
             if upload_id and parts:
                 # Complete multipart upload
                 s3_client = self._get_s3_client()
-                
+
                 # Sort parts by PartNumber to ensure correct order
                 sorted_parts = sorted(parts, key=lambda x: x['PartNumber'])
-                
+
                 response = s3_client.complete_multipart_upload(
                     Bucket=settings.AWS_STORAGE_BUCKET_NAME,
                     Key=file_path,
                     UploadId=upload_id,
                     MultipartUpload={'Parts': sorted_parts}
                 )
-                
+
                 logger.info(f"Multipart upload completed for {file_path}")
-            
+
             # For single uploads, file is already there after PUT
             # For multipart, it's now assembled
-            
+
             if not default_storage.exists(file_path):
                 return Response({'error': 'File not found'}, status=404)
-            
+
             return Response({
                 'file_path': file_path,
                 'file_url': default_storage.url(file_path),
                 'original_name': original_name,
                 'size': default_storage.size(file_path)
             })
-            
+
         except Exception as e:
             logger.error(f"Upload completion failed: {e}")
             # Clean up failed multipart upload
@@ -314,7 +319,7 @@ class FastUploadView(APIView):
                 except Exception as cleanup_error:
                     logger.error(f"Failed to abort multipart upload: {cleanup_error}")
             return Response({'error': 'Upload completion failed'}, status=500)
-    
+
     def _get_s3_client(self):
         """Get S3 client"""
         import boto3
@@ -325,7 +330,7 @@ class FastUploadView(APIView):
             aws_secret_access_key=settings.AWS_SECRET_ACCESS_KEY,
             endpoint_url=getattr(settings, 'AWS_S3_ENDPOINT_URL', None)
         )
-    
+
     def _is_s3_storage(self) -> bool:
         """Check if using S3-compatible storage"""
         try:
@@ -333,4 +338,101 @@ class FastUploadView(APIView):
             from storages.backends.s3 import S3Storage
         except ImportError:
             return False
-        return isinstance(default_storage, (S3Boto3Storage, S3Storage))
+        return isinstance(default_storage, (S3Boto3Storage, S3Storage))
+
+
+class ActionView(APIView):
+    """
+    Django view to handle StateZero action execution.
+    It uses a single try/except block to catch all errors, including
+    not found actions and permission denials, and formats them with the
+    explicit_exception_handler.
+    """
+
+    permission_classes = [ORMBridgeViewAccessGate]
+
+    def post(self, request, action_name):
+        """Execute a registered action."""
+        try:
+            action_config = action_registry.get_action(action_name)
+
+            if not action_config:
+                # Raise an exception to be handled by the central handler
+                raise NotFound(detail=f"Action '{action_name}' not found")
+
+            # This will raise PermissionDenied on failure
+            self._check_permissions(request, action_config, action_name)
+
+            # Validate input data
+            validated_data = {}
+            if action_config["serializer"]:
+                serializer = action_config["serializer"](
+                    data=request.data, context={"request": request}
+                )
+                # Using raise_exception=True automatically triggers the handler
+                # for validation errors.
+                serializer.is_valid(raise_exception=True)
+                validated_data = serializer.validated_data
+            else:
+                validated_data = request.data
+
+            # This will also raise PermissionDenied on failure
+            self._check_action_permissions(
+                request, action_config, action_name, validated_data
+            )
+
+            # Execute the core action function
+            action_func = action_config["function"]
+            result = action_func(**validated_data, request=request)
+
+            # Validate the response data
+            if action_config["response_serializer"]:
+                response_serializer = action_config["response_serializer"](data=result)
+                if not response_serializer.is_valid():
+                    # This indicates an issue with the action's implementation
+                    return Response(
+                        {
+                            "error": f"Action returned invalid response: {response_serializer.errors}"
+                        },
+                        status=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                    )
+                return Response(response_serializer.validated_data)
+            else:
+                return Response(result)
+
+        except Exception as original_exception:
+            # This single block now handles all runtime exceptions
+            return explicit_exception_handler(original_exception)
+
+    def _check_permissions(self, request, action_config, action_name) -> None:
+        """Check view-level permissions, raising an exception on failure."""
+        permissions = action_config.get("permissions", [])
+        for permission_class in permissions:
+            permission_instance = permission_class()
+            if not permission_instance.has_permission(request, action_name):
+                raise PermissionDenied(
+                    detail="You do not have permission to perform this action."
+                )
+
+    def _check_action_permissions(
+        self, request, action_config, action_name, validated_data
+    ) -> None:
+        """Check action-level permissions, raising an exception on failure."""
+        permissions = action_config.get("permissions", [])
+        for permission_class in permissions:
+            permission_instance: Type[AbstractActionPermission] = permission_class()
+            if not permission_instance.has_action_permission(
+                request, action_name, validated_data
+            ):
+                raise PermissionDenied(
+                    detail="You do not have permission for this specific request."
+                )
+
+
+class ActionSchemaView(APIView):
+    """Django view to provide action schema information for frontend generation"""
+    permission_classes = [ORMBridgeViewAccessGate]
+    
+    def get(self, request):
+        """Return schema information for all registered actions"""
+        return DjangoActionSchemaGenerator.generate_actions_schema()

statezero/core/actions.py

@@ -0,0 +1,88 @@
+import inspect
+from typing import Dict, Any, Callable, List, Union, Optional
+from .interfaces import AbstractActionPermission
+
+
+class ActionRegistry:
+    """Framework-agnostic action registry"""
+
+    def __init__(self):
+        self._actions: Dict[str, Dict] = {}
+
+    def register(
+        self,
+        func: Callable = None,
+        *,
+        docstring: Optional[str] = None,
+        serializer=None,
+        response_serializer=None,
+        permissions: Union[
+            List[AbstractActionPermission], AbstractActionPermission, None
+        ] = None,
+        name: Optional[str] = None,
+    ):
+        """Register an action function with an optional, explicit docstring."""
+
+        def decorator(func: Callable):
+            action_name = name or func.__name__
+
+            # Determine the docstring, prioritizing the explicit parameter over the function's own.
+            final_docstring = docstring or func.__doc__
+            if final_docstring:
+                # Clean up indentation and whitespace from the docstring.
+                final_docstring = inspect.cleandoc(final_docstring)
+
+            if permissions is None:
+                permission_list = []
+            elif isinstance(permissions, list):
+                permission_list = permissions
+            else:
+                permission_list = [permissions]
+
+            self._actions[action_name] = {
+                "function": func,
+                "serializer": serializer,
+                "response_serializer": response_serializer,
+                "permissions": permission_list,
+                "name": action_name,
+                "module": func.__module__,
+                "docstring": final_docstring,  # Store the determined docstring
+            }
+            return func
+
+        if func is None:
+            return decorator
+        return decorator(func)
+
+    def get_actions(self) -> Dict[str, Dict]:
+        return self._actions
+
+    def get_action(self, name: str) -> Optional[Dict]:
+        return self._actions.get(name)
+
+
+# Global registry instance
+action_registry = ActionRegistry()
+
+
+# Convenient decorator
+def action(
+    func: Callable = None,
+    *,
+    docstring: Optional[str] = None,
+    serializer=None,
+    response_serializer=None,
+    permissions: Union[
+        List[AbstractActionPermission], AbstractActionPermission, None
+    ] = None,
+    name: Optional[str] = None,
+):
+    """Framework-agnostic decorator to register an action."""
+    return action_registry.register(
+        func,
+        docstring=docstring,
+        serializer=serializer,
+        response_serializer=response_serializer,
+        permissions=permissions,
+        name=name,
+    )