better variable/function names

Author: Archmonger

src/django_idom/hooks.py

@@ -14,7 +14,14 @@
 from idom.backend.types import Location
 from idom.core.hooks import Context, create_context, use_context, use_effect, use_state
 
-from django_idom.types import IdomWebsocket, Mutation, OrmFetch, Query, _Params, _Result
+from django_idom.types import (
+    IdomWebsocket,
+    Mutation,
+    QueryOptions,
+    Query,
+    _Params,
+    _Result,
+)
 from django_idom.utils import _generate_obj_name
 
 
@@ -68,7 +75,7 @@ def use_websocket() -> IdomWebsocket:
 
 
 def use_query(
-    query: Callable[_Params, _Result | None] | OrmFetch,
+    query: Callable[_Params, _Result | None] | QueryOptions,
     *args: _Params.args,
     **kwargs: _Params.kwargs,
 ) -> Query[_Result | None]:
@@ -88,7 +95,9 @@ def use_query(
     data, set_data = use_state(cast(Union[_Result, None], None))
     loading, set_loading = use_state(True)
     error, set_error = use_state(cast(Union[Exception, None], None))
-    fetch_cls = query if isinstance(query, OrmFetch) else OrmFetch(query)
+    query_options = (
+        query if isinstance(query, QueryOptions) else QueryOptions(func=query)
+    )
 
     @use_callback
     def refetch() -> None:
@@ -100,8 +109,8 @@ def refetch() -> None:
     def add_refetch_callback() -> Callable[[], None]:
         # By tracking callbacks globally, any usage of the query function will be re-run
         # if the user has told a mutation to refetch it.
-        _REFETCH_CALLBACKS[fetch_cls.func].add(refetch)
-        return lambda: _REFETCH_CALLBACKS[fetch_cls.func].remove(refetch)
+        _REFETCH_CALLBACKS[query_options.func].add(refetch)
+        return lambda: _REFETCH_CALLBACKS[query_options.func].remove(refetch)
 
     @use_effect(dependencies=None)
     @database_sync_to_async
@@ -111,15 +120,15 @@ def execute_query() -> None:
 
         try:
             # Run the initial query
-            fetch_cls.data = fetch_cls.func(*args, **kwargs)
+            query_options._data = query_options.func(*args, **kwargs)
 
-            # Use a custom evaluator, if provided
-            if fetch_cls.evaluator:
-                fetch_cls.evaluator(fetch_cls)
+            # Use a custom postprocessor, if provided
+            if query_options.postprocessor:
+                query_options.postprocessor(query_options)
 
-            # Evaluate lazy Django fields
+            # Use the default postprocessor
             else:
-                _evaluate_django_query(fetch_cls)
+                _postprocess_django_query(query_options)
         except Exception as e:
             set_data(None)
             set_loading(False)
@@ -131,7 +140,7 @@ def execute_query() -> None:
         finally:
             set_should_execute(False)
 
-        set_data(fetch_cls.data)
+        set_data(query_options._data)
         set_loading(False)
         set_error(None)
 
@@ -191,21 +200,21 @@ def reset() -> None:
     return Mutation(call, loading, error, reset)
 
 
-def _evaluate_django_query(fetch_cls: OrmFetch) -> None:
+def _postprocess_django_query(fetch_cls: QueryOptions) -> None:
     """Recursively fetch all fields within a `Model` or `QuerySet` to ensure they are not performed lazily.
 
     Some behaviors can be modified through `OrmFetch` attributes."""
-    data = fetch_cls.data
+    data = fetch_cls._data
 
     # `QuerySet`, which is effectively a list of `Model` instances
     # https://github.com/typeddjango/django-stubs/issues/704
     if isinstance(data, QuerySet):  # type: ignore[misc]
         for model in data:
-            _evaluate_django_query(
-                OrmFetch(
+            _postprocess_django_query(
+                QueryOptions(
                     func=fetch_cls.func,
-                    data=model,
-                    options=fetch_cls.options,
+                    _data=model,
+                    postprocessor_options=fetch_cls.postprocessor_options,
                 )
             )
 
@@ -219,20 +228,20 @@ def _evaluate_django_query(fetch_cls: OrmFetch) -> None:
                 getattr(data, field.name)
 
             if (
-                fetch_cls.options.get("many_to_one", None)
+                fetch_cls.postprocessor_options.get("many_to_one", None)
                 and type(field) == ManyToOneRel
             ):
                 prefetch_fields.append(f"{field.name}_set")
 
-            elif fetch_cls.options.get("many_to_many", None) and isinstance(
-                field, ManyToManyField
-            ):
+            elif fetch_cls.postprocessor_options.get(
+                "many_to_many", None
+            ) and isinstance(field, ManyToManyField):
                 prefetch_fields.append(field.name)
-                _evaluate_django_query(
-                    OrmFetch(
+                _postprocess_django_query(
+                    QueryOptions(
                         func=fetch_cls.func,
-                        data=getattr(data, field.name).get_queryset(),
-                        options=fetch_cls.options,
+                        _data=getattr(data, field.name).get_queryset(),
+                        postprocessor_options=fetch_cls.postprocessor_options,
                     )
                 )
 

src/django_idom/types.py

@@ -53,21 +53,22 @@ class ViewComponentIframe:
     kwargs: dict
 
 
-@dataclass
-class OrmFetch:
-    """A Django ORM fetch."""
+@dataclass(kw_only=True)
+class QueryOptions:
+    """A Django ORM query function, alongside some configuration values."""
 
     func: Callable
-    """Callable that fetches ORM objects."""
+    """Callable that fetches ORM object(s)."""
 
-    data: Any | None = None
-    """The results of a fetch operation."""
+    _data: Any = None
+    """The results of a fetch operation.
+    This is only intended to be set automatically by the `use_query` hook."""
 
-    options: dict[str, Any] = field(
+    postprocessor_options: dict[str, Any] = field(
         default_factory=lambda: {"many_to_many": True, "many_to_one": True}
     )
-    """Configuration values usable by the `fetch_handler`."""
+    """Configuration values usable by the `postprocessor`."""
 
-    evaluator: Callable[[OrmFetch], None] | None = None
-    """A post-processing callable that can read/modify the `OrmFetch` object. If unset, the default fetch
+    postprocessor: Callable[[QueryOptions], None] | None = None
+    """A post processing callable that can read/modify the `OrmFetch` object. If unset, the default fetch
     handler is used to prevent lazy loading of Django fields."""

src/django_idom/utils.py

@@ -16,7 +16,7 @@
 from django.views import View
 
 from django_idom.config import IDOM_REGISTERED_COMPONENTS
-from django_idom.types import OrmFetch, _Params, _Result
+from django_idom.types import QueryOptions, _Params, _Result
 
 
 _logger = logging.getLogger(__name__)
@@ -203,35 +203,35 @@ def _generate_obj_name(object: Any) -> str | None:
 
 
 @overload
-def fetch_options(
+def query_options(
     query_func: None = ...,
-    evaluator: Callable[[OrmFetch], None] | None = None,
+    evaluator: Callable[[QueryOptions], None] | None = None,
     **options,
-) -> Callable[[Callable[_Params, _Result]], OrmFetch]:
+) -> Callable[[Callable[_Params, _Result]], QueryOptions]:
     ...
 
 
 @overload
-def fetch_options(
+def query_options(
     query_func: Callable[_Params, _Result],
-    evaluator: Callable[[OrmFetch], None] | None = None,
+    evaluator: Callable[[QueryOptions], None] | None = None,
     **options,
-) -> OrmFetch:
+) -> QueryOptions:
     ...
 
 
-def fetch_options(
+def query_options(
     query_func: Callable[_Params, _Result] | None = None,
-    evaluator: Callable[[OrmFetch], None] | None = None,
+    evaluator: Callable[[QueryOptions], None] | None = None,
     **options,
-) -> OrmFetch | Callable[[Callable[_Params, _Result]], OrmFetch]:
+) -> QueryOptions | Callable[[Callable[_Params, _Result]], QueryOptions]:
     def decorator(query_func: Callable[_Params, _Result]):
         if not query_func:
-            raise ValueError("A query function must be provided to `fetch_options`")
+            raise ValueError("A query function must be provided to `query_options`")
 
-        fetch_options = OrmFetch(func=query_func, evaluator=evaluator)
+        query_options = QueryOptions(func=query_func, postprocessor=evaluator)
         if options:
-            fetch_options.options.update(options)
-        return fetch_options
+            query_options.postprocessor_options.update(options)
+        return query_options
 
     return decorator(query_func) if query_func else decorator

tests/test_app/components.py

@@ -8,7 +8,7 @@
 import django_idom
 from django_idom.components import view_to_component
 from django_idom.hooks import use_mutation, use_query
-from django_idom.utils import fetch_options
+from django_idom.utils import query_options
 
 from . import views
 
@@ -207,7 +207,7 @@ def relational_query():
     )
 
 
-@fetch_options(many_to_many=False, many_to_one=False)
+@query_options(many_to_many=False, many_to_one=False)
 def get_relational_parent_query_fail():
     return RelationalParent.objects.first() or create_relational_parent()