statezero 0.1.0b20__py3-none-any.whl

statezero/adaptors/django/actions.py

@@ -0,0 +1,248 @@
+import os
+from django.apps import apps
+from rest_framework.response import Response
+from rest_framework import fields, serializers
+from django.db import models
+from statezero.core.actions import action_registry
+
+class DjangoActionSchemaGenerator:
+    """Django-specific action schema generator that matches StateZero model schema format"""
+
+    @staticmethod
+    def generate_actions_schema():
+        """Generate schema for all registered actions matching StateZero model schema format"""
+        actions_schema = {}
+        all_app_configs = list(apps.get_app_configs())
+
+        for action_name, action_config in action_registry.get_actions().items():
+            func = action_config.get("function")
+            if not func:
+                raise ValueError(
+                    f"Action '{action_name}' is missing a function and cannot be processed."
+                )
+
+            func_path = os.path.abspath(func.__code__.co_filename)
+            found_app = None
+
+            for app_config in all_app_configs:
+                app_path = os.path.abspath(app_config.path)
+                if func_path.startswith(app_path + os.sep):
+                    if not found_app or len(app_path) > len(
+                        os.path.abspath(found_app.path)
+                    ):
+                        found_app = app_config
+
+            if not found_app:
+                raise LookupError(
+                    f"Action '{action_name}' from file '{func_path}' does not belong to any "
+                    f"installed Django app. Please ensure the parent app is in INSTALLED_APPS."
+                )
+
+            app_name = found_app.label
+            docstring = action_config.get("docstring")
+
+            input_properties, input_relationships = DjangoActionSchemaGenerator._get_serializer_schema(
+                action_config["serializer"]
+            )
+            response_properties, response_relationships = DjangoActionSchemaGenerator._get_serializer_schema(
+                action_config["response_serializer"]
+            )
+
+            # Serialize display metadata if present
+            display_data = None
+            if action_config.get("display"):
+                display_data = DjangoActionSchemaGenerator._serialize_display_metadata(
+                    action_config["display"]
+                )
+
+            schema_info = {
+                "action_name": action_name,
+                "app": app_name,
+                "title": action_name.replace("_", " ").title(),
+                "docstring": docstring,
+                "class_name": "".join(
+                    word.capitalize() for word in action_name.split("_")
+                ),
+                "input_properties": input_properties,
+                "response_properties": response_properties,
+                "relationships": {**input_relationships, **response_relationships},
+                "permissions": [
+                    perm.__name__ for perm in action_config.get("permissions", [])
+                ],
+                "display": display_data,
+            }
+            actions_schema[action_name] = schema_info
+
+        return Response({"actions": actions_schema, "count": len(actions_schema)})
+
+    @staticmethod
+    def _get_serializer_schema(serializer_class):
+        if not serializer_class:
+            return {}, {}
+        try:
+            serializer_instance = serializer_class()
+            properties = {}
+            relationships = {}
+            for field_name, field in serializer_instance.fields.items():
+                relation_info = DjangoActionSchemaGenerator._get_relation_info(field)
+                if relation_info:
+                    relationships[field_name] = relation_info
+                
+                field_info = {
+                    "type": DjangoActionSchemaGenerator._get_field_type(field),
+                    "title": getattr(field, "label")
+                    or field_name.replace("_", " ").title(),
+                    "required": field.required,
+                    "description": getattr(field, "help_text", None),
+                    "nullable": getattr(field, "allow_null", False),
+                    "format": DjangoActionSchemaGenerator._get_field_format(field),
+                    "max_length": getattr(field, "max_length", None),
+                    "choices": DjangoActionSchemaGenerator._get_field_choices(field),
+                    "default": DjangoActionSchemaGenerator._get_field_default(field),
+                    "validators": [],
+                    "max_digits": getattr(field, "max_digits", None),
+                    "decimal_places": getattr(field, "decimal_places", None),
+                    "read_only": field.read_only,
+                    "ref": None,
+                }
+                if hasattr(field, "max_value") and field.max_value is not None:
+                    field_info["max_value"] = field.max_value
+                if hasattr(field, "min_value") and field.min_value is not None:
+                    field_info["min_value"] = field.min_value
+                if hasattr(field, "min_length") and field.min_length is not None:
+                    field_info["min_length"] = field.min_length
+                properties[field_name] = field_info
+            return properties, relationships
+        except Exception as e:
+            print(f"Could not inspect serializer: {str(e)}")
+            raise e
+
+    @staticmethod
+    def _get_field_type(field):
+        if isinstance(field, serializers.PrimaryKeyRelatedField):
+            pk_field = field.queryset.model._meta.pk
+            if isinstance(pk_field, (models.UUIDField, models.CharField)):
+                return "string"
+            return "integer"
+
+        # Handle nested serializers (many=True creates a ListSerializer)
+        if isinstance(field, serializers.ListSerializer):
+            return "array"
+
+        # Handle nested serializers (single nested serializer)
+        if isinstance(field, serializers.Serializer):
+            return "object"
+
+        type_mapping = {
+            fields.BooleanField: "boolean",
+            fields.CharField: "string",
+            fields.EmailField: "string",
+            fields.URLField: "string",
+            fields.UUIDField: "string",
+            fields.IntegerField: "integer",
+            fields.FloatField: "number",
+            fields.DecimalField: "string",
+            fields.DateField: "string",
+            fields.DateTimeField: "string",
+            fields.TimeField: "string",
+            fields.JSONField: "object",
+            fields.DictField: "object",
+            fields.ListField: "array",
+            serializers.ManyRelatedField: "array",
+        }
+        return type_mapping.get(type(field), "string")
+
+    @staticmethod
+    def _get_field_format(field):
+        format_mapping = {
+            fields.EmailField: "email",
+            fields.URLField: "uri",
+            fields.UUIDField: "uuid",
+            fields.DateField: "date",
+            fields.DateTimeField: "date-time",
+            fields.TimeField: "time",
+            serializers.ManyRelatedField: "many-to-many",
+            serializers.PrimaryKeyRelatedField: "foreign-key",
+        }
+        return format_mapping.get(type(field))
+
+    @staticmethod
+    def _get_field_choices(field):
+        if hasattr(field, "choices") and field.choices:
+            choices = field.choices
+            
+            # Handle dict format: {'low': 'Low', 'high': 'High'}
+            if isinstance(choices, dict):
+                return choices
+            
+            # Handle list/tuple format: [('low', 'Low'), ('high', 'High')]
+            elif isinstance(choices, (list, tuple)):
+                try:
+                    # Return dict with value->label mapping (same as model)
+                    return {str(choice[0]): choice[1] for choice in choices}
+                except (IndexError, TypeError) as e:
+                    raise ValueError(
+                        f"Invalid choice format for field '{field}'. Expected list of tuples "
+                        f"like [('value', 'display')], but got: {choices}. Error: {e}"
+                    )
+            
+            # Handle unexpected format
+            else:
+                raise ValueError(
+                    f"Unsupported choice format for field '{field}'. Expected dict or list of tuples, "
+                    f"but got {type(choices)}: {choices}"
+                )
+        
+        return None
+
+    @staticmethod
+    def _get_field_default(field):
+        if hasattr(field, "default"):
+            default = field.default
+            if default is fields.empty:
+                return None
+            if callable(default):
+                return None
+            return default
+        return None
+    
+    @staticmethod
+    def _get_relation_info(field):
+        relation_type = DjangoActionSchemaGenerator._get_field_format(field)
+        if not relation_type in ["foreign-key", "one-to-one", "many-to-many"]:
+            return None
+
+        if isinstance(field, serializers.PrimaryKeyRelatedField):
+            model = field.queryset.model
+            return {
+                "type": relation_type,
+                "model": f"{model._meta.app_label}.{model._meta.model_name}",
+                "class_name": model.__name__,
+                "primary_key_field": model._meta.pk.name,
+            }
+        if isinstance(field, serializers.ManyRelatedField):
+            model = field.child_relation.queryset.model
+            return {
+                "type": relation_type,
+                "model": f"{model._meta.app_label}.{model._meta.model_name}",
+                "class_name": model.__name__,
+                "primary_key_field": model._meta.pk.name,
+            }
+        return None
+
+    @staticmethod
+    def _serialize_display_metadata(display):
+        """Convert DisplayMetadata dataclass to dict for JSON serialization"""
+        from dataclasses import asdict, is_dataclass
+
+        if display is None:
+            return None
+
+        if is_dataclass(display):
+            return asdict(display)
+
+        # If it's already a dict, return as-is
+        if isinstance(display, dict):
+            return display
+
+        return None

