djhtmx 1.1.1__py3-none-any.whl → 1.2.0__py3-none-any.whl

djhtmx/__init__.py

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

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/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/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/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/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")

{djhtmx-1.1.1.dist-info → djhtmx-1.2.0.dist-info}/METADATA

@@ -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.dist-info → djhtmx-1.2.0.dist-info}/RECORD

@@ -1,13 +1,13 @@
-djhtmx/__init__.py,sha256=xrcVGamFk6KoJqtBJy3ACEWX66jWJTfebnCGNPZcAu8,84
-djhtmx/apps.py,sha256=_Ic52zQLpbYmyuCAlgZ0lF3NDgi77sxptb31snBAN4o,268
+djhtmx/__init__.py,sha256=3QdXDcoVk5icMta3uAvAdFpaUBzAyNy162DvVsELvRk,84
+djhtmx/apps.py,sha256=hAyjzmInEstxLY9k8Qn58LvNlezgQLx5_NqyVL1WwYs,323
 djhtmx/command_queue.py,sha256=kiYbQFPyjnhMSR7KgO1Nu-lWiapnH511P2Pyg-Zrdq4,4862
 djhtmx/commands.py,sha256=UxXbARd4Teetjh_zjvAWgI2KNbvdETH-WrGf4qD9Xr8,1206
-djhtmx/component.py,sha256=viqrizs85e6zlGh3Zlf2n2HxfBg1cOaSp5deVGPRGXY,15739
+djhtmx/component.py,sha256=0Z5gAbhOg7lKXzbwDGmVJVv_IA6WYtzrWxZo_ww9CpY,15789
 djhtmx/consumer.py,sha256=kHNoXokcWaFjs5zbZAhM7Y0x7GVwwawXbxBCkP8HNA8,2839
 djhtmx/context.py,sha256=cWvz8Z0MC6x_G8sn5mvoH8Hu38qReY21_eNdThuba1A,214
 djhtmx/exceptions.py,sha256=UtyE1N-52OmzwgRM9xFxjUuhHTMDvD7Oy3rNpgthLcs,47
 djhtmx/global_events.py,sha256=bYb8WmQn_WsZ_Dadr0pGiGOPia01K-VanPpM97Lt324,342
-djhtmx/introspection.py,sha256=HAc4iRxAzEW1n0Oyb1yEW7K80lLhQhZdTHGwVOMong0,13294
+djhtmx/introspection.py,sha256=OVNaQ8r6G13HMftydfW2UVCfs2dzy34HET2Tb7bGnN4,13431
 djhtmx/json.py,sha256=7cjwWIJj7e0dk54INKYZJe6zKkIW7wlsNSlD05cbXfY,1374
 djhtmx/middleware.py,sha256=JuMtv9ZnpungTvQ1qD2Lg6LiFPB3knQlA1ERgH4iGl0,1274
 djhtmx/query.py,sha256=UyjN1jokh4wTwQJxcRwA9f-Zn-A7A4GLToeGrCnPhKA,6674
@@ -16,8 +16,8 @@ djhtmx/settings.py,sha256=ymFUMvrcXDkYU9KkhPOjRZSQMWz5GcUjlgh07x09-1s,1242
 djhtmx/testing.py,sha256=AdZKsT6sNTsyqSKx6EmfthOIHzSAPkTquheMfg9znbk,8301
 djhtmx/tracing.py,sha256=xkCXb7t_3yCj1PGzmQfHPu9sYQftDKwtALaEbFVnQ1E,1260
 djhtmx/urls.py,sha256=zWMlw_udCUWvo5DNxsvbebSNRFxy0C9ghBmRg08XlcU,3894
-djhtmx/utils.py,sha256=gjsJZrjrr7FDh-8wv9W5j3EWNlDl_Eztr5IeMvdY2BE,3617
-djhtmx/management/commands/htmx.py,sha256=EtJhQofJ4Dl3s34Uihz4WbSljzy5R6r0HXGaX4vkcDg,2011
+djhtmx/utils.py,sha256=8dzSjEk4IR8LBHg-fDR9yn1Y2IVQjpmNn9x59rK5wgM,4645
+djhtmx/management/commands/htmx.py,sha256=tEtiJn_Z6byOFzBNIzTbdluA4T5q21zFwGvJ7yt90bw,3642
 djhtmx/static/htmx/django.js,sha256=G59uwy5hA4QUcAFJv21SMxizATpNZG3KfgFlO2zXeGc,7086
 djhtmx/static/htmx/2.0.4/htmx.amd.js,sha256=Hgmm_X5zw7ek0pjBaxhzH7OHx6Xfce5UYVa9ICWlWR0,165593
 djhtmx/static/htmx/2.0.4/htmx.cjs.js,sha256=4P3vh1eGwULBCT7wsKQ2bu4HiNQ_Kmnv2fP1RQ6_QW8,165586
@@ -30,7 +30,7 @@ djhtmx/templates/htmx/headers.html,sha256=rBQTBt9rnlxE8lgxN4U7nvzQZNw4JZKS4flD1V
 djhtmx/templates/htmx/lazy.html,sha256=LfAThtKmFj-lCUZ7JWF_sC1Y6XsIpEz8A3IgWASn-J8,52
 djhtmx/templatetags/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 djhtmx/templatetags/htmx.py,sha256=HlH7_B9lJoTDoIkYPeEE55OwpBTrrCesE70j1KcRC70,8063
-djhtmx-1.1.1.dist-info/METADATA,sha256=NMrxVSCGCi-0f4X5jWgClss_sMFM_M8vZ7Yx3mipc28,28777
-djhtmx-1.1.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-djhtmx-1.1.1.dist-info/licenses/LICENSE,sha256=kCi_iSBUGsRZInQn96w7LXYzjiRjZ8FXl6vP--mFRPk,1085
-djhtmx-1.1.1.dist-info/RECORD,,
+djhtmx-1.2.0.dist-info/METADATA,sha256=YxslHSLGP3ZdSVy0gYuJZ8xLluzIce0Ne38lfpneCi8,32245
+djhtmx-1.2.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+djhtmx-1.2.0.dist-info/licenses/LICENSE,sha256=kCi_iSBUGsRZInQn96w7LXYzjiRjZ8FXl6vP--mFRPk,1085
+djhtmx-1.2.0.dist-info/RECORD,,