statezero 0.1.0b11__tar.gz → 0.1.0b13__tar.gz

{statezero-0.1.0b11 → statezero-0.1.0b13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: statezero
-Version: 0.1.0b11
+Version: 0.1.0b13
 Summary: Connect your Python backend to a modern JavaScript SPA frontend with 90% less complexity.
 Author-email: Robert <robert.herring@statezero.dev>
 Project-URL: homepage, https://www.statezero.dev

{statezero-0.1.0b11 → statezero-0.1.0b13}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "statezero"
-version = "0.1.0b11"
+version = "0.1.0b13"
 description = "Connect your Python backend to a modern JavaScript SPA frontend with 90% less complexity."
 readme = "README.md"
 license = { file = "LICENSE" }

{statezero-0.1.0b11 → statezero-0.1.0b13}/statezero/adaptors/django/actions.py

@@ -48,6 +48,13 @@ class DjangoActionSchemaGenerator:
                 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,
@@ -62,6 +69,7 @@ class DjangoActionSchemaGenerator:
                 "permissions": [
                     perm.__name__ for perm in action_config.get("permissions", [])
                 ],
+                "display": display_data,
             }
             actions_schema[action_name] = schema_info
 
@@ -212,4 +220,21 @@ class DjangoActionSchemaGenerator:
                 "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-0.1.0b11 → statezero-0.1.0b13}/statezero/adaptors/django/extensions/custom_field_serializers/money_field.py

@@ -15,6 +15,14 @@ class MoneyFieldSerializer(serializers.Field):
         self.decimal_places = kwargs.pop("decimal_places", 2)
         super().__init__(**kwargs)
 