statezero/adaptors/django/apps.py

@@ -0,0 +1,137 @@
+import importlib
+import logging
+import os
+
+from django.apps import AppConfig as DjangoAppConfig
+from django.apps import apps
+from django.conf import settings
+
+from statezero.adaptors.django.config import config, registry
+
+# Attempt to import Rich for nicer console output.
+try:
+    from rich.console import Console
+    from rich.panel import Panel
+
+    console = Console()
+except ImportError:
+    console = None
+
+logger = logging.getLogger(__name__)
+
+
+class StateZeroDjangoConfig(DjangoAppConfig):
+    name = "statezero.adaptors.django"
+    verbose_name = "StateZero Django Integration"
+    label = "statezero"
+
+    def ready(self):
+        # Import crud modules which register models in the registry.
+        if hasattr(settings, "CONFIG_FILE_PREFIX"):
+            config_file_prefix: str = settings.CONFIG_FILE_PREFIX
+            config_file_prefix = config_file_prefix.replace(".py", "")
+            if (not isinstance(config_file_prefix, str)) or (
+                len(config_file_prefix) < 1
+            ):
+                raise ValueError(
+                    f"If provided, CONFIG_FILE_PREFIX must be a string with at least one character. In your settings.py it is set to {settings.CONFIG_FILE_PREFIX}. Either delete the setting completely or use a valid file name like 'crud'"
+                )
+        else:
+            config_file_prefix = "crud"
+        for app_config_instance in apps.get_app_configs():
+            module_name = f"{app_config_instance.name}.{config_file_prefix}"
+            try:
+                importlib.import_module(module_name)
+                logger.debug(
+                    f"Imported {config_file_prefix} module from {app_config_instance.name}"
+                )
+            except ModuleNotFoundError:
+                pass
+
+        # Import actions modules which register actions in the action registry.
+        from statezero.core.actions import action_registry
+
+        for app_config_instance in apps.get_app_configs():
+            actions_module_name = f"{app_config_instance.name}.actions"
+            try:
+                importlib.import_module(actions_module_name)
+                logger.debug(f"Imported actions module from {app_config_instance.name}")
+            except ModuleNotFoundError:
+                pass
+
+        # Once all the apps are imported, initialize StateZero and provide the registry to the event bus.
+        config.initialize()
+        config.validate_exposed_models(
+            registry
+        )  # Raises an exception if a non StateZero model is implicitly exposed
+        config.event_bus.set_registry(registry)
+
+        # Print the list of published models and actions to confirm StateZero is running.
+        try:
+            published_models = []
+            for model in registry._models_config.keys():
+                # Use the ORM provider's get_model_name to get the namespaced model name.
+                model_name = model.__name__
+                published_models.append(model_name)
+
+            # Get registered actions
+            registered_actions = list(action_registry.get_actions().keys())
+
+            # Build base message for models
+            if published_models:
+                models_message = (
+                    "[bold green]StateZero is exposing models:[/bold green] [bold yellow]"
+                    + ", ".join(published_models)
+                    + "[/bold yellow]"
+                )
+            else:
+                models_message = "[bold yellow]StateZero is running but no models are registered.[/bold yellow]"
+
+            # Build message for actions (limit to first 10 to avoid cluttering console)
+            if registered_actions:
+                displayed_actions = registered_actions[:10]
+                actions_message = (
+                    "\n[bold green]StateZero is exposing actions:[/bold green] [bold cyan]"
+                    + ", ".join(displayed_actions)
+                )
+                if len(registered_actions) > 10:
+                    actions_message += (
+                        f" [dim](and {len(registered_actions) - 10} more)[/dim]"
+                    )
+                actions_message += "[/bold cyan]"
+            else:
+                actions_message = (
+                    "\n[bold yellow]No actions are registered.[/bold yellow]"
+                )
+
+            base_message = models_message + actions_message
+
+            # Append the npm command instruction only in debug mode.
+            if (published_models or registered_actions) and settings.DEBUG:
+                npm_message = (
+                    "\n[bold blue]Next step:[/bold blue] Run [italic]npm run sync[/italic] in your frontend project directory "
+                    "to generate or update the client-side code corresponding to these models and actions. "
+                    "Note: This command should only be executed in a development environment."
+                )
+                message = base_message + npm_message
+            else:
+                message = base_message
+
+            # Use Rich Panel for a boxed display if Rich is available.
+            if console:
+                final_message = Panel(message, expand=False)
+                console.print(final_message)
+            else:
+                # Fallback to simple demarcation lines if Rich isn't available.
+                demarcation = "\n" + "-" * 50 + "\n"
+                final_message = demarcation + message + demarcation
+                logger.info(final_message)
+        except Exception as e:
+            error_message = f"[bold red]Error retrieving published models and actions: {e}[/bold red]"
+            if console:
+                final_message = Panel(error_message, expand=False)
+                console.print(final_message)
+            else:
+                demarcation = "\n" + "-" * 50 + "\n"
+                final_message = demarcation + error_message + demarcation
+                logger.info(final_message)

