Rename prefetch.Required to hints.Virtual

Author: fjsj

django_virtual_models/__init__.py

@@ -9,4 +9,5 @@
 # Top-level imports:
 from .fields import *
 from .generic_views import *
+from .prefetch import hints
 from .serializers import *

django_virtual_models/prefetch/__init__.py

@@ -1 +0,0 @@
-from .hints import *  # noqa

django_virtual_models/prefetch/hints.py

@@ -36,10 +36,10 @@ def wrapper(*args, **kwargs):
             raise MissingHintsException(
                 f"Unexpected query happened inside `{decorated_func.__qualname__}`.\n"
                 f"*Possible* line: {s.filename}:{s.lineno}\n"
-                "Please check if all `prefetch.hints` are correct, "
+                "Please check if all `hints` are correct, "
                 "and update them and the virtual model as needed.\n"
                 "Also, if this field is deferred on virtual model, "
-                "it needs to be hinted with `prefech.Required`\n"
+                "it needs to be hinted with `hints.Virtual`\n"
                 "See more details about the query on the other exception above (in console)."
             ) from exc
 
@@ -124,7 +124,7 @@ class defined_on_virtual_model(OnOffDecorator):  # noqa: N801
 
 
 @dataclass
-class Required:
+class Virtual:
     fields: List[str]
 
     def __init__(self, *args):

django_virtual_models/prefetch/serializer_optimization.py

@@ -8,7 +8,7 @@
 
 import typing_extensions
 
-from django_virtual_models import prefetch
+from django_virtual_models.prefetch import hints
 
 from .. import utils
 from ..fields import BaseVirtualField, NestedJoin, NoOp
@@ -29,7 +29,7 @@ def _validate_type_hint(type_hint, invalid_type_hint_message):
         raise ImproperlyAnnotatedCodeException(invalid_type_hint_message)
 
     metadata = typing_extensions.get_args(type_hint)[1:]
-    metadata_only = [datum for datum in metadata if isinstance(datum, prefetch.Required)]
+    metadata_only = [datum for datum in metadata if isinstance(datum, hints.Virtual)]
     if len(metadata_only) == 0:
         raise ImproperlyAnnotatedCodeException(invalid_type_hint_message)
     if len(metadata_only) > 1:
@@ -44,8 +44,8 @@ def _extract_type_hint_from_function(field, function):
     if len(type_hints_dict) == 0:
         raise ImproperlyAnnotatedCodeException(
             f"`{friendly_name}` inside `{field.parent.__class__.__name__}` "
-            "must have a `prefetch.hints` decorator or "
-            "a single `Annotated` type hint with a single `prefetch.Required` inside it."
+            "must have a `hints` decorator or "
+            "a single `Annotated` type hint with a single `hints.Virtual` inside it."
         )
     if len(type_hints_dict) > 1:
         raise ImproperlyAnnotatedCodeException(
@@ -58,14 +58,14 @@ def _extract_type_hint_from_function(field, function):
     # Check if Annotated is correct
     invalid_type_hint_message = (
         f"`{friendly_name}` inside `{field.parent.__class__.__name__}` "
-        "must have a single `Annotated` type hint with a single `prefetch.Required` inside it."
+        "must have a single `Annotated` type hint with a single `hints.Virtual` inside it."
     )
     _validate_type_hint(type_hint, invalid_type_hint_message=invalid_type_hint_message)
     return type_hint
 
 
 def _extract_type_hint_from_types_of_other_function(
-    field: Field, decorator_instance: prefetch.hints.from_types_of
+    field: Field, decorator_instance: hints.from_types_of
 ):
     friendly_name = utils.get_friendly_field_name(field)
     typed_func = decorator_instance.typed_func
@@ -93,17 +93,15 @@ def _extract_type_hint_from_types_of_other_function(
         f"referenced by decorator `{decorator_instance.__class__.__name__}` "
         f"on `{friendly_name}` inside `{field.parent.__class__.__name__}` "
         f"must have a `Annotated` type hint on param `{decorator_instance.obj_param_name}` "
-        "with a single `prefetch.Required` inside it."
+        "with a single `hints.Virtual` inside it."
     )
     _validate_type_hint(type_hint, invalid_type_hint_message=invalid_type_hint_message)
     return type_hint
 
 
 def _extract_lookups_from_type_hint_obj(type_hint) -> List[str]:
     metadata = typing_extensions.get_args(type_hint)[1:]
-    only = next(
-        datum for datum in metadata if isinstance(datum, prefetch.Required)
-    )  # pragma: no cover
+    only = next(datum for datum in metadata if isinstance(datum, hints.Virtual))  # pragma: no cover
     return only.fields
 
 
@@ -146,10 +144,10 @@ def _extract_lookups_from_function_type_hint(
     if decorator_instance is None:
         type_hint = _extract_type_hint_from_function(field, function)
         return _extract_lookups_from_type_hint_obj(type_hint)
-    elif isinstance(decorator_instance, prefetch.hints.from_types_of):
+    elif isinstance(decorator_instance, hints.from_types_of):
         type_hint = _extract_type_hint_from_types_of_other_function(field, decorator_instance)
         return _extract_lookups_from_type_hint_obj(type_hint)
-    elif isinstance(decorator_instance, prefetch.hints.from_serializer):
+    elif isinstance(decorator_instance, hints.from_serializer):
         serializer_instance = decorator_instance.serializer_cls(
             **(decorator_instance.serializer_kwargs or {})
         )
@@ -160,10 +158,10 @@ def _extract_lookups_from_function_type_hint(
             serializer_instance=serializer_instance,
             block_queries=block_queries,
         )
-    elif isinstance(decorator_instance, prefetch.hints.defined_on_virtual_model):
+    elif isinstance(decorator_instance, hints.defined_on_virtual_model):
         # `field.field_name` must be defined in virtual model
         return [field.field_name]
-    elif isinstance(decorator_instance, prefetch.hints.no_deferred_fields):
+    elif isinstance(decorator_instance, hints.no_deferred_fields):
         # `field.field_name` uses only fields that are always
         # fetched by the virtual model (which are all concrete fields minus the deferred ones)
         # so we don't need to return anything here to be included as a lookup
@@ -440,7 +438,7 @@ def recursively_find_lookup_list(
                     f"Debug info `{k}` from `{self.serializer_instance.__class__.__name__}`"
                 )  # pragma: no cover
 
-        # activate the `prefetch.hints` decorators to block unexpected queries
+        # activate the `hints` decorators to block unexpected queries
         if self.block_queries:
             self._activate_query_blocking(
                 readable_serializer_fields=readable_serializer_fields,

docs/tutorial.md

@@ -435,54 +435,54 @@ class PersonSerializer(v.VirtualModelSerializer):
 
 This serializer needs the `awards` field from `VirtualPerson` inside `get_has_won_any_award` method, otherwise it would raise an `AttributeError` as this is a *virtual field*. But how to specify that requirement? There are multiple ways of doing this:
 
-#### Using type hints with `prefetch.Required`
+#### Using type hints with `hints.Virtual`
 
 This library supports special type hints for informing what virtual fields a serializer method needs:
 
 ```python
 # Python < 3.9. For >= 3.9, use `from typing import Annotated`:
 from typing_extensions import Annotated
-from django_virtual_models import prefetch
+from django_virtual_models import hints
 
 class PersonSerializer(v.VirtualModelSerializer):
     ...
 
     def get_has_won_any_award(
         self,
         # Type hint to ensure `awards` here:
-        person: Annotated[Person, prefetch.Required("awards")]
+        person: Annotated[Person, hints.Virtual("awards")]
     ):
         return len(person.awards) > 0
 ```
 
-Now thanks to `prefetch.Required("awards")`, this serializer will be able to require the field `awards` from the virtual model. If necessary, you can pass multiple fields or even nested lookups: `prefetch.Required("awards", "nominations__movie")`.
+Now thanks to `hints.Virtual("awards")`, this serializer will be able to require the field `awards` from the virtual model. If necessary, you can pass multiple fields or even nested lookups: `hints.Virtual("awards", "nominations__movie")`.
 
 !!! note
-    `prefetch.Required` can be used to ensure the fetching of any `deferred_fields` a method needs without N+1s.
+    `hints.Virtual` can be used to ensure the fetching of any `deferred_fields` a method needs without N+1s.
 
 !!! note
     [Annotated](https://docs.python.org/3/library/typing.html#typing.Annotated) is a built-in Python construct that allows us to add custom annotations that don't affect type checking.
 
 #### Using `from_types_of` decorator
 
-If your method calls another function, you can add type hints to that function with `prefetch.Required` and then use the `from_types_of` decorator:
+If your method calls another function, you can add type hints to that function with `hints.Virtual` and then use the `from_types_of` decorator:
 
 ```python
 # Python < 3.9. For >= 3.9, use `from typing import Annotated`:
 from typing_extensions import Annotated
-from django_virtual_models import prefetch
+from django_virtual_models import hints
 
 def check_person_has_won_any_award(
     # Type hint to ensure `awards` here:
-    person: Annotated[Person, prefetch.Required("awards")]
+    person: Annotated[Person, hints.Virtual("awards")]
 ):
     return len(person.awards) > 0
 
 class PersonSerializer(v.VirtualModelSerializer):
     ...
 
     # Decorator to specify where to find the type hint here:
-    @prefetch.hints.from_types_of(check_person_has_won_any_award, "person")
+    @hints.from_types_of(check_person_has_won_any_award, "person")
     def get_has_won_any_award(self, person, check_person_has_won_any_award):
         return check_person_has_won_any_award(person)
 ```
@@ -494,12 +494,12 @@ Note the function `check_person_has_won_any_award` is received in the decorator
 If you have the `has_won_any_award` field in your virtual model, you can use the `defined_on_virtual_model` decorator:
 
 ```python
-from django_virtual_models import prefetch
+from django_virtual_models import hints
 
 class PersonSerializer(v.VirtualModelSerializer):
     ...
 
-    @prefetch.hints.defined_on_virtual_model()  # <--- here
+    @hints.defined_on_virtual_model()  # <--- here
     def get_has_won_any_award(self, person):
         return person.has_won_any_award
 ```
@@ -509,7 +509,7 @@ class PersonSerializer(v.VirtualModelSerializer):
 If your method field only uses concrete fields, in other words, it doesn't depend on any virtual model fields, nor any `deferred_fields`, you can use the `no_deferred_fields` decorator:
 
 ```python
-from django_virtual_models import prefetch
+from django_virtual_models import hints
 
 class PersonSerializer(v.VirtualModelSerializer):
     name_title_case = serializers.SerializerMethodField()
@@ -519,7 +519,7 @@ class PersonSerializer(v.VirtualModelSerializer):
         virtual_model = VirtualPerson
         fields = ["name_title_case"]
 
-    @prefetch.hints.no_deferred_fields()  # <--- here
+    @hints.no_deferred_fields()  # <--- here
     def get_name_title_case(self, person):
         return person.name.title()
 ```
@@ -529,18 +529,18 @@ class PersonSerializer(v.VirtualModelSerializer):
 DRF Serializers can use directly model properties and methods in `Meta.fields`. If your serializer uses a model property or method, you need to use the same hints described by the previous section ["Prefetching for method fields"](#prefetching-for-method-fields-serializermethodfield). For example:
 
 ```python
-from django_virtual_models import prefetch
+from django_virtual_models import hints
 
 class Person(models.Model):
     name = models.CharField(max_length=255)
 
     @property  # <--- property must come before
-    @prefetch.hints.no_deferred_fields()
+    @hints.no_deferred_fields()
     def name_title_case(self):
         return self.name.title()
 
     # method w/o params, DRF supports that too:
-    def has_won_any_award(self: Annotated[Person, prefetch.Required("awards")]):
+    def has_won_any_award(self: Annotated[Person, hints.Virtual("awards")]):
         return len(person.awards) > 0
 
 class PersonSerializer(v.VirtualModelSerializer):