feat: allow Django Form/ModelForm instances to be passed as template kwargs without serialization or pickling errors

Author: JohananOppongAmoateng

docs/source/views.md

@@ -195,6 +195,45 @@ class HelloKwargView(UnicornView):
       assert self.component_kwargs["hello"] == "World"
 ```
 
+### Passing a Django Form
+
+A Django `Form` (or `ModelForm`) instance can be passed directly from a template into a unicorn component as a keyword argument. The form will be available in the component's template context for rendering, but it is automatically excluded from the JSON state sent to the browser (since forms cannot be serialized to JSON).
+
+```html
+<!-- index.html -->
+{% unicorn 'my-form-component' form=my_django_form %}
+```
+
+```python
+# my_form_component.py
+from django_unicorn.components import UnicornView
+
+class MyFormComponentView(UnicornView):
+    form = None  # will hold the passed-in form instance
+
+    def mount(self):
+        # self.form is available here on the initial render
+        pass
+```
+
+```html
+<!-- unicorn/my-form-component.html -->
+<div>
+  <form method="POST">
+    {% csrf_token %}
+    {{ form.as_p }}
+    <button unicorn:click="submit">Submit</button>
+  </form>
+</div>
+```
+
+```{note}
+Because forms cannot be pickled, `self.form` will be `None` on subsequent AJAX
+interactions (after the initial page load). If you need to process submitted form
+data reactively, declare a `form_class` on the component and use
+[component validation](validation.md) instead.
+```
+
 ### request
 
 The current `request`.
@@ -392,7 +431,12 @@ class HelloStateView(UnicornView):
 
 ### javascript_exclude
 
-To allow an attribute to be included in the the context to be used by a Django template, but not exposed to JavaScript, add it to the `Meta` class's `javascript_exclude` tuple.
+To allow an attribute to be included in the context to be used by a Django template, but not exposed to JavaScript, add it to the `Meta` class's `javascript_exclude` tuple.
+
+```{note}
+Django `Form` and `ModelForm` instances are **automatically** excluded from the
+JavaScript context — you do not need to add them to `javascript_exclude`.
+```
 
 ```html
 <!-- hello-state.html -->
@@ -465,4 +509,12 @@ Do not store unpickleable objects (e.g. generators) on the component instance.
 
 If you need to use an unpickleable object, either convert it to a pickleable type (e.g. convert a generator to a list) or re-initialize it within the method that needs it without storing it on `self`.
 
+```{note}
+Django `Form` and `ModelForm` instances are handled automatically — they are stripped
+from the component before pickling and restored afterwards, so passing a form as a
+template kwarg (see [Passing a Django Form](#passing-a-django-form)) will not cause
+pickling errors. The form will be `None` after a cache restore (i.e. on subsequent
+AJAX requests).
+```
+
 

src/django_unicorn/cacher.py

@@ -6,6 +6,7 @@
     from django_unicorn.components.unicorn_view import UnicornView
 
 from django.core.cache import caches
+from django.forms import BaseForm
 from django.http import HttpRequest
 
 from django_unicorn.errors import UnicornCacheError
@@ -66,13 +67,22 @@ def __enter__(self):
             if not isinstance(component.template_name, str):
                 component.template_name = None
 
+            # Strip Django Form instances before pickling — forms contain unpicklable
+            # references (e.g. lazily-bound validators) and are only needed for rendering.
+            form_attributes: dict = {}
+            for attr_name, attr_val in list(vars(component).items()):
+                if isinstance(attr_val, BaseForm):
+                    form_attributes[attr_name] = attr_val
+                    setattr(component, attr_name, None)
+
             self._state[component.component_id] = (
                 component,
                 request,
                 extra_context,
                 component.parent,
                 component.children.copy(),
                 template_name,
+                form_attributes,
             )
 
             if component.parent:
@@ -104,12 +114,16 @@ def __enter__(self):
         return self
 
     def __exit__(self, *args):
-        for component, request, extra_context, parent, children, template_name in self._state.values():
+        for component, request, extra_context, parent, children, template_name, form_attributes in self._state.values():
             component.request = request
             component.parent = parent
             component.children = children
             component.template_name = template_name
 
+            # Restore any form instances that were stripped before pickling
+            for attr_name, attr_val in form_attributes.items():
+                setattr(component, attr_name, attr_val)
+
             # Re-create the template_name `Template` object if it is `None`
             if component.template_name is None and hasattr(component, "template_html"):
                 component.template_name = create_template(component.template_html)

src/django_unicorn/components/unicorn_view.py