statezero/adaptors/django/config.py

@@ -0,0 +1,99 @@
+import logging
+
+from django.conf import settings
+from django.core.exceptions import ImproperlyConfigured
+from django.utils.module_loading import import_string
+import warnings
+
+from statezero.adaptors.django.query_optimizer import DjangoQueryOptimizer
+from statezero.adaptors.django.context_manager import query_timeout
+from statezero.core.config import AppConfig, Registry
+from django.db.models import FileField
+
+try:
+    from django.db.models import ImageField
+    image_field_available = True
+except ImportError:
+    ImageField = None
+    image_field_available = False
+
+logger = logging.getLogger(__name__)
+
+class DjangoLocalConfig(AppConfig):
+    def __init__(self):
+        self.DEBUG = settings.DEBUG
+
+    def initialize(self):
+        from statezero.adaptors.django.event_emitters import \
+            DjangoPusherEventEmitter, DjangoConsoleEventEmitter
+        from statezero.adaptors.django.orm import DjangoORMAdapter
+        from statezero.adaptors.django.schemas import DjangoSchemaGenerator
+        from statezero.adaptors.django.serializers import DRFDynamicSerializer
+        from statezero.adaptors.django.search_providers.basic_search import BasicSearchProvider
+        from statezero.core.event_bus import EventBus
+
+        # Initialize serializer, schema generator, and ORM adapter.
+        self.serializer = DRFDynamicSerializer()
+        self.schema_generator = DjangoSchemaGenerator()
+        self.orm_provider = DjangoORMAdapter()
+        self.context_manager = query_timeout
+        self.query_optimizer = DjangoQueryOptimizer
+
+        # Instantiate emitters by injecting only the necessary functions.
+        if hasattr(settings, 'STATEZERO_PUSHER'):
+            event_emitter = DjangoPusherEventEmitter()
+        else:
+            warnings.warn("You have not added STATEZERO_PUSHER to your settings.py. Live model changes will not be broadcast")
+            event_emitter = DjangoConsoleEventEmitter()
+        
+        # Create the EventBus with two explicit emitters.
+        self.event_bus = EventBus(
+            broadcast_emitter=event_emitter,
+            orm_provider=self.orm_provider,
+        )
+
+        # Setup the search provider
+        self.search_provider = BasicSearchProvider()
+        
+        self.file_upload_callbacks = None
+
+        # Explicitly register event signals after both components are configured.
+        self.orm_provider.register_event_signals(self.event_bus)
+        
+        from statezero.adaptors.django.extensions.custom_field_serializers.file_fields import (
+            FileFieldSerializer, ImageFieldSerializer)
+
+        # Initialize custom serializers
+        self.custom_serializers = {
+            FileField: FileFieldSerializer
+        }
+        
+        if image_field_available:
+            self.custom_serializers[ImageField] = ImageFieldSerializer
+
+        # Try to register djmoney support
+        try:
+            from statezero.adaptors.django.extensions.custom_field_serializers.money_field import (
+            MoneyFieldSchema, MoneyFieldSerializer)
+            from djmoney.models.fields import MoneyField
+            self.custom_serializers[MoneyField] = MoneyFieldSerializer
+            self.schema_overrides = {
+                MoneyField: MoneyFieldSchema,
+            }
+        except Exception:
+            self.schema_overrides = {}
+
+
+# Create the singleton instances.
+custom_config_path = getattr(settings, "STATEZERO_CUSTOM_CONFIG", None)
+if custom_config_path:
+    custom_config_class = import_string(custom_config_path)
+    if not issubclass(custom_config_class, AppConfig):
+        raise ImproperlyConfigured(
+            "STATEZERO_CUSTOM_CONFIG must be a subclass of AppConfig"
+        )
+    config = custom_config_class()
+else:
+    config = DjangoLocalConfig()
+
+registry = Registry()

