statezero 0.1.0b3__py3-none-any.whl → 0.1.0b5__py3-none-any.whl

statezero/core/hook_checks.py

@@ -0,0 +1,86 @@
+import warnings
+from django.conf import settings
+from typing import Any, Dict, Set, Type
+
+def _check_pre_hook_result(
+    original_data: Dict, result_data: Any, model: Type, serializer_fields: Set[str]
+):
+    """Check pre-hook result and warn about common issues in DEBUG mode only."""
+    if not getattr(settings, "DEBUG", False):
+        return result_data or original_data
+
+    model_name = model.__name__
+
+    # Warning 1: Hook returned None
+    if result_data is None:
+        warnings.warn(
+            f"Pre-hook for {model_name} returned None (should return dict). HINT: If you want to skip changes, return the original data.",
+            stacklevel=5,
+        )
+        return original_data
+
+    if not isinstance(result_data, dict):
+        warnings.warn(
+            f"Pre-hook for {model_name} returned {type(result_data).__name__} (should return dict). HINT: If you want to skip changes, return the original data.",
+            stacklevel=5,
+        )
+        return original_data
+
+    # Warning 2: Added fields not in serializer
+    added_keys = set(result_data.keys()) - set(original_data.keys())
+    missing_fields = added_keys - serializer_fields
+    if missing_fields:
+        warnings.warn(
+            f"Pre-hook for {model_name} added unavailable fields {missing_fields}. HINT: Add the field to permission.editable_fields() or use post-hook.",
+            stacklevel=5,
+        )
+
+    # Warning 3: Removed fields that were in original data
+    removed_keys = set(original_data.keys()) - set(result_data.keys())
+    if removed_keys:
+        warnings.warn(
+            f"Pre-hook for {model_name} removed fields {removed_keys} that were in original data. This might be intentional, or it could be caused by a hook not returning the full input data.",
+            stacklevel=5,
+        )
+
+    return result_data
+
+def _check_post_hook_result(original_data: Dict, result_data: Any, model: Type):
+    """Check post-hook result and warn about common issues in DEBUG mode only."""
+    if not getattr(settings, "DEBUG", False):
+        return result_data or original_data
+
+    model_name = model.__name__
+
+    # Warning 1: Hook returned None
+    if result_data is None:
+        warnings.warn(
+            f"Post-hook for {model_name} returned None (should return dict). HINT: Return the validated_data dict.",
+            stacklevel=5,
+        )
+        return original_data
+
+    if not isinstance(result_data, dict):
+        warnings.warn(
+            f"Post-hook for {model_name} returned {type(result_data).__name__} (should return dict). HINT: Return the validated_data dict.",
+            stacklevel=5,
+        )
+        return original_data
+
+    # Warning 2: Removed validated fields (more serious than pre-hook)
+    removed_keys = set(original_data.keys()) - set(result_data.keys())
+    if removed_keys:
+        warnings.warn(
+            f"Post-hook for {model_name} removed validated fields {removed_keys}. These fields won't be saved.",
+            stacklevel=5,
+        )
+
+    # Warning 3: Added fields that weren't validated
+    added_keys = set(result_data.keys()) - set(original_data.keys())
+    if added_keys:
+        warnings.warn(
+            f"Post-hook for {model_name} added unvalidated fields {added_keys}. These bypassed serializer validation.",
+            stacklevel=5,
+        )
+
+    return result_data

statezero/core/interfaces.py

@@ -1,104 +1,126 @@
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
-from typing import Any, Callable, Dict, List, Optional, Set, Tuple, Type, Union, Literal, Protocol
+from typing import (
+    Any,
+    Callable,
+    Dict,
+    List,
+    Optional,
+    Set,
+    Tuple,
+    Type,
+    Union,
+    Literal,
+    Protocol,
+)
 
 from statezero.core.classes import ModelSchemaMetadata, SchemaFieldMetadata
