djhtmx 1.1.1__tar.gz → 1.2.0__tar.gz

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

@@ -7,6 +7,38 @@ 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
+- **Python 3.13 Compatibility**: Added support for `defaultdict[..., ...]` type annotations in Query introspection
+- Fixed type checking for generic aliases in collection annotations
+
+### Documentation
+- **Redis Dependency**: Added clear documentation that Redis is required and must be installed separately
+- **Framework Clarification**: Clarified that djhtmx is a framework, not a component library - no pre-built components are provided
+- **Settings Documentation**: Added comprehensive documentation for all available Django settings
+- **Installation Guide**: Added Redis installation instructions for different platforms
+
 ## [1.1.1] - 2025-08-23
 
 - Remove `get_model_subscriptions` `Action` annotation as string literals, as this does not reflect model relationships

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: djhtmx
-Version: 1.1.1
+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
@@ -66,6 +66,20 @@ pip install djhtmx
 
 # Configuration
 
+## Requirements
+
+djhtmx requires **Redis** to be running for session storage and component state management. 
+
+**Important**: Redis is not included with djhtmx and must be installed separately on your system. Make sure Redis is installed and accessible before using djhtmx.
+
+### Installing Redis
+
+- **macOS**: `brew install redis`
+- **Ubuntu/Debian**: `sudo apt-get install redis-server`
+- **CentOS/RHEL**: `sudo yum install redis` or `sudo dnf install redis`
+- **Docker**: `docker run -d -p 6379:6379 redis:alpine`
+- **Windows**: Download from [Redis for Windows](https://github.com/microsoftarchive/redis/releases)
+
 Add `djhtmx` to your `INSTALLED_APPS`.
 
 ```python
@@ -116,6 +130,40 @@ urlpatterns = [
 ]
 ```
 
+## Settings
+
+djhtmx can be configured through Django settings:
+
+### Required Settings
+
+- **`DJHTMX_REDIS_URL`** (default: `"redis://localhost/0"`): Redis connection URL for session storage and component state management.
+
+### Optional Settings
+
+- **`DJHTMX_SESSION_TTL`** (default: `3600`): Session timeout in seconds. Can be an integer or a `datetime.timedelta` object.
+- **`DJHTMX_DEFAULT_LAZY_TEMPLATE`** (default: `"htmx/lazy.html"`): Default template for lazy-loaded components.
+- **`DJHTMX_ENABLE_SENTRY_TRACING`** (default: `True`): Enable Sentry tracing integration.
+- **`DJHTMX_ENABLE_LOGFIRE_TRACING`** (default: `False`): Enable Logfire tracing integration.
+- **`DJHTMX_STRICT_EVENT_HANDLER_CONSISTENCY_CHECK`** (default: `False`): Enable strict consistency checking for event handlers.
+- **`DJHTMX_KEY_SIZE_ERROR_THRESHOLD`** (default: `0`): Threshold in bytes for session key size errors (0 = disabled).
+- **`DJHTMX_KEY_SIZE_WARN_THRESHOLD`** (default: `51200`): Threshold in bytes for session key size warnings (50KB).
+- **`DJHTMX_KEY_SIZE_SAMPLE_PROB`** (default: `0.1`): Probability for sampling session key size checks.
+
+### Example Configuration
+
+```python
+# settings.py
+
+# Redis connection (required)
+DJHTMX_REDIS_URL = "redis://localhost:6379/0"  # or redis://user:password@host:port/db
+
+# Optional settings
+DJHTMX_SESSION_TTL = 7200  # 2 hours
+DJHTMX_DEFAULT_LAZY_TEMPLATE = "my_app/lazy_component.html"
+DJHTMX_ENABLE_SENTRY_TRACING = True
+DJHTMX_KEY_SIZE_WARN_THRESHOLD = 100 * 1024  # 100KB
+```
+
 In your base template you need to load the necessary scripts to make this work
 
 ```html
@@ -130,8 +178,39 @@ In your base template you need to load the necessary scripts to make this work
 
 ## Getting started
 
+**Important**: djhtmx is a framework for building interactive components, not a component library. No pre-built components, templates, or behaviors are provided. You need to create your own components from scratch using the framework's base classes and conventions.
+
+This library is opinionated about how to use HTMX with Django, but it is not opinionated about components, styling, or specific functionality. You have complete freedom to design and implement your components as needed for your application.
+
 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.1 → djhtmx-1.2.0}/README.md

@@ -19,6 +19,20 @@ pip install djhtmx
 
 # Configuration
 
+## Requirements
+
+djhtmx requires **Redis** to be running for session storage and component state management. 
+
+**Important**: Redis is not included with djhtmx and must be installed separately on your system. Make sure Redis is installed and accessible before using djhtmx.
+
+### Installing Redis
+
+- **macOS**: `brew install redis`
+- **Ubuntu/Debian**: `sudo apt-get install redis-server`
+- **CentOS/RHEL**: `sudo yum install redis` or `sudo dnf install redis`
+- **Docker**: `docker run -d -p 6379:6379 redis:alpine`
+- **Windows**: Download from [Redis for Windows](https://github.com/microsoftarchive/redis/releases)
+
 Add `djhtmx` to your `INSTALLED_APPS`.
 
 ```python
@@ -69,6 +83,40 @@ urlpatterns = [
 ]
 ```
 
+## Settings
+
+djhtmx can be configured through Django settings:
+
+### Required Settings
+
+- **`DJHTMX_REDIS_URL`** (default: `"redis://localhost/0"`): Redis connection URL for session storage and component state management.
+
+### Optional Settings
+
+- **`DJHTMX_SESSION_TTL`** (default: `3600`): Session timeout in seconds. Can be an integer or a `datetime.timedelta` object.
+- **`DJHTMX_DEFAULT_LAZY_TEMPLATE`** (default: `"htmx/lazy.html"`): Default template for lazy-loaded components.
+- **`DJHTMX_ENABLE_SENTRY_TRACING`** (default: `True`): Enable Sentry tracing integration.
+- **`DJHTMX_ENABLE_LOGFIRE_TRACING`** (default: `False`): Enable Logfire tracing integration.
+- **`DJHTMX_STRICT_EVENT_HANDLER_CONSISTENCY_CHECK`** (default: `False`): Enable strict consistency checking for event handlers.
+- **`DJHTMX_KEY_SIZE_ERROR_THRESHOLD`** (default: `0`): Threshold in bytes for session key size errors (0 = disabled).
+- **`DJHTMX_KEY_SIZE_WARN_THRESHOLD`** (default: `51200`): Threshold in bytes for session key size warnings (50KB).
+- **`DJHTMX_KEY_SIZE_SAMPLE_PROB`** (default: `0.1`): Probability for sampling session key size checks.
+
+### Example Configuration
+
+```python
+# settings.py
+
+# Redis connection (required)
+DJHTMX_REDIS_URL = "redis://localhost:6379/0"  # or redis://user:password@host:port/db
+
+# Optional settings
+DJHTMX_SESSION_TTL = 7200  # 2 hours
+DJHTMX_DEFAULT_LAZY_TEMPLATE = "my_app/lazy_component.html"
+DJHTMX_ENABLE_SENTRY_TRACING = True
+DJHTMX_KEY_SIZE_WARN_THRESHOLD = 100 * 1024  # 100KB
+```
+
 In your base template you need to load the necessary scripts to make this work
 
 ```html
@@ -83,8 +131,39 @@ In your base template you need to load the necessary scripts to make this work
 
 ## Getting started
 
+**Important**: djhtmx is a framework for building interactive components, not a component library. No pre-built components, templates, or behaviors are provided. You need to create your own components from scratch using the framework's base classes and conventions.
+
+This library is opinionated about how to use HTMX with Django, but it is not opinionated about components, styling, or specific functionality. You have complete freedom to design and implement your components as needed for your application.
+
 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.1 → djhtmx-1.2.0}/src/djhtmx/__init__.py

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

{djhtmx-1.1.1 → 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.1 → 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.1 → djhtmx-1.2.0}/src/djhtmx/introspection.py

@@ -419,9 +419,12 @@ def is_simple_annotation(ann):
 
 
 def is_collection_annotation(ann):
-    return issubclass_safe(ann, _COLLECTION_TYPES)
+    if isinstance(ann, types.GenericAlias):
+        return issubclass_safe(ann.__origin__, _COLLECTION_TYPES)
+    else:
+        return issubclass_safe(ann, _COLLECTION_TYPES)
 
 
 Unset = object()
 _SIMPLE_TYPES = (int, str, float, UUID, types.NoneType, date, datetime, bool)
-_COLLECTION_TYPES = (dict, tuple, list, set)
+_COLLECTION_TYPES = (dict, tuple, list, set, defaultdict)

{djhtmx-1.1.1 → 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.1 → 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")