statezero/adaptors/django/context_manager.py

@@ -0,0 +1,12 @@
+from contextlib import contextmanager
+from django.db import connection
+
+@contextmanager
+def query_timeout(timeout_ms):
+    if connection.vendor == 'postgresql':
+        with connection.cursor() as cursor:
+            cursor.execute(f'SET LOCAL statement_timeout = {timeout_ms};')
+            yield
+    else:
+        # For SQLite or others, no operation
+        yield

statezero/adaptors/django/event_emitters.py

@@ -0,0 +1,78 @@
+from typing import Optional
+import logging
+from django.conf import settings
+from rest_framework.request import Request
+from django.utils.module_loading import import_string
+
+from statezero.core.event_emitters import ConsoleEventEmitter, PusherEventEmitter
+
+logger = logging.getLogger(__name__)
+
+
+class DjangoConsoleEventEmitter(ConsoleEventEmitter):
+    def __init__(self) -> None:
+        super().__init__()
+        
+        permission_class_path = getattr(
+            settings,
+            "STATEZERO_VIEW_ACCESS_CLASS",
+            "rest_framework.permissions.IsAuthenticated",
+        )
+        try:
+            self.permission_class = import_string(permission_class_path)()
+            logger.debug("Using emitter permission class: %s", permission_class_path)
+        except Exception as e:
+            logger.error("Error importing emitter permission class '%s': %s", permission_class_path, str(e))
+            from rest_framework.permissions import IsAuthenticated
+            self.permission_class = IsAuthenticated()
+
+    def has_permission(self, request: Request, namespace: str) -> bool:
+        return self.permission_class.has_permission(request, None)
+
+
+class DjangoPusherEventEmitter(PusherEventEmitter):
+    def __init__(
+        self,
+        app_id: Optional[str] = None,
+        key: Optional[str] = None,
+        secret: Optional[str] = None,
+        cluster: Optional[str] = None,
+    ) -> None:
+        import pusher
+        
+        app_id = app_id or settings.STATEZERO_PUSHER.get("APP_ID")
+        key = key or settings.STATEZERO_PUSHER.get("KEY")
+        secret = secret or settings.STATEZERO_PUSHER.get("SECRET")
+        cluster = cluster or settings.STATEZERO_PUSHER.get("CLUSTER")
+        
+        if not all([app_id, key, secret, cluster]):
+            raise ValueError(
+                "Pusher credentials must be provided via parameters or defined in settings as "
+                "'APP_ID', 'KEY', 'SECRET', and 'CLUSTER'."
+            )
+            
+        pusher_client = pusher.Pusher(
+            app_id=app_id,
+            key=key,
+            secret=secret,
+            cluster=cluster,
+            ssl=True,
+        )
+        
+        super().__init__(pusher_client=pusher_client)
+        
+        permission_class_path = getattr(
+            settings,
+            "STATEZERO_VIEW_ACCESS_CLASS",
+            "rest_framework.permissions.IsAuthenticated",
+        )
+        try:
+            self.permission_class = import_string(permission_class_path)()
+            logger.debug("Using emitter permission class: %s", permission_class_path)
+        except Exception as e:
+            logger.error("Error importing emitter permission class '%s': %s", permission_class_path, str(e))
+            from rest_framework.permissions import IsAuthenticated
+            self.permission_class = IsAuthenticated()
+
+    def has_permission(self, request: Request, namespace: str) -> bool:
+        return self.permission_class.has_permission(request, None)

