statezero 0.1.0b1__py3-none-any.whl

statezero/adaptors/django/apps.py

@@ -0,0 +1,97 @@
+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
+
+        # 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 (from registry) 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)
+
+            if published_models:
+                base_message = (
+                    "[bold green]StateZero is exposing models:[/bold green] [bold yellow]"
+                    + ", ".join(published_models)
+                    + "[/bold yellow]"  
+                )
+            else:
+                base_message = "[bold yellow]StateZero is running but no models are registered.[/bold yellow]"
+
+            # Append the npm command instruction only in debug mode.
+            if published_models and settings.DEBUG:
+                npm_message = (
+                    "\n[bold blue]Next step:[/bold blue] Run [italic]npm run sync-models[/italic] in your frontend project directory "
+                    "to generate or update the client-side code corresponding to these models. "
+                    "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: {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 your library'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)

statezero/adaptors/django/extensions/custom_field_serializers/file_fields.py

@@ -0,0 +1,141 @@
+from rest_framework import fields
+from rest_framework.fields import empty
+from django.core.exceptions import ObjectDoesNotExist
+from django.core.files.storage import default_storage
+import os
+import mimetypes
+
+image_fields_supported = False
+try:
+    from PIL import Image
+    import io
+    image_fields_supported = True
+except:
+    image_fields_supported = False
+
+class FileFieldSerializer(fields.FileField):
+    """
+    Copy of DRF's FileField but handles file paths instead of file objects.
+    """
+    default_error_messages = {
+        'required': 'No file path provided.',
+        'invalid': 'Not a valid file path.',
+        'no_name': 'No filename could be determined.',
+        'empty': 'The submitted file path is empty.',
+        'max_length': 'Ensure this filename has at most {max_length} characters (it has {length}).',
+        'file_not_found': 'File not found at the specified path.',
+    }
+
+    def __init__(self, **kwargs):
+        self.max_length = kwargs.pop('max_length', None)
+        self.allow_empty_file = kwargs.pop('allow_empty_file', False)
+        super().__init__(**kwargs)
+    
+    def to_representation(self, value):
+        if not value:
+            return None
+        url = super().to_representation(value)
+        mime_type, _ = mimetypes.guess_type(value.name)
+        
+        return {
+            'file_path': value.name,
+            'file_name': os.path.basename(value.name),
+            'file_url': url,
+            'size': value.size,
+            'mime_type': mime_type
+        }
+
+    def to_internal_value(self, data):
+        if data is empty:
+            return None
+        
+        if isinstance(data, dict) and 'file_path' in data:
+            file_path = data.get('file_path')
+        elif isinstance(data, str):
+            file_path = data
+        else:
+            self.fail('invalid')
+        
+        if not isinstance(file_path, str):
+            self.fail('invalid')
+
+        if not file_path:
+            if self.allow_empty_file:
+                return file_path
+            self.fail('empty')
+
+        if self.max_length is not None and len(file_path) > self.max_length:
+            self.fail('max_length', max_length=self.max_length, length=len(file_path))
+
+        if not default_storage.exists(file_path):
+            self.fail('file_not_found')
+
+        return file_path
+
+class ImageFieldSerializer(fields.ImageField):
+    """
+    Copy of DRF's ImageField but handles file paths instead of file objects.
+    """
+    default_error_messages = {
+        'invalid_image': (
+            'Upload a valid image. The file you uploaded was either not an '
+            'image or a corrupted image.'
+        ),
+    }
+
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        
+    def to_representation(self, value):
+        if not value:
+            return None
+        url = super().to_representation(value)
+        
+        return {
+            'file_path': value.name,
+            'file_name': os.path.basename(value.name),
+            'file_url': url,
+            'size': value.size
+        }
+
+    def to_internal_value(self, data):
+        # File path validation logic
+        if data is empty:
+            return None
+        
+        if isinstance(data, dict) and 'file_path' in data:
+            file_path = data.get('file_path')
+        elif isinstance(data, str):
+            file_path = data
+        else:
+            self.fail('invalid')
+
+        if not isinstance(file_path, str):
+            self.fail('invalid')
+
+        if not file_path:
+            if self.allow_empty_file:
+                return file_path
+            self.fail('empty')
+
+        if self.max_length is not None and len(file_path) > self.max_length:
+            self.fail('max_length', max_length=self.max_length, length=len(file_path))
+
+        if not default_storage.exists(file_path):
+            self.fail('file_not_found')
+
+        # Image validation logic
+        if image_fields_supported:
+            try:
+                with default_storage.open(file_path, 'rb') as f:
+                    image = Image.open(f)
+                    image.verify()
+                    
+                    # verify() invalidates the image
+                    f.seek(0)
+                    image = Image.open(f)
+                    
+            except Exception:
+                self.fail('invalid_image')
+
+        return file_path

statezero/adaptors/django/extensions/custom_field_serializers/money_field.py

@@ -0,0 +1,75 @@
+import json
+from decimal import Decimal, InvalidOperation
+from typing import Dict, Tuple
+
+from djmoney.contrib.django_rest_framework.fields import MoneyField
+from djmoney.money import Money
+from rest_framework import serializers
+
+from statezero.core.classes import FieldFormat, FieldType, SchemaFieldMetadata
+from statezero.core.interfaces import AbstractSchemaOverride
+
+class MoneyFieldSerializer(serializers.Field):
+    def __init__(self, **kwargs):
+        self.max_digits = kwargs.pop("max_digits", 14)
+        self.decimal_places = kwargs.pop("decimal_places", 2)
+        super().__init__(**kwargs)
+
+    def to_representation(self, value):
+        djmoney_field = MoneyField(
+            max_digits=self.max_digits, decimal_places=self.decimal_places
+        )
+        amount_representation = djmoney_field.to_representation(value)
+        return {"amount": amount_representation, "currency": value.currency.code}
+
+    def to_internal_value(self, data):
+        if isinstance(data, Money):
+            return data
+        if not isinstance(data, dict):
+            raise serializers.ValidationError(
+                "Input must be an object with 'amount' and 'currency' keys"
+            )
+        try:
+            amount = data["amount"]
+            currency = data["currency"]
+            if isinstance(amount, (str, float, int)):
+                amount = Decimal(amount)
+            return Money(amount, currency)
+        except KeyError:
+            raise serializers.ValidationError("Missing 'amount' or 'currency'")
+        except InvalidOperation:
+            raise serializers.ValidationError("Invalid decimal format")
+
+
+class MoneyFieldSchema(AbstractSchemaOverride):
+    def __init__(self, *args, **kwargs):
+        pass
+
+    def get_schema(
+        field: MoneyField,
+    ) -> Tuple[SchemaFieldMetadata, Dict[str, str], str]:
+        """
+        Generate a schema for MoneyField.
+        This registers a reusable definition and returns a schema metadata object with a $ref.
+        """
+        key = field.__class__.__name__  # i.e. "MoneyField"
+
+        definition = {
+            "type": "object",
+            "properties": {
+                "amount": {"type": "number"},
+                "currency": {"type": "string"},
+            },
+        }
+        # Return a schema metadata object that references this definition.
+        schema = SchemaFieldMetadata(
+            type=FieldType.OBJECT,
+            title="Money",
+            required=True,
+            nullable=field.null,
+            format=FieldFormat.MONEY,
+            description=field.help_text or "Money field",
+            ref=f"#/components/schemas/{key}",
+        )
+
+        return schema, definition, key