-from statezero.core.types import (ActionType, ORMField, ORMModel, ORMQuerySet, RequestType)
+from statezero.core.types import (
+    ActionType,
+    ORMField,
+    ORMModel,
+    ORMQuerySet,
+    RequestType,
+)
+
 
 class AbstractORMProvider(ABC):
     """
     A merged ORM engine interface that combines both query building (filtering,
     ordering, aggregation, etc.) and ORM provider responsibilities (queryset assembly,
     event signal registration, model graph construction, etc.).
+
+    UPDATED: All query manipulation methods now take queryset parameters and return
+    new querysets instead of mutating internal state.
     """
 
-    # === Query Engine Methods ===
+    # === Query Engine Methods (UPDATED: Now stateless) ===
 
     @abstractmethod
-    def get_fields(self) -> Set[str]:
+    def get_fields(self, model: ORMModel) -> Set[str]:
         """
         Get all of the model fields - doesn't apply permissions check.
         """
         pass
 
     @abstractmethod
-    def filter_node(self, node: Dict[str, Any]) -> None:
+    def filter_node(self, queryset: ORMQuerySet, node: Dict[str, Any]) -> ORMQuerySet:
         """
-        Apply filter/and/or/not logic to the current query.
+        Apply filter/and/or/not logic to the queryset and return new queryset.
         """
         pass
 
     @abstractmethod
-    def search_node(self, search_query: str, search_fields: Set[str]) -> None:
+    def search_node(
+        self, queryset: ORMQuerySet, search_query: str, search_fields: Set[str]
+    ) -> ORMQuerySet:
         """
-        Apply search to the current query.
+        Apply search to the queryset and return new queryset.
         """
         pass
 
     @abstractmethod
-    def create(self, data: Dict[str, Any]) -> Any:
-        """Create a new record."""
-        pass
-
-    @abstractmethod
-    def update(self, node: Dict[str, Any]) -> int:
+    def exclude_node(self, queryset: ORMQuerySet, node: Dict[str, Any]) -> ORMQuerySet:
         """
-        Update records (by filter or primary key).
-        Returns the number of rows updated.
+        Apply exclude logic to the queryset and return new queryset.
         """
         pass
 
     @abstractmethod
-    def delete(self, node: Dict[str, Any]) -> int:
+    def order_by(self, queryset: ORMQuerySet, order_list: List[str]) -> ORMQuerySet:
         """
-        Delete records (by filter or primary key).
-        Returns the number of rows deleted.
+        Order the queryset based on a list of fields and return new queryset.
         """
         pass
 
     @abstractmethod
-    def get(self, node: Dict[str, Any]) -> Any:
+    def select_related(
+        self, queryset: ORMQuerySet, related_fields: List[str]
+    ) -> ORMQuerySet:
         """
-        Retrieve a single record. Raises an error if multiple or none are found.
+        Optimize the queryset by eager loading the given related fields and return new queryset.
         """
         pass
 
     @abstractmethod
-    def get_or_create(self, node: Dict[str, Any]) -> Tuple[Any, bool]:
+    def prefetch_related(
+        self, queryset: ORMQuerySet, related_fields: List[str]
+    ) -> ORMQuerySet:
         """
-        Retrieve a record if it exists, otherwise create it.
-        Returns a tuple of (instance, created_flag).
+        Optimize the queryset by prefetching the given related fields and return new queryset.
         """
         pass
 
     @abstractmethod
-    def update_or_create(self, node: Dict[str, Any]) -> Tuple[Any, bool]:
+    def select_fields(self, queryset: ORMQuerySet, fields: List[str]) -> ORMQuerySet:
         """
-        Update a record if it exists or create it if it doesn't.
-        Returns a tuple of (instance, created_flag).
+        Select only specific fields from the queryset and return new queryset.
         """
         pass
 
     @abstractmethod
-    def first(self) -> Any:
-        """Return the first record from the current query."""
-        pass
-
-    @abstractmethod
-    def last(self) -> Any:
-        """Return the last record from the current query."""
+    def fetch_list(
+        self,
+        queryset: ORMQuerySet,
+        offset: Optional[int] = None,
+        limit: Optional[int] = None,
+        req: Optional[RequestType] = None,
+        permissions: Optional[List[Type]] = None,
+    ) -> ORMQuerySet:
+        """
+        Return a sliced queryset based on pagination with permission checks.
+        """
         pass
 
-    @abstractmethod
-    def exists(self) -> bool:
-        """Return True if the current query has any results; otherwise False."""
-        pass
+    # === Aggregate Methods (UPDATED: Take queryset parameter) ===
 
     @abstractmethod
-    def aggregate(self, agg_list: List[Dict[str, Any]]) -> Dict[str, Any]:
+    def aggregate(
+        self, queryset: ORMQuerySet, agg_list: List[Dict[str, Any]]
+    ) -> Dict[str, Any]:
         """
-        Aggregate the current query based on the provided functions.
+        Aggregate the queryset based on the provided functions.
         Example:
           [
             {'function': 'count', 'field': 'id', 'alias': 'id_count'},
@@ -108,60 +130,155 @@ class AbstractORMProvider(ABC):
         pass
 
     @abstractmethod
-    def count(self, field: str) -> int:
+    def count(self, queryset: ORMQuerySet, field: str) -> int:
         """Count the number of records for the given field."""
         pass
 
     @abstractmethod
-    def sum(self, field: str) -> Any:
+    def sum(self, queryset: ORMQuerySet, field: str) -> Any:
         """Sum the values of the given field."""
         pass
 
     @abstractmethod
-    def avg(self, field: str) -> Any:
+    def avg(self, queryset: ORMQuerySet, field: str) -> Any:
         """Calculate the average of the given field."""
         pass
 
     @abstractmethod
-    def min(self, field: str) -> Any:
+    def min(self, queryset: ORMQuerySet, field: str) -> Any:
         """Find the minimum value for the given field."""
         pass
 
     @abstractmethod
-    def max(self, field: str) -> Any:
+    def max(self, queryset: ORMQuerySet, field: str) -> Any:
         """Find the maximum value for the given field."""
         pass
 
     @abstractmethod
-    def order_by(self, order_list: List[Dict[str, str]]) -> None:
+    def first(self, queryset: ORMQuerySet) -> Any:
+        """Return the first record from the queryset."""
+        pass
+
+    @abstractmethod
+    def last(self, queryset: ORMQuerySet) -> Any:
+        """Return the last record from the queryset."""
+        pass
+
+    @abstractmethod
+    def exists(self, queryset: ORMQuerySet) -> bool:
+        """Return True if the queryset has any results; otherwise False."""
+        pass
+
+    # === CRUD Methods (UPDATED: Take model or queryset parameters explicitly) ===
+
+    @abstractmethod
+    def create(
+        self, model: Type[ORMModel], data: Dict[str, Any], *args, **kwargs
+    ) -> Any:
+        """Create a new record using the model class."""
+        pass
+
+    @abstractmethod
+    def update(
+        self,
+        queryset: ORMQuerySet,
+        node: Dict[str, Any],
+        req: RequestType,
+        permissions: List[Type],
+        readable_fields: Optional[Set[str]] = None,
+    ) -> Tuple[int, List[Any]]:
         """
-        Order the query based on a list of fields.
-        Each dict should contain 'field' and optionally 'direction' ('asc' or 'desc').
+        Update records in the queryset.
+        Returns tuple of (number of rows updated, updated instances).
         """
         pass
 
     @abstractmethod
-    def select_related(self, related_fields: List[str]) -> None:
+    def delete(
+        self,
+        queryset: ORMQuerySet,
+        node: Dict[str, Any],
+        req: RequestType,
+        permissions: List[Type],
+    ) -> Tuple[int, Any]:
         """
-        Optimize the query by eager loading the given related fields.
+        Delete records in the queryset.
+        Returns tuple of (number of rows deleted, deleted instance data).
         """
         pass
 
     @abstractmethod
-    def prefetch_related(self, related_fields: List[str]) -> None:
+    def get(
+        self,
+        queryset: ORMQuerySet,
+        node: Dict[str, Any],
+        req: RequestType,
+        permissions: List[Type],
+    ) -> Any:
         """