statezero/adaptors/django/exception_handler.py

@@ -0,0 +1,98 @@
+import logging
+import traceback
+
+from django.conf import settings
+from django.core.exceptions import \
+    MultipleObjectsReturned as DjangoMultipleObjectsReturned
+from django.core.exceptions import ObjectDoesNotExist
+from django.core.exceptions import PermissionDenied as DjangoPermissionDenied
+from django.core.exceptions import ValidationError as DjangoValidationError
+# Import Django/DRF exceptions.
+from django.db.models import Model
+from django.http import Http404
+from fastapi.encoders import jsonable_encoder  # Requires fastapi dependency
+from rest_framework import status
+from rest_framework.exceptions import NotFound as DRFNotFound
+from rest_framework.exceptions import PermissionDenied as DRFPermissionDenied
+from rest_framework.exceptions import ValidationError as DRFValidationError
+from rest_framework.response import Response
+
+# Import your custom StateZero exception types.
+from statezero.core.exceptions import (ErrorDetail, StateZeroError,
+                                       MultipleObjectsReturned, NotFound,
+                                       PermissionDenied, ValidationError)
+
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.DEBUG)
+
+
+def map_exception(exc):
+    """
+    Map Django/DRF exceptions to your library’s errors.
+    If the exception is already one of your library's types, return it as is.
+    """
+    logger.debug("Mapping exception type: %s", type(exc))
+
+    if isinstance(exc, StateZeroError):
+        return exc
+
+    if isinstance(exc, type) and issubclass(exc, Model.DoesNotExist):
+        return NotFound(detail=str(exc))
+
+    if isinstance(exc, DjangoMultipleObjectsReturned):
+        return MultipleObjectsReturned(detail=str(exc))
+    if isinstance(exc, (ObjectDoesNotExist, Http404)):
+        return NotFound(detail=str(exc))
+    if isinstance(exc, DjangoValidationError):
+        detail = getattr(exc, "message_dict", getattr(exc, "messages", str(exc)))
+        return ValidationError(detail=detail)
+    if isinstance(exc, DjangoPermissionDenied):
+        return PermissionDenied(detail=str(exc))
+
+    if isinstance(exc, DRFValidationError):
+        return ValidationError(detail=exc.detail)
+    if isinstance(exc, DRFNotFound):
+        return NotFound(detail=str(exc))
+    if isinstance(exc, DRFPermissionDenied):
+        return PermissionDenied(detail=str(exc))
+
+    return exc
+
+
+def explicit_exception_handler(exc):
+    """
+    Extended explicit exception handler that builds a structured JSON response.
+    It maps known Django/DRF exceptions to StateZero's standard errors and
+    uses jsonable_encoder to ensure the output is JSON serializable.
+    """
+    traceback.print_exc()
+    exc = map_exception(exc)
+    logger.debug("Using exception type after mapping: %s", type(exc))
+    
+    if isinstance(exc, NotFound):
+        status_code = status.HTTP_404_NOT_FOUND
+    elif isinstance(exc, PermissionDenied):
+        status_code = status.HTTP_403_FORBIDDEN
+    elif isinstance(exc, ValidationError):
+        status_code = status.HTTP_400_BAD_REQUEST
+    else:
+        status_code = getattr(exc, "status_code", status.HTTP_500_INTERNAL_SERVER_ERROR)
+    
+    # Only show detailed errors for 400 and 404 in production
+    # For 403 and 500 errors, only show details in debug mode
+    if status_code in [status.HTTP_403_FORBIDDEN, status.HTTP_500_INTERNAL_SERVER_ERROR] and not settings.DEBUG:
+        if status_code == status.HTTP_403_FORBIDDEN:
+            detail = "Permission denied"
+        else:
+            detail = "Internal server error"
+    else:
+        detail = jsonable_encoder(exc.detail) if hasattr(exc, "detail") else str(exc)
+    
+    error_data = {
+        "status": status_code,
+        "type": exc.__class__.__name__,
+        "detail": detail,
+    }
+    
+    logger.error("Exception handled explicitly: %s", error_data)
+    return Response(error_data, status=status_code)