djhtmx 1.1.0__tar.gz → 1.1.2__tar.gz

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

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+
 ## [1.1.0] - 2025-08-15
 
 ### Changed

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: djhtmx
-Version: 1.1.0
+Version: 1.1.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
@@ -54,8 +54,33 @@ Interactive UI Components for Django using [htmx](https://htmx.org)
 
 ## Install
 
-Add `djhtmx` to your `INSTALLED_APPS` and install the Middleware as the last one
-of the list:
+```bash
+uv add djhtmx
+```
+
+or 
+
+```bash
+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
 INSTALLED_APPS = [
@@ -63,11 +88,33 @@ INSTALLED_APPS = [
     "djhtmx",
     ...
 ]
+```
+
+Install the Middleware as the last one  of the list 
 
+```python
 MIDDLEWARE = [
     ...,
     "djhtmx.middleware",
 ]
+```
+
+Add `djhtmx.context.component_repo` to the list of context processors:
+
+```python
+TEMPLATES = [
+    {
+        "BACKEND": "django.template.backends.django.DjangoTemplates",
+        "DIRS": [],
+        "APP_DIRS": True,
+        "OPTIONS": {
+            "context_processors": [
+                ...,
+                "djhtmx.context.component_repo",
+            ],
+        },
+    },
+]
 
 ```
 
@@ -83,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
@@ -97,6 +178,10 @@ 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.
 
 ```python

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

@@ -7,8 +7,33 @@ Interactive UI Components for Django using [htmx](https://htmx.org)
 
 ## Install
 
-Add `djhtmx` to your `INSTALLED_APPS` and install the Middleware as the last one
-of the list:
+```bash
+uv add djhtmx
+```
+
+or 
+
+```bash
+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
 INSTALLED_APPS = [
@@ -16,11 +41,33 @@ INSTALLED_APPS = [
     "djhtmx",
     ...
 ]
+```
+
+Install the Middleware as the last one  of the list 
 
+```python
 MIDDLEWARE = [
     ...,
     "djhtmx.middleware",
 ]
+```
+
+Add `djhtmx.context.component_repo` to the list of context processors:
+
+```python
+TEMPLATES = [
+    {
+        "BACKEND": "django.template.backends.django.DjangoTemplates",
+        "DIRS": [],
+        "APP_DIRS": True,
+        "OPTIONS": {
+            "context_processors": [
+                ...,
+                "djhtmx.context.component_repo",
+            ],
+        },
+    },
+]
 
 ```
 
@@ -36,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
@@ -50,6 +131,10 @@ 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.
 
 ```python

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

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

{djhtmx-1.1.0 → djhtmx-1.1.2}/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.0 → djhtmx-1.1.2}/src/djhtmx/utils.py

@@ -63,12 +63,9 @@ def get_instance_subscriptions(
         return {f"{prefix}.{action}" for action in actions}
 
 
-Action = t.Literal["created", "updated", "deleted"]
-
-
 def get_model_subscriptions(
     obj: type[models.Model] | models.Model,
-    actions: t.Sequence[Action | None] = (),
+    actions: t.Sequence[str | None] = (),
 ) -> set[str]:
     """Get the subscriptions to actions of the model.