+    @classmethod
+    def get_prefetch_db_fields(cls, field_name: str):
+        """
+        Return all database fields required for this field to serialize.
+        MoneyField creates two database columns: field_name and field_name_currency.
+        """
+        return [field_name, f"{field_name}_currency"]
+
     def to_representation(self, value):
         djmoney_field = MoneyField(
             max_digits=self.max_digits, decimal_places=self.decimal_places

{statezero-0.1.0b11 → statezero-0.1.0b13}/statezero/adaptors/django/query_optimizer.py

@@ -477,7 +477,34 @@ def optimize_query(queryset, fields=None, fields_map=None, depth=0, use_only=Tru
             related_fields_to_fetch = set()
 
             if fields_map and related_model_name in fields_map:
-                related_fields_to_fetch.update(fields_map[related_model_name])
+                # Process each field, checking for custom serializers
+                from statezero.adaptors.django.serializers import get_custom_serializer
+                related_meta = _get_model_meta(related_model)
+                for field_name in fields_map[related_model_name]:
+                    try:
+                        field_obj = related_meta.get_field(field_name)
+                        if not field_obj.is_relation:
+                            # Check if this field has a custom serializer with explicit DB field requirements
+                            custom_serializer = get_custom_serializer(field_obj.__class__)
+                            if custom_serializer and hasattr(custom_serializer, 'get_prefetch_db_fields'):
+                                # Use the explicit list from the custom serializer
+                                db_fields = custom_serializer.get_prefetch_db_fields(field_name)
+                                for db_field in db_fields:
+                                    related_fields_to_fetch.add(db_field)
+                                logger.debug(f"Using custom DB fields {db_fields} for field '{field_name}' in {related_model_name}")
+                            else:
+                                # No custom serializer, just add the field itself
+                                related_fields_to_fetch.add(field_name)
+                        else:
+                            # Relation field, add as-is
+                            related_fields_to_fetch.add(field_name)
+                    except FieldDoesNotExist:
+                        # Field doesn't exist, add it anyway (might be computed)
+                        related_fields_to_fetch.add(field_name)
+                    except Exception as e:
+                        logger.error(f"Error checking custom serializer for field '{field_name}' in {related_model_name}: {e}")
+                        # On error, add the field anyway to be safe
+                        related_fields_to_fetch.add(field_name)
             else:
                 # If no field restrictions are provided, get all fields
                 all_fields = [f.name for f in related_model._meta.get_fields() if f.concrete]
@@ -531,7 +558,18 @@ def optimize_query(queryset, fields=None, fields_map=None, depth=0, use_only=Tru
                     try:
                         field_obj = root_meta.get_field(field_name)
                         if not field_obj.is_relation:
-                           root_fields_to_fetch.add(field_name)
+                           # Check if this field has a custom serializer with explicit DB field requirements
+                           from statezero.adaptors.django.serializers import get_custom_serializer
+                           custom_serializer = get_custom_serializer(field_obj.__class__)
+                           if custom_serializer and hasattr(custom_serializer, 'get_prefetch_db_fields'):
+                               # Use the explicit list from the custom serializer
+                               db_fields = custom_serializer.get_prefetch_db_fields(field_name)
+                               for db_field in db_fields:
+                                   root_fields_to_fetch.add(db_field)
+                               logger.debug(f"Using custom DB fields {db_fields} for field '{field_name}'")
+                           else:
+                               # No custom serializer, just add the field itself
+                               root_fields_to_fetch.add(field_name)
                         elif isinstance(field_obj, (ForeignKey, OneToOneField)):
                              # If FK/O2O itself is requested directly, include its id field
                              root_fields_to_fetch.add(field_obj.attname)

{statezero-0.1.0b11 → statezero-0.1.0b13}/statezero/adaptors/django/schemas.py

@@ -127,6 +127,11 @@ class DjangoSchemaGenerator(AbstractSchemaGenerator):
         if hasattr(model._meta, "ordering") and model._meta.ordering:
             default_ordering = list(model._meta.ordering)
 
+        # Serialize display metadata if present
+        display_data = None
+        if model_config.display:
+            display_data = self._serialize_display_metadata(model_config.display)
+
         schema_meta = ModelSchemaMetadata(
             model_name=config.orm_provider.get_model_name(model),
             title=model._meta.verbose_name.title(),
@@ -153,6 +158,7 @@ class DjangoSchemaGenerator(AbstractSchemaGenerator):
             time_format=getattr(settings, "REST_FRAMEWORK", {}).get(
                 "TIME_FORMAT", "iso-8601"
             ),
+            display=display_data,
         )
         return schema_meta
 
@@ -322,3 +328,20 @@ class DjangoSchemaGenerator(AbstractSchemaGenerator):
         if isinstance(target_field, (models.UUIDField, models.CharField)):
             return FieldType.STRING
         return FieldType.INTEGER
+
+    @staticmethod
+    def _serialize_display_metadata(display) -> Dict[str, Any]:
+        """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-0.1.0b11 → statezero-0.1.0b13}/statezero/core/actions.py

@@ -20,8 +20,9 @@ class ActionRegistry:
             List[AbstractActionPermission], AbstractActionPermission, None
         ] = None,
         name: Optional[str] = None,
+        display: Optional[Any] = None,
     ):
-        """Register an action function with an optional, explicit docstring."""
+        """Register an action function with an optional, explicit docstring and display metadata."""
 
         def decorator(func: Callable):
             action_name = name or func.__name__
@@ -47,6 +48,7 @@ class ActionRegistry:
                 "name": action_name,
                 "module": func.__module__,
                 "docstring": final_docstring,  # Store the determined docstring
+                "display": display,  # Store display metadata
             }
             return func
 
@@ -76,8 +78,9 @@ def action(
         List[AbstractActionPermission], AbstractActionPermission, None
     ] = None,
     name: Optional[str] = None,
+    display: Optional[Any] = None,
 ):
-    """Framework-agnostic decorator to register an action."""
+    """Framework-agnostic decorator to register an action with optional display metadata."""
     return action_registry.register(
         func,
         docstring=docstring,
@@ -85,4 +88,5 @@ def action(
         response_serializer=response_serializer,
         permissions=permissions,
         name=name,
+        display=display,
     )

{statezero-0.1.0b11 → statezero-0.1.0b13}/statezero/core/classes.py

@@ -131,12 +131,15 @@ class ModelSchemaMetadata(BaseModel):
     default_ordering: Optional[List[str]] = None
     # Extra definitions (for schemas referenced via $ref) are merged in if provided.
     definitions: Dict[str, Any] = field(default_factory=dict)
-    
+
     # Date / time formatting templates
     datetime_format: Optional[str] = None
     date_format: Optional[str] = None
     time_format: Optional[str] = None
 
+    # Display customization
+    display: Optional[Dict[str, Any]] = None
+
 @dataclass
 class ModelSummaryRepresentation:
     pk: Any
@@ -165,3 +168,56 @@ class FieldNode:
     is_relation: bool
     related_model: Optional[str] = None  # The object name of the related model, if any
     type: str = "field"
+
+
+@dataclass
+class FieldDisplayConfig:
+    """
+    Configuration for customizing how a field is displayed in the frontend.
+
+    Attributes:
+        field_name: The name of the field this config applies to
+        display_component: Custom UI component name (e.g., "AddressAutocomplete", "DatePicker")
+        filter_queryset: Filter options for select/multi-select fields (dict passed to backend)
+        display_help_text: Additional help text for the field
+        extra: Additional custom metadata for framework-specific or UI-specific extensions
+    """
+    field_name: str
+    display_component: Optional[str] = None
+    filter_queryset: Optional[Dict[str, Any]] = None
+    display_help_text: Optional[str] = None
+    extra: Optional[Dict[str, Any]] = None
+
+
+@dataclass
+class FieldGroup:
+    """
+    Group related fields together for better UX.
+
+    Attributes:
+        display_title: Group heading
+        display_description: Group description
+        field_names: List of field names in this group
+    """
+    display_title: str
+    display_description: Optional[str] = None
+    field_names: Optional[List[str]] = None
+
+
+@dataclass
+class DisplayMetadata:
+    """
+    Rich display information for models and actions to customize frontend rendering.
+
+    Attributes:
+        display_title: Main heading/title override
+        display_description: Explanatory text about the model/action
+        field_groups: Logical grouping of fields (e.g., "Contact Info", "Address Details")
+        field_display_configs: Per-field customization (custom components, filters, help text)
+        extra: Additional custom metadata for framework-specific or UI-specific extensions
+    """
+    display_title: Optional[str] = None
+    display_description: Optional[str] = None
+    field_groups: Optional[List[FieldGroup]] = None
+    field_display_configs: Optional[List[FieldDisplayConfig]] = None
+    extra: Optional[Dict[str, Any]] = None

{statezero-0.1.0b11 → statezero-0.1.0b13}/statezero/core/config.py

@@ -162,6 +162,8 @@ class ModelConfig:
         Fields that can be used for ordering
     fields: Optional[Optional[Union[Set[str], Literal["__all__"]]]]
         Expose just a subset of the model fields
+    display: Optional[Any], optional
+        Display metadata for frontend customization (DisplayMetadata instance)
     DEBUG: bool, default=False
         Enable debug mode for this model
     """
@@ -179,6 +181,7 @@ class ModelConfig:
         searchable_fields: Optional[Union[Set[str], Literal["__all__"]]] = None,
         ordering_fields: Optional[Union[Set[str], Literal["__all__"]]] = None,
         fields: Optional[Union[Set[str], Literal["__all__"]]] = None,
+        display: Optional[Any] = None,
         DEBUG: bool = False,
     ):
         self.model = model
@@ -192,6 +195,7 @@ class ModelConfig:
         self.searchable_fields = searchable_fields or set()
         self.ordering_fields = ordering_fields or set()
         self.fields = fields or "__all__"
+        self.display = display
         self.DEBUG = DEBUG or False
 
     @property

{statezero-0.1.0b11 → statezero-0.1.0b13}/statezero.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: statezero
-Version: 0.1.0b11
+Version: 0.1.0b13
 Summary: Connect your Python backend to a modern JavaScript SPA frontend with 90% less complexity.
 Author-email: Robert <robert.herring@statezero.dev>
 Project-URL: homepage, https://www.statezero.dev