@@ -11,6 +11,7 @@
 from django.apps import apps as django_apps_module
 from django.core.exceptions import NON_FIELD_ERRORS
 from django.db.models import Model
+from django.forms import BaseForm
 from django.forms.widgets import CheckboxInput, Select
 from django.http import HttpRequest, HttpResponse, HttpResponseRedirect
 from django.utils.decorators import classonlymethod
@@ -520,6 +521,12 @@ def get_frontend_context_variables(self) -> str:
 
                         del frontend_context_variables[field_name]
 
+        # Auto-exclude Django Form instances (they can't be serialized to JSON).
+        # This lets forms be passed as template kwargs for rendering without causing errors.
+        for field_name in list(frontend_context_variables.keys()):
+            if isinstance(frontend_context_variables[field_name], BaseForm):
+                del frontend_context_variables[field_name]
+
         # Add cleaned values to `frontend_content_variables` based on the widget in form's fields
         form = self._get_form(attributes)
 

tests/components/test_component.py

@@ -2,6 +2,7 @@
 
 import orjson
 import pytest
+from django import forms
 from tests.views.fake_components import (
     FakeAuthenticationComponent,
     FakeValidationComponent,
@@ -345,3 +346,58 @@ def test_get_frontend_context_variables_authentication_form(component):
     )
 
     component.get_frontend_context_variables()
+
+
+class SimpleForm(forms.Form):
+    name = forms.CharField()
+
+
+def test_get_frontend_context_variables_excludes_form_instance():
+    """
+    A Django Form instance passed as a component attribute should be automatically
+    excluded from the serialized frontend context variables (issue #165).
+    """
+
+    class ComponentWithForm(UnicornView):
+        name = "test"
+        form = None
+
+        def __init__(self, *args, **kwargs):
+            super().__init__(*args, **kwargs)
+
+    component = ComponentWithForm(
+        component_id="test_excludes_form_instance",
+        component_name="example",
+    )
+    component.form = SimpleForm()
+
+    frontend_context_variables = component.get_frontend_context_variables()
+    frontend_context_variables_dict = orjson.loads(frontend_context_variables)
+
+    # The form instance must not be included in the JSON (not serialisable)
+    assert "form" not in frontend_context_variables_dict
+    # Other public attributes are still present
+    assert "name" in frontend_context_variables_dict
+
+
+def test_get_frontend_context_variables_form_available_in_context():
+    """
+    Even though the form is excluded from the JSON frontend context, it should still
+    be accessible in the template context via get_context_data().
+    """
+
+    class ComponentWithForm(UnicornView):
+        form = None
+
+        def __init__(self, *args, **kwargs):
+            super().__init__(*args, **kwargs)
+
+    component = ComponentWithForm(
+        component_id="test_form_in_context_data",
+        component_name="example",
+    )
+    form_instance = SimpleForm()
+    component.form = form_instance
+
+    context = component.get_context_data()
+    assert context["form"] is form_instance

tests/test_cacher.py

@@ -1,6 +1,7 @@
 from unittest.mock import MagicMock, patch
 
 import pytest
+from django import forms
 
 from django_unicorn.cacher import (
     CacheableComponent,
@@ -292,3 +293,48 @@ def test_cacheable_component_restores_nested_state_on_pickle_failure():
     assert not isinstance(parent.parent, PointerUnicornView)
     assert child in parent.children
     assert parent in grandparent.children
+
+
+class SimpleForm(forms.Form):
+    name = forms.CharField()
+
+
+class ComponentWithForm(UnicornView):
+    """Component whose instance attributes include a Django Form."""
+
+    def __init__(self, *args, **kwargs):
+        self.form = kwargs.pop("form", None)
+        super().__init__(*args, **kwargs)
+
+
+def test_cacheable_component_strips_form_before_pickling():
+    """Form instances are stripped before pickling so the component can be cached."""
+    form_instance = SimpleForm()
+    component = ComponentWithForm(
+        component_id="test_form_strip",
+        component_name="with-form",
+        form=form_instance,
+    )
+    assert component.form is form_instance
+
+    with CacheableComponent(component):
+        # Inside context: form should be stripped (set to None) so pickle can succeed
+        assert component.form is None
+
+    # After context: form should be restored
+    assert component.form is form_instance
+
+
+def test_cacheable_component_restores_form_after_context():
+    """Form instances are fully restored on CacheableComponent.__exit__."""
+    form_instance = SimpleForm(data={"name": "Alice"})
+    component = ComponentWithForm(
+        component_id="test_form_restore",
+        component_name="with-form",
+        form=form_instance,
+    )
+
+    with CacheableComponent(component):
+        pass
+
+    assert component.form is form_instance