-        Optimize the query by prefetching the given related fields.
+        Retrieve a single record from the queryset.
+        Raises an error if multiple or none are found.
         """
         pass
 
     @abstractmethod
-    def fetch_list(self, offset: int, limit: int) -> List[Any]:
+    def get_or_create(
+        self,
+        queryset: ORMQuerySet,
+        node: Dict[str, Any],
+        serializer: Any,
+        req: RequestType,
+        permissions: List[Type],
+        create_fields_map: Dict[str, Set[str]],
+    ) -> Tuple[Any, bool]:
         """
-        Return a list of records (as dicts or objects) based on pagination.
+        Retrieve a record if it exists, otherwise create it.
+        Returns a tuple of (instance, created_flag).
         """
         pass
 
-    # === ORM Provider Methods ===
+    @abstractmethod
+    def update_or_create(
+        self,
+        queryset: ORMQuerySet,
+        node: Dict[str, Any],
+        req: RequestType,
+        serializer: Any,
+        permissions: List[Type],
+        update_fields_map: Dict[str, Set[str]],
+        create_fields_map: Dict[str, Set[str]],
+    ) -> Tuple[Any, bool]:
+        """
+        Update a record if it exists or create it if it doesn't.
+        Returns a tuple of (instance, created_flag).
+        """
+        pass
+
+    @abstractmethod
+    def update_instance(
+        self,
+        model: Type[ORMModel],
+        ast: Dict[str, Any],
+        req: RequestType,
+        permissions: List[Type],
+        serializer: Any,
+        fields_map: Dict[str, Set[str]],
+    ) -> Any:
+        """Update a single model instance by filter."""
+        pass
+
+    @abstractmethod
+    def delete_instance(
+        self,
+        model: Type[ORMModel],
+        ast: Dict[str, Any],
+        req: RequestType,
+        permissions: List[Type],
+    ) -> int:
+        """Delete a single model instance by filter."""
+        pass
+
+    # === ORM Provider Methods (Unchanged - these are utility methods) ===
 
     @abstractmethod
     def get_queryset(
@@ -205,29 +322,32 @@ class AbstractORMProvider(ABC):
         pass
 
     @abstractmethod
-    def get_user(self, request: RequestType): # returns User
+    def get_user(self, request: RequestType):  # returns User
         """
         Get the request user.
         """
         pass
 
     @abstractmethod
-    def build_model_graph(self, model: ORMModel) -> None:  # type:ignore
+    def build_model_graph(self, model: ORMModel) -> Any:  # type:ignore
         """
         Construct a graph representation of model relationships.
         """
         pass
 
 
+# === Other Abstract Classes (Unchanged) ===
+
+
 class AbstractCustomQueryset(ABC):
     @abstractmethod
     def get_queryset(self, request: Optional[RequestType] = None) -> Any:
         """
         Return a custom queryset (e.g. a custom SQLAlchemy Query or Django QuerySet).
-        
+
         Args:
             request: The current request object, which may contain user information
-        
+
         Returns:
             A custom queryset
         """
@@ -302,7 +422,7 @@ class AbstractEventEmitter(ABC):
     ) -> None:
         """
         Emit an event to the specified namespace with the given event type and data.
-        
+
         Parameters:
         -----------
         namespace: str
@@ -406,24 +526,31 @@ class AbstractPermission(ABC):
         """
         pass
 
+
 class AbstractSearchProvider(ABC):
     """Base class for search providers in StateZero."""
-    
+
     @abstractmethod
-    def search(self, queryset: ORMQuerySet, query: str, search_fields: Union[Set[str], Literal["__all__"]]) -> ORMQuerySet:
+    def search(
+        self,
+        queryset: ORMQuerySet,
+        query: str,
+        search_fields: Union[Set[str], Literal["__all__"]],
+    ) -> ORMQuerySet:
         """
         Apply search filtering to a queryset.
-        
+
         Args:
             queryset: Django queryset
             query: The search query string
             search_fields: Set of field names to search in
-            
+
         Returns:
             Filtered queryset with search applied
         """
         pass
 
+
 class AbstractQueryOptimizer(ABC):
     """
     Abstract Base Class for query optimizers.
