djhtmx 1.3.2__tar.gz → 1.3.4__tar.gz

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

@@ -7,23 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [1.3.2] - 2026-01-14
+## [1.3.4] - 2026-01-19
 
-### 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.
+**Note**: This release supersedes versions 1.3.1, 1.3.2, and 1.3.3, which contained incomplete implementations of the `Model | None` handling feature. Users on 1.3.1-1.3.3 should upgrade to 1.3.4 immediately.
 
-## [1.3.1] - 2026-01-14
+### Added
+- **Yield Logging**: Added debug logging for commands yielded from component methods during event handling. Logs format: `< YIELD: ComponentName.method_name -> Command(...)`. Helps developers track command flow and debug issues when components emit multiple commands.
+- Comprehensive test coverage for `Model | None` and lazy model handling with 12 new tests
 
 ### 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
+- **Model | None Handling**: Fixed components with `Model | None` fields to gracefully return `None` when objects don't exist or have been deleted, instead of raising `DoesNotExist` exceptions
+  - Changed database lookups from `manager.get()` to `manager.filter().first()` for graceful handling
+  - For optional fields (`Model | None`), returns `None` when object doesn't exist
+  - For required fields (`Model`), raises clear `ValueError` with descriptive message
+  - Works correctly with both eager and lazy loading (`ModelConfig(lazy=True)`)
+  - Lazy models create proxies that handle non-existent objects when attributes are accessed
+- **Type Safety**: Added None check for `app_config.module` in `autodiscover_htmx_modules()` to prevent AttributeError
 
-### 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
+### Technical Details
+- Added `allow_none` parameter to `_ModelBeforeValidator` and `_LazyModelProxy` classes
+- Enhanced `annotate_model()` to detect `Model | None` unions and pass `allow_none=True`
+- Updated lazy proxy `__ensure_instance()` to use `filter().first()` and handle missing objects gracefully
+- QuerySet fields continue to work correctly by silently filtering out non-existent IDs
 
 ## [1.3.0] - 2026-01-07
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: djhtmx
-Version: 1.3.2
+Version: 1.3.4
 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
@@ -311,6 +311,23 @@ class TodoComponent(HtmxComponent):
     ]
 ```
 
+**Handling Deleted Objects:**
+
+Lazy models handle deleted database objects gracefully:
+
+```python
+class MyComponent(HtmxComponent):
+    # Required: raises ObjectDoesNotExist when checking if object was deleted
+    item: Annotated[Item, ModelConfig(lazy=True)]
+
+    # Optional: becomes falsy and returns None when object was deleted
+    archived_item: Annotated[Item | None, ModelConfig(lazy=True)]
+```
+
+- **Required lazy models**: Checking truthiness (`if component.item:`) raises `ObjectDoesNotExist` with a clear message
+- **Optional lazy models**: Checking truthiness returns `False`, field accesses return `None`
+- **Both**: Accessing `.pk` always works without triggering database queries
+
 ## 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.2 → djhtmx-1.3.4}/README.md

@@ -264,6 +264,23 @@ class TodoComponent(HtmxComponent):
     ]
 ```
 
+**Handling Deleted Objects:**
+
+Lazy models handle deleted database objects gracefully:
+
+```python
+class MyComponent(HtmxComponent):
+    # Required: raises ObjectDoesNotExist when checking if object was deleted
+    item: Annotated[Item, ModelConfig(lazy=True)]
+
+    # Optional: becomes falsy and returns None when object was deleted
+    archived_item: Annotated[Item | None, ModelConfig(lazy=True)]
+```
+
+- **Required lazy models**: Checking truthiness (`if component.item:`) raises `ObjectDoesNotExist` with a clear message
+- **Optional lazy models**: Checking truthiness returns `False`, field accesses return `None`
+- **Both**: Accessing `.pk` always works without triggering database queries
+
 ## 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.2 → djhtmx-1.3.4}/src/djhtmx/__init__.py

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

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

@@ -29,7 +29,6 @@ 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)
 
@@ -78,14 +77,17 @@ class _LazyModelProxy(Generic[M]):  # noqa
     __pk: Any | None
     __select_related: Sequence[str] | None
     __prefetch_related: Sequence[str | Prefetch] | None
+    __allow_none: bool
 
     def __init__(
         self,
         model: type[M],
         value: Any,
         model_annotation: ModelConfig | None = None,
+        allow_none: bool = False,
     ):
         self.__model = model
+        self.__allow_none = allow_none
         if value is None or isinstance(value, model):
             self.__instance = value
             self.__pk = getattr(value, "pk", None)
@@ -107,19 +109,22 @@ class _LazyModelProxy(Generic[M]):  # noqa
         return getattr(self.__instance, name)
 
     def __ensure_instance(self):
-        if self.__instance:
-            return self.__instance
-        elif self.__pk is None:
-            # If pk is None, don't try to load anything
-            return None
-        else:
+        if not self.__instance:
             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)
+            # Use filter().first() instead of get() to avoid exceptions
             self.__instance = manager.filter(pk=self.__pk).first()
-            return self.__instance
+            if self.__instance is None:
+                if self.__allow_none:
+                    # For Model | None, object doesn't exist - proxy becomes None-like
+                    pass
+                else:
+                    # For required Model fields, raise error
+                    raise ValueError(f"{self.__model.__name__} with pk={self.__pk} does not exist")
+        return self.__instance
 
     def __repr__(self) -> str:
         return f"<_LazyModelProxy model={self.__model}, pk={self.__pk}, instance={self.__instance}>"
@@ -138,14 +143,11 @@ class _ModelBeforeValidator(Generic[M]):  # noqa
             return self._get_instance(value)
 
     def _get_lazy_proxy(self, value):
-        if value is None:
-            # Don't create a proxy for explicit None
-            return None
-        elif isinstance(value, _LazyModelProxy):
+        if isinstance(value, _LazyModelProxy):
             instance = value._LazyModelProxy__instance or value._LazyModelProxy__pk
-            return _LazyModelProxy(self.model, instance, model_annotation=self.model_config)
+            return _LazyModelProxy(self.model, instance, allow_none=self.allow_none)
         else:
-            return _LazyModelProxy(self.model, value, model_annotation=self.model_config)
+            return _LazyModelProxy(self.model, value, allow_none=self.allow_none)
 
     def _get_instance(self, value):
         if value is None or isinstance(value, self.model):
@@ -168,11 +170,7 @@ class _ModelBeforeValidator(Generic[M]):  # noqa
                     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},
-                    )
+                    raise ValueError(f"{self.model.__name__} with pk={value} does not exist")
             return instance
 
     @classmethod
@@ -186,11 +184,7 @@ class _ModelPlainSerializer(Generic[M]):  # noqa
     model: type[M]
 
     def __call__(self, value):
-        # Handle None for Model | None fields
-        if value is None:
-            return None
-        else:
-            return value.pk
+        return value.pk
 
     @classmethod
     @cache
@@ -199,16 +193,20 @@ class _ModelPlainSerializer(Generic[M]):  # noqa
 
 
 def _Model(
-    model: type[models.Model], model_config: ModelConfig | None = None, allow_none: bool = False
+    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
+
+    # Determine the base type
     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
+    # If allow_none, make it optional
+    annotated_type = base_type | None if allow_none else base_type
+
     return Annotated[
-        base_type,
+        annotated_type,
         BeforeValidator(_ModelBeforeValidator.from_modelclass(model, model_config, allow_none)),
         PlainSerializer(
             func=_ModelPlainSerializer.from_modelclass(model),
@@ -247,54 +245,45 @@ def annotate_model(annotation, *, model_config: ModelConfig | None = None):
             },
         )
     elif type_ := get_origin(annotation):
-        # 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:
+        if 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,
-                    )
-                    # 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
+        match get_args(annotation):
+            case ():
+                return type_
+            case (param,):
+                return type_[annotate_model(param)]  # type: ignore
+            case params:
+                # Check for ModelConfig in params (for Annotated types)
+                param_model_config = next(
+                    (p for p in params if isinstance(p, ModelConfig)),
+                    None,
+                )
+                # Use param ModelConfig if found, otherwise use the passed model_config
+                effective_model_config = param_model_config or model_config
+
+                # Check if this is a Model | None union
+                has_none = types.NoneType in params
+                model_types = [p for p in params if issubclass_safe(p, models.Model)]
+
+                # If we have Model | None, annotate the model with allow_none=True
+                if has_none and len(model_types) == 1:
+                    annotated_params = []
+                    for p in params:
+                        if issubclass_safe(p, models.Model):
+                            annotated_params.append(
+                                _Model(p, effective_model_config, allow_none=True)
+                            )
+                        elif p is not types.NoneType:
+                            annotated_params.append(
+                                annotate_model(p, model_config=effective_model_config)
+                            )
+                        else:
+                            annotated_params.append(p)
+                    return type_[*annotated_params]  # type: ignore
+                else:
+                    return type_[
+                        *(annotate_model(p, model_config=effective_model_config) for p in params)
+                    ]  # type: ignore
     else:
         return annotation
 
@@ -472,27 +461,10 @@ 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(origin, models.Model)
+        or issubclass_safe(getattr(ann, "__origin__", None), models.Model)
         or issubclass_safe(ann, (enum.IntEnum, enum.StrEnum))
         or is_collection_annotation(ann)
         or is_literal_annotation(ann)

{djhtmx-1.3.2 → djhtmx-1.3.4}/src/djhtmx/repo.py

@@ -240,7 +240,11 @@ class Repository:
                                 Emit(HtmxUnhandledError(error, handler_annotations=annotations))
                             ]
                         yield from self._process_emited_commands(
-                            component, emited_commands, commands, during_execute=True
+                            component,
+                            emited_commands,
+                            commands,
+                            during_execute=True,
+                            method_name=event_handler,
                         )
 
             case SkipRender(component):
@@ -286,7 +290,11 @@ class Repository:
                         else:
                             raise
                     yield from self._process_emited_commands(
-                        component, emited_commands, commands, during_execute=False
+                        component,
+                        emited_commands,
+                        commands,
+                        during_execute=False,
+                        method_name="_handle_event",
                     )
 
             case Signal(signals):
@@ -320,10 +328,13 @@ class Repository:
         emmited_commands: Iterable[Command] | None,
         commands: CommandQueue,
         during_execute: bool,
+        method_name: str | None = None,
     ) -> Iterable[ProcessedCommand]:
         component_was_rendered = False
         commands_to_add: list[Command] = []
         for command in emmited_commands or []:
+            if method_name:
+                logger.debug("< YIELD: %s.%s -> %s", component.hx_name, method_name, command)
             component_was_rendered = component_was_rendered or (
                 isinstance(command, SkipRender | Render) and command.component.id == component.id
             )

{djhtmx-1.3.2 → djhtmx-1.3.4}/src/djhtmx/utils.py

@@ -130,6 +130,8 @@ def autodiscover_htmx_modules():
     - All Python files under htmx/ directories in apps (recursively)
     """
     for app_config in apps.get_app_configs():
+        if app_config.module is None:
+            continue
         module_name = f"{app_config.module.__name__}.htmx"
         spec = importlib.util.find_spec(module_name)
         if spec is None: