djhtmx 1.3.0__tar.gz → 1.3.2__tar.gz

{djhtmx-1.3.0 → djhtmx-1.3.2}/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.3.2] - 2026-01-14
+
+### Fixed
+- **Generic Type Handling**: Fixed `annotate_model()` to preserve non-Model generic types (like `defaultdict`, `list`, `dict`) when used with `Annotated` wrappers. Previously, these types would be incorrectly transformed to `None`, causing validation errors.
+
+## [1.3.1] - 2026-01-14
+
+### Fixed
+- **Optional Model Loading**: Fixed `Model | None` annotations to return `None` when an object with the provided ID doesn't exist (e.g., was deleted), instead of raising `DoesNotExist` exception. Uses `.filter().first()` approach for graceful handling of missing objects.
+
+### Added
+- Comprehensive test coverage for optional model handling in both lazy and non-lazy loading scenarios
+- Documentation for model loading optimization (lazy loading, `select_related`, `prefetch_related`) in README
+
+### Changed
+- Query parameter handling now preserves full annotation metadata for proper serialization of `Model | None` fields
+- Enhanced `is_basic_type()` to recognize `Model | None` unions as valid simple types for query parameters
+
 ## [1.3.0] - 2026-01-07
 
 ### Changed

{djhtmx-1.3.0 → djhtmx-1.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: djhtmx
-Version: 1.3.0
+Version: 1.3.2
 Summary: Interactive UI Components for Django using HTMX
 Project-URL: Homepage, https://github.com/edelvalle/djhtmx
 Project-URL: Documentation, https://github.com/edelvalle/djhtmx#readme
@@ -282,6 +282,35 @@ class BaseComponent(HtmxComponent, public=False):
     ...
 ```
 
+### Model Loading Optimization
+
+Components can optimize database queries when loading Django models:
+
+```python
+from typing import Annotated
+from djhtmx.introspection import ModelConfig
+
+class TodoComponent(HtmxComponent):
+    # Basic: loads immediately when component is created
+    item: Item
+
+    # Optional: returns None if object doesn't exist (e.g., was deleted)
+    archived_item: Item | None = None
+
+    # Lazy: defers loading until accessed
+    user: Annotated[User, ModelConfig(lazy=True)]
+
+    # Optimized: use select_related for foreign keys, prefetch_related for reverse FKs/M2M
+    todo_list: Annotated[
+        TodoList,
+        ModelConfig(
+            lazy=True,
+            select_related=["owner", "category"],
+            prefetch_related=["items", "items__tags"]
+        )
+    ]
+```
+
 ## Component nesting
 
 Components can contain components inside to decompose the behavior in more granular and specialized parts, for this you don't have to do anything but to a component inside the template of other component....

{djhtmx-1.3.0 → djhtmx-1.3.2}/README.md

@@ -235,6 +235,35 @@ class BaseComponent(HtmxComponent, public=False):
     ...
 ```
 
+### Model Loading Optimization
+
+Components can optimize database queries when loading Django models:
+
+```python
+from typing import Annotated
+from djhtmx.introspection import ModelConfig
+
+class TodoComponent(HtmxComponent):
+    # Basic: loads immediately when component is created
+    item: Item
+
+    # Optional: returns None if object doesn't exist (e.g., was deleted)
+    archived_item: Item | None = None
+
+    # Lazy: defers loading until accessed
+    user: Annotated[User, ModelConfig(lazy=True)]
+
+    # Optimized: use select_related for foreign keys, prefetch_related for reverse FKs/M2M
+    todo_list: Annotated[
+        TodoList,
+        ModelConfig(
+            lazy=True,
+            select_related=["owner", "category"],
+            prefetch_related=["items", "items__tags"]
+        )
+    ]
+```
+
 ## Component nesting
 
 Components can contain components inside to decompose the behavior in more granular and specialized parts, for this you don't have to do anything but to a component inside the template of other component....

{djhtmx-1.3.0 → djhtmx-1.3.2}/src/djhtmx/__init__.py

@@ -1,4 +1,4 @@
 from .middleware import middleware
 
-__version__ = "1.3.0"
+__version__ = "1.3.2"
 __all__ = ("middleware",)

{djhtmx-1.3.0 → djhtmx-1.3.2}/src/djhtmx/introspection.py

@@ -29,6 +29,7 @@ from django.db import models
 from django.db.models import Prefetch
 from django.utils.datastructures import MultiValueDict
 from pydantic import BeforeValidator, PlainSerializer, TypeAdapter
+from pydantic_core import PydanticCustomError
 
 M = TypeVar("M", bound=models.Model)
 
@@ -106,14 +107,19 @@ class _LazyModelProxy(Generic[M]):  # noqa
         return getattr(self.__instance, name)
 
     def __ensure_instance(self):
-        if not self.__instance:
+        if self.__instance:
+            return self.__instance
+        elif self.__pk is None:
+            # If pk is None, don't try to load anything
+            return None
+        else:
             manager = self.__model.objects
             if select_related := self.__select_related:
                 manager = manager.select_related(*select_related)
             if prefetch_related := self.__prefetch_related:
                 manager = manager.prefetch_related(*prefetch_related)
-            self.__instance = manager.get(pk=self.__pk)
-        return self.__instance
+            self.__instance = manager.filter(pk=self.__pk).first()
+            return self.__instance
 
     def __repr__(self) -> str:
         return f"<_LazyModelProxy model={self.__model}, pk={self.__pk}, instance={self.__instance}>"
@@ -123,6 +129,7 @@ class _LazyModelProxy(Generic[M]):  # noqa
 class _ModelBeforeValidator(Generic[M]):  # noqa
     model: type[M]
     model_config: ModelConfig
+    allow_none: bool = False
 
     def __call__(self, value):
         if self.model_config.lazy:
@@ -131,11 +138,14 @@ class _ModelBeforeValidator(Generic[M]):  # noqa
             return self._get_instance(value)
 
     def _get_lazy_proxy(self, value):
-        if isinstance(value, _LazyModelProxy):
+        if value is None:
+            # Don't create a proxy for explicit None
+            return None
+        elif isinstance(value, _LazyModelProxy):
             instance = value._LazyModelProxy__instance or value._LazyModelProxy__pk
-            return _LazyModelProxy(self.model, instance)
+            return _LazyModelProxy(self.model, instance, model_annotation=self.model_config)
         else:
-            return _LazyModelProxy(self.model, value)
+            return _LazyModelProxy(self.model, value, model_annotation=self.model_config)
 
     def _get_instance(self, value):
         if value is None or isinstance(value, self.model):
@@ -150,12 +160,25 @@ class _ModelBeforeValidator(Generic[M]):  # noqa
                 manager = manager.select_related(*select_related)
             if prefetch_related := self.model_config.prefetch_related:
                 manager = manager.prefetch_related(*prefetch_related)
-            return manager.get(pk=value)
+            # Use filter().first() instead of get() to avoid exceptions
+            instance = manager.filter(pk=value).first()
+            if instance is None:
+                if self.allow_none:
+                    # For Model | None fields, return None when object doesn't exist
+                    return None
+                else:
+                    # For required Model fields, raise validation error
+                    raise PydanticCustomError(
+                        "model_not_found",
+                        f"{self.model.__name__} with pk={{pk}} does not exist",
+                        {"pk": value},
+                    )
+            return instance
 
     @classmethod
     @cache
-    def from_modelclass(cls, model: type[M], model_config: ModelConfig):
-        return cls(model, model_config=model_config)
+    def from_modelclass(cls, model: type[M], model_config: ModelConfig, allow_none: bool = False):
+        return cls(model, model_config=model_config, allow_none=allow_none)
 
 
 @dataclass(slots=True)
@@ -163,7 +186,11 @@ class _ModelPlainSerializer(Generic[M]):  # noqa
     model: type[M]
 
     def __call__(self, value):
-        return value.pk
+        # Handle None for Model | None fields
+        if value is None:
+            return None
+        else:
+            return value.pk
 
     @classmethod
     @cache
@@ -171,12 +198,18 @@ class _ModelPlainSerializer(Generic[M]):  # noqa
         return cls(model)
 
 
-def _Model(model: type[models.Model], model_config: ModelConfig | None = None):
+def _Model(
+    model: type[models.Model], model_config: ModelConfig | None = None, allow_none: bool = False
+):
     assert issubclass_safe(model, models.Model)
     model_config = model_config or _DEFAULT_MODEL_CONFIG
+    base_type = model if not model_config.lazy else _LazyModelProxy[model]
+    # If allow_none is True, the base type can be None (for Model | None unions)
+    if allow_none:
+        base_type = base_type | None  # type: ignore
     return Annotated[
-        model if not model_config.lazy else _LazyModelProxy[model],
-        BeforeValidator(_ModelBeforeValidator.from_modelclass(model, model_config)),
+        base_type,
+        BeforeValidator(_ModelBeforeValidator.from_modelclass(model, model_config, allow_none)),
         PlainSerializer(
             func=_ModelPlainSerializer.from_modelclass(model),
             return_type=guess_pk_type(model),
@@ -214,19 +247,54 @@ def annotate_model(annotation, *, model_config: ModelConfig | None = None):
             },
         )
     elif type_ := get_origin(annotation):
-        if type_ is types.UnionType or type_ is Union:
+        # Handle Annotated types like Annotated[Item | None, Query("editing")]
+        if type_ is Annotated:
+            args = get_args(annotation)
+            if args:
+                # Process the base type (first arg) and keep other metadata
+                base_type = args[0]
+                metadata = args[1:]
+                processed_base = annotate_model(base_type, model_config=model_config)
+
+                # If processed_base is also Annotated, merge the metadata
+                if get_origin(processed_base) is Annotated:
+                    processed_args = get_args(processed_base)
+                    inner_base = processed_args[0]
+                    inner_metadata = processed_args[1:]
+                    # Merge: inner metadata first, then original metadata
+                    return Annotated[inner_base, *inner_metadata, *metadata]  # type: ignore
+                else:
+                    # Reconstruct the Annotated with processed base type
+                    return Annotated[processed_base, *metadata]  # type: ignore
+            return annotation
+        elif type_ is types.UnionType or type_ is Union:
             type_ = Union
-        match get_args(annotation):
-            case ():
-                return type_
-            case (param,):
-                return type_[annotate_model(param)]  # type: ignore
-            case params:
-                model_annotation = next(
-                    (p for p in params if isinstance(p, ModelConfig)),
-                    None,
-                )
-                return type_[*(annotate_model(p, model_config=model_annotation) for p in params)]  # type: ignore
+            match get_args(annotation):
+                case ():
+                    return type_
+                case (param,):
+                    return type_[annotate_model(param)]  # type: ignore
+                case params:
+                    model_annotation = next(
+                        (p for p in params if isinstance(p, ModelConfig)),
+                        None,
+                    )
+                    # Check if this is a Model | None union
+                    has_none = types.NoneType in params
+                    model_params = [p for p in params if issubclass_safe(p, models.Model)]
+
+                    if has_none and len(model_params) == 1:
+                        # This is a Model | None union - use allow_none=True
+                        # Use the model_config parameter passed to annotate_model, not model_annotation from Union params
+                        model = model_params[0]
+                        return _Model(model, model_config or model_annotation, allow_none=True)
+                    else:
+                        # Regular union - process each param independently
+                        return type_[
+                            *(annotate_model(p, model_config=model_annotation) for p in params)
+                        ]  # type: ignore
+        # Other generic types (list, dict, defaultdict, etc.) - return as-is
+        return annotation
     else:
         return annotation
 
@@ -404,10 +472,27 @@ def is_basic_type(ann):
     - Literal types with simple values
 
     """
+    # Check if it's a Union (e.g., Item | None)
+    origin_type = get_origin(ann)
+    if origin_type in (types.UnionType, Union):
+        args = get_args(ann)
+        # If it's Model | None, consider it a basic type
+        model_types = [arg for arg in args if issubclass_safe(arg, models.Model)]
+        if model_types and types.NoneType in args:
+            return True
+
+    # Check for Annotated[Model, ...] or Annotated[Model | None, ...] pattern
+    origin = getattr(ann, "__origin__", None)
+    if origin is not None and get_origin(origin) in (types.UnionType, Union):
+        args = get_args(origin)
+        model_types = [arg for arg in args if issubclass_safe(arg, models.Model)]
+        if model_types and types.NoneType in args:
+            return True
+
     return (
         ann in _SIMPLE_TYPES
         #  __origin__ -> model in 'Annotated[model, BeforeValidator(...), PlainSerializer(...)]'
-        or issubclass_safe(getattr(ann, "__origin__", None), models.Model)
+        or issubclass_safe(origin, models.Model)
         or issubclass_safe(ann, (enum.IntEnum, enum.StrEnum))
         or is_collection_annotation(ann)
         or is_literal_annotation(ann)

{djhtmx-1.3.0 → djhtmx-1.3.2}/src/djhtmx/query.py

@@ -107,7 +107,10 @@ class QueryPatcher:
                 # Prefix with the component name if not shared
                 if not query.shared:
                     param_name = f"{param_name}-{compact_hash(component.__name__)}"
-                adapter = get_annotation_adapter(field.annotation)
+
+                # Use the full annotation from __annotations__ to preserve serializers
+                full_annotation = component.__annotations__.get(field_name, field.annotation)
+                adapter = get_annotation_adapter(full_annotation)
                 yield cls(
                     field_name=field_name,
                     param_name=param_name,