@@ -436,7 +563,7 @@ class AbstractQueryOptimizer(ABC):
         self,
         depth: Optional[int] = None,
         fields_per_model: Optional[Dict[str, Set[str]]] = None,
-        get_model_name_func: Optional[Callable[[Type[ORMModel]], str]] = None
+        get_model_name_func: Optional[Callable[[Type[ORMModel]], str]] = None,
     ):
         """
         Initializes the optimizer with common configuration potentially
@@ -462,10 +589,7 @@ class AbstractQueryOptimizer(ABC):
 
     @abstractmethod
     def optimize(
-        self,
-        queryset: Any,
-        fields: Optional[List[str]] = None,
-        **kwargs: Any
+        self, queryset: Any, fields: Optional[List[str]] = None, **kwargs: Any
     ) -> Any:
         """
         Optimizes the given query object.

statezero/core/process_request.py

@@ -170,13 +170,13 @@ class RequestProcessor:
                 )
 
         # Create and use the AST parser directly, instead of delegating to ORM provider
-        self.orm_provider.set_queryset(base_queryset)
         parser = ASTParser(
             engine=self.orm_provider,
             serializer=self.data_serializer,
             model=model,
             config=self.config,
             registry=self.registry,
+            base_queryset=base_queryset,  # Pass the queryset here
             serializer_options=serializer_options or {},
             request=req,
         )

{statezero-0.1.0b3.dist-info → statezero-0.1.0b5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: statezero
-Version: 0.1.0b3
+Version: 0.1.0b5
 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.0b3.dist-info → statezero-0.1.0b5.dist-info}/RECORD

@@ -9,11 +9,11 @@ statezero/adaptors/django/exception_handler.py,sha256=cQF1Fm5IjH91ydB54TK9sqXiAO
 statezero/adaptors/django/f_handler.py,sha256=yvITFj9UAnz8-r-aLEcWoz48tBhZ08-VMq9Fsm2uiN8,12305
 statezero/adaptors/django/helpers.py,sha256=0Dyq5vboDuTUaH-KpS3oVDjastA9yv6xI6XpBuvRM3I,5974
 statezero/adaptors/django/middleware.py,sha256=YVr8fkqCk51xJQM-ovtrUiB9Kt9H81cLd9xv4cM9YlM,410
-statezero/adaptors/django/orm.py,sha256=G_dhMzX5iaaTSxO4bxSZvxMiBw7mLMWY2GUD0mlkMNg,36304
+statezero/adaptors/django/orm.py,sha256=-9tWH9hW2Ta5AipXysoWy-em7R-ybHKmPLtBX89nYQc,37118
 statezero/adaptors/django/permissions.py,sha256=fU2c4bKK0zX2uuVB0UazZHTI-5OkiI5-BtPNcPEWmW0,9525
 statezero/adaptors/django/query_optimizer.py,sha256=-GNqL7Xn8WP8OsLEAAxXpIszSyEwm-l6WjgdkEFzxUM,38541
 statezero/adaptors/django/schemas.py,sha256=shq8ed9qHCnbCfYVsRxVE7V3R3GhGIKeRRj7dI3r1IU,12728
-statezero/adaptors/django/serializers.py,sha256=fOKuAlui076yNqQzBqYXLqz5uYwi_KAIHXHwRnomiL0,22586
+statezero/adaptors/django/serializers.py,sha256=YFFDu6bzoWkSEOVH5Wmc4yJ8SaOkUA6HbXXYt6djlfc,23296
 statezero/adaptors/django/urls.py,sha256=G4LAUVG1WtPCyB_POQ3wa_VKqKCSI6p3fHZGy6GV99g,636
 statezero/adaptors/django/views.py,sha256=ZoTocBkqv8sdxaq5bMOZpsj1zko5FDcSYP1C9m8s9Hw,13723
 statezero/adaptors/django/extensions/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -27,7 +27,7 @@ statezero/adaptors/django/search_providers/__init__.py,sha256=47DEQpj8HBSa-_TImW
 statezero/adaptors/django/search_providers/basic_search.py,sha256=5_GJ1r_B6JdIYXL6yYEYn5mik88EolSH5aZvygc_UF0,977
 statezero/adaptors/django/search_providers/postgres_search.py,sha256=IMoHxzfi-Y3hAxPND4Xc6GatrPs1eXAqpmcfwt5Zr14,2459
 statezero/core/__init__.py,sha256=Z6RTutAAElLMEjBFphVVmpySPdJBA55j-Uo0BtR7c5E,1040
-statezero/core/ast_parser.py,sha256=epJ2pBpzRlKnrSgDMdVNOTRX6NX28khwkf_xOoPH_Uw,35561
+statezero/core/ast_parser.py,sha256=ezEHqVB1Afqw_GSyUs4Dh0W94xFM4aaNEaxyYMk-rr4,38756
 statezero/core/ast_validator.py,sha256=YZAflPyba0kXWBNhd1Z_XeEk-_zUzM6MkY9zSlX1PMs,11582
 statezero/core/classes.py,sha256=-rJ8szqGGzsFxE3TvbtYHFHFP9Kg2WP24aYi74Io338,4923
 statezero/core/config.py,sha256=oOjcudQO0XgEZ60kwkzpcOoTi0QZARS8XWbp9gzgasg,11489
@@ -35,11 +35,12 @@ statezero/core/context_storage.py,sha256=DVx525ZMRorj41kg5K0N6pPdGkQ5_XEJcBucpH5
 statezero/core/event_bus.py,sha256=2IFLBHSkLzpm1AX0MfSXSmF2X-lXK-gOoODZCtB2Jdw,6284
 statezero/core/event_emitters.py,sha256=qjMbeUmdn4bG7WiVfqTmNdaflEea5amnTEpOn5X0J44,2046
 statezero/core/exceptions.py,sha256=_krMHWW9qBbMXvvqFdWf85a3Kayn7XbJczfC3x3gmBI,3330
-statezero/core/interfaces.py,sha256=HwcFXWJfIAxqYgWbGesn1Th9O8mvqH2r0XP2UyYifEw,15866
-statezero/core/process_request.py,sha256=NiG36XEjPMemJI03l5eTNaymyfUbwVgrx78chVcs4Nk,8047
+statezero/core/hook_checks.py,sha256=uqtvwRx1qGsF7Vc49elAWdOjMzhuv3RADKY1wiLvhK4,3425
+statezero/core/interfaces.py,sha256=VCekst5esL9Yh739tW8PSedRS_s50qhEzlnJ8pwaxtU,19064
+statezero/core/process_request.py,sha256=dwIeBEVOE8zA-oE1h65XNOGiVqFbbXA7SzTAguLNgZk,8060
 statezero/core/types.py,sha256=K9x9AU5J6yd2AWvqRz27CeAY6UYfuQoQ7xTEwTijrmM,1982
-statezero-0.1.0b3.dist-info/licenses/license.md,sha256=0uKjybTt9K_YbEmYgf25JN292qjjJ-BPofvIZ3wdtX4,7411
-statezero-0.1.0b3.dist-info/METADATA,sha256=Zccgg4EbNtLlc0X_X0GHmvG7hLMQ4C_lXhPwApMK-aw,7152
-statezero-0.1.0b3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-statezero-0.1.0b3.dist-info/top_level.txt,sha256=UAuZYPKczradU1kcMQxsGjUzEW0qdgsqzhXyscrcLpw,10
-statezero-0.1.0b3.dist-info/RECORD,,
+statezero-0.1.0b5.dist-info/licenses/license.md,sha256=0uKjybTt9K_YbEmYgf25JN292qjjJ-BPofvIZ3wdtX4,7411
+statezero-0.1.0b5.dist-info/METADATA,sha256=cHmsrjlDYnl5F-H5HSHcgqpP13UMLfZr9M8gqoC7UZc,7152
+statezero-0.1.0b5.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+statezero-0.1.0b5.dist-info/top_level.txt,sha256=UAuZYPKczradU1kcMQxsGjUzEW0qdgsqzhXyscrcLpw,10
+statezero-0.1.0b5.dist-info/RECORD,,