djhtmx 1.1.2__tar.gz → 1.2.0__tar.gz

{djhtmx-1.1.2 → djhtmx-1.2.0}/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.2.0] - 2025-09-29
+
+### Added
+- **Enhanced HTMX Module Discovery**: HTMX components can now be organized in directory structures within Django apps. The autodiscovery system now recursively imports all Python modules under `htmx/` directories, in addition to the traditional single `htmx.py` files. This allows for better code organization in larger projects.
+- **New Management Commands**:
+  - `python manage.py htmx check-unused`: Check for unused HTMX components in your project
+  - `python manage.py htmx check-unused-non-public`: Check for unused non-public HTMX components
+
+### Changed
+- **BREAKING**: Template name validation now raises `ImproperlyConfigured` exceptions instead of logging warnings when HTMX component template names don't match the component class name. This provides better error visibility and prevents potential runtime issues.
+
+### Technical Details
+- Modified `apps.py` to use the new autodiscovery function instead of Django's standard `autodiscover_modules("htmx")`
+- Added `autodiscover_htmx_modules()` function in `utils.py` that recursively discovers and imports all Python modules in `htmx/` directories across Django apps
+- Maintains full backward compatibility with existing single `htmx.py` files
+
+### Migration Guide
+- **Template Name Validation**: If you have components with mismatched template names, you'll now get `ImproperlyConfigured` exceptions instead of warnings. Update your component template names to match the class names.
+- **Module Organization**: You can now organize your HTMX components in directory structures under `htmx/` in your Django apps. No changes required for existing single `htmx.py` files.
+
 ## [1.1.2] - 2025-08-27
 
 ### Fixed

{djhtmx-1.1.2 → djhtmx-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: djhtmx
-Version: 1.1.2
+Version: 1.2.0
 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
@@ -184,6 +184,33 @@ This library is opinionated about how to use HTMX with Django, but it is not opi
 
 This app will look for `htmx.py` files in your app and registers all components found there, but if you load any module where you have components manually when Django boots up, that also works.
 
+### Component Organization
+
+As of version 1.2.0, djhtmx supports both single file and directory-based component organization:
+
+**Single file (traditional):**
+```
+myapp/
+├── htmx.py  # All components in one file
+└── ...
+```
+
+**Directory structure (new in v1.2.0):**
+```
+myapp/
+├── htmx/
+│   ├── __init__.py
+│   ├── components.py      # Basic components
+│   ├── forms.py           # Form components
+│   └── widgets/
+│       ├── __init__.py
+│       ├── calendar.py    # Calendar widgets
+│       └── charts.py      # Chart widgets
+└── ...
+```
+
+The autodiscovery system will recursively find and import all Python modules under `htmx/` directories, allowing you to organize your components in a structured way that scales with your project size.
+
 ```python
 from djhtmx.component import HtmxComponent
 

{djhtmx-1.1.2 → djhtmx-1.2.0}/README.md

@@ -137,6 +137,33 @@ This library is opinionated about how to use HTMX with Django, but it is not opi
 
 This app will look for `htmx.py` files in your app and registers all components found there, but if you load any module where you have components manually when Django boots up, that also works.
 
+### Component Organization
+
+As of version 1.2.0, djhtmx supports both single file and directory-based component organization:
+
+**Single file (traditional):**
+```
+myapp/
+├── htmx.py  # All components in one file
+└── ...
+```
+
+**Directory structure (new in v1.2.0):**
+```
+myapp/
+├── htmx/
+│   ├── __init__.py
+│   ├── components.py      # Basic components
+│   ├── forms.py           # Form components
+│   └── widgets/
+│       ├── __init__.py
+│       ├── calendar.py    # Calendar widgets
+│       └── charts.py      # Chart widgets
+└── ...
+```
+
+The autodiscovery system will recursively find and import all Python modules under `htmx/` directories, allowing you to organize your components in a structured way that scales with your project size.
+
 ```python
 from djhtmx.component import HtmxComponent
 

{djhtmx-1.1.2 → djhtmx-1.2.0}/src/djhtmx/__init__.py

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

{djhtmx-1.1.2 → djhtmx-1.2.0}/src/djhtmx/apps.py

@@ -1,11 +1,13 @@
 from django.apps import AppConfig
 from django.utils.module_loading import autodiscover_modules
 
+from .utils import autodiscover_htmx_modules
+
 
 class App(AppConfig):
     name = "djhtmx"
     verbose_name = "Django HTMX"
 
     def ready(self):
-        autodiscover_modules("live")
-        autodiscover_modules("htmx")
+        autodiscover_modules("live")  # legacy
+        autodiscover_htmx_modules()

{djhtmx-1.1.2 → djhtmx-1.2.0}/src/djhtmx/component.py

@@ -20,6 +20,7 @@ from typing import (
     get_type_hints,
 )
 
+from django.core.exceptions import ImproperlyConfigured
 from django.db import models
 from django.shortcuts import resolve_url
 from django.template import Context, loader
@@ -306,9 +307,8 @@ class HtmxComponent(BaseModel):
             basename(cls._template_name.default)
             not in (f"{klass.__name__}.html" for klass in cls.__mro__)
         ):
-            logger.warning(
-                "HTMX Component <%s> template name does not match the component name",
-                FQN[cls],
+            raise ImproperlyConfigured(
+                f"HTMX Component <{FQN[cls]}> template name does not match the component name"
             )
 
         # We use 'get_type_hints' to resolve the forward refs if needed, but

{djhtmx-1.1.2 → djhtmx-1.2.0}/src/djhtmx/management/commands/htmx.py

@@ -46,6 +46,58 @@ def check_missing(fname):
         sys.exit(1)
 
 
+@htmx.command("check-unused")  # type: ignore
+@click.argument("fname", type=click.File())
+def check_unused(fname):
+    r"""Check if there are any unused HTMX components.
+
+    Expected usage:
+
+    find -type f -name '*.html' | while read f; do grep -P '{% htmx .(\\w+)' -o $f \
+    | awk '{print $3}' | cut -b2-; done | sort -u \
+    | python manage.py htmx check-unused -
+
+    """
+    names = {n.strip() for n in fname.readlines()}
+    known = set(REGISTRY)
+    unused = list(known - names)
+    if unused:
+        unused.sort()
+        for n in unused:
+            click.echo(
+                f"Unused component detected {bold(yellow(n))}",
+                file=sys.stderr,
+            )
+        sys.exit(1)
+
+
+@htmx.command("check-unused-non-public")  # type: ignore
+def check_unused_non_public():
+    """Check if there are any unused non-public HTMX components.
+
+    Non-public components that are final subclasses (have no subclasses themselves)
+    are considered unused since they can't be instantiated from templates and serve
+    no purpose as base classes.
+    """
+    final_subclasses = set(
+        get_final_subclasses(
+            HtmxComponent,  # type: ignore
+            without_duplicates=True,
+        )
+    )
+    registered = set(REGISTRY.values())
+    unused_non_public = list(final_subclasses - registered)
+
+    if unused_non_public:
+        unused_non_public.sort(key=lambda cls: cls.__name__)
+        for cls in unused_non_public:
+            click.echo(
+                f"Unused non-public component detected {bold(yellow(cls.__name__))}",
+                file=sys.stderr,
+            )
+        sys.exit(1)
+
+
 @htmx.command("check-shadowing")  # type: ignore
 def check_shadowing():
     "Checks if there are components that might shadow one another."

{djhtmx-1.1.2 → djhtmx-1.2.0}/src/djhtmx/utils.py

@@ -1,8 +1,12 @@
+import contextlib
+import importlib
+import pkgutil
 import typing as t
 from urllib.parse import urlparse
 
 import mmh3
 from channels.db import database_sync_to_async as db  # type: ignore
+from django.apps import apps
 from django.db import models
 from django.http.request import HttpRequest, QueryDict
 from uuid6 import uuid7
@@ -115,3 +119,26 @@ def compact_hash(value: str) -> str:
 # The symbols are chosen to avoid extra encoding in the URL and HTML, and
 # allowed in plain CSS selectors.
 _BASE = "ZmBeUHhTgusXNW_Y1b05KPiFcQJD86joqnIRE7Lfkrdp3AOMCvltSwzVG9yxa42"
+
+
+def autodiscover_htmx_modules():
+    """
+    Auto-discover HTMX modules in Django apps.
+
+    This discovers both:
+    - htmx.py files (like standard autodiscover_modules("htmx"))
+    - All Python files under htmx/ directories in apps (recursively)
+    """
+    def _import_modules_recursively(module_name):
+        """Recursively import a module and all its submodules."""
+        with contextlib.suppress(ImportError):
+            module = importlib.import_module(module_name)
+
+            # If this is a package, recursively import all modules in it
+            if hasattr(module, "__path__"):
+                for _finder, submodule_name, _is_pkg in pkgutil.iter_modules(module.__path__):
+                    _import_modules_recursively(f"{module_name}.{submodule_name}")
+
+    for app_config in apps.get_app_configs():
+        # Import htmx module and all its submodules recursively
+        _import_modules_recursively(f"{app_config.name}.htmx")