Add state serialization documentation and custom reducer feature

- Introduce a new `state_serialization.md` file detailing the state serialization process for livecomponents.
- Document the `livecomponents_reducer` decorator to enforce custom pickling for dynamically created classes.

Author: imankulov

CHANGELOG.md

@@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## UNRELEASED
 
 - Updated livecomponent documentation. Added simple counter example.
+- Added and documented livecomponents_reducer decorator to force the use of a custom reducer for dynamically created classes.
 
 ## 1.15.0 (2025-04-08)
 

docs/livecomponents.md

@@ -166,22 +166,6 @@ class Alert(LiveComponent):
 
 Component states don't need to be stored if components are not expected to be re-rendered independently, and only as part of the parent component. For example, components for buttons are rarely re-rendered independently, so you can get away without the state model.
 
-## Serializing Component State
-
-When the page is rendered for the first time, a new session is created, and each component is initialized with its state by calling the `init_state()` method.
-
-The state is then serialized and stored in the session store, and as long as the session is the same (in other words, while the page is not reloaded), the state is reused.
-
-The state is serialized using the `StateSerializer` class and saved in Redis. By default, the `PickleStateSerializer` is used. The serializer uses a custom pickler and is optimized to effectively store the most common types of data used in a Django app. More specifically:
-
-- When serializing a Django model, only the model's name and primary key are stored. The serializer takes advantage of the persistent_id/persistent_load pickle mechanism.
-- When serializing a Pydantic model, only the model's name and the values of the fields are stored.
-- When serializing a Django form, only the form's class name, as well as initial data and data, are stored.
-
-!!! note "Session Storage Size Warning"
-
-    Livecomponents use Redis as the session store. Remember that a new session is created for each page load of every client, and stored there for 24 hours by default. This means you should keep the state small.
-
 ## Stateless components
 
 If the component doesn't store any state, you can inherit from the StatelessLiveComponent class. You may find this helpful for rendering a hierarchy of components where the shared state is stored in the root components.

docs/state_serialization.md

@@ -0,0 +1,77 @@
+# State Serialization
+
+When the page is rendered for the first time, a new session is created, and each component is initialized with its state by calling the `init_state()` method.
+
+The state is then serialized and stored in the session store. As long as the session remains the same (in other words, while the page is not reloaded), the state is reused.
+
+The state is serialized using the `StateSerializer` class and saved in Redis.
+
+> [!NOTE]
+>
+> **Session Storage Size Warning.**
+> Livecomponents use Redis as the session store. Keep in mind that a new session is created for each page load for every client and is stored there for 24 hours by default. This means you should keep the state compact.
+
+## PickleStateSerializer
+
+To convert the object to a string, the `PickleStateSerializer` is used.
+
+The serializer employs a custom pickler and is optimized to effectively store the most common types of data used in a Django app. More specifically:
+
+- When serializing a Django model, only the model's name and primary key are stored. The serializer utilizes the persistent_id/persistent_load pickle mechanism.
+- When serializing a Pydantic model, only the model's name and the values of the fields are stored.
+- When serializing a Django form, only the form's class name, along with initial data and data, are stored.
+
+## Serializing Dynamically Created Classes
+
+> [!WARNING]
+> This section is an advanced topic that most users do not need. It's only necessary if you create model forms dynamically.
+
+By default, pickle does not support serializing classes created dynamically (that is, classes defined as a result of a function call). Creating classes from functions is uncommon, but in some rare cases, you may want to do this, for example, when creating Django model forms dynamically.
+
+If you attempt to serialize a dynamically created class, you will encounter an error like this:
+
+```
+AttributeError: Can't pickle local object 'dynamic_user_form.<locals>.DynamicUserForm'
+```
+
+The common solution for serializing dynamically created classes is to use a custom reducer by overriding the `__reduce__` method (see [Python docs](https://docs.python.org/3/library/pickle.html#object.__reduce__)). However, since `PickleStateSerializer` overrides the reducer for certain classes (specifically, for Django forms, templates, and models), your custom reducer will not be called for them.
+
+If you want to ensure the use of your custom reducer, you must decorate it with the `livecomponents_reducer` decorator.
+
+Here's the complete example:
+
+```python
+from django.forms import ModelForm
+from django.contrib.auth.models import User
+
+from livecomponents.manager.serializers import livecomponents_reducer
+
+
+def dynamic_user_form(form_fields: list[str]):
+    """Dynamically create a ModelForm for the User model with specified fields."""
+
+    class DynamicUserForm(ModelForm):
+        class Meta:
+            model = User
+            fields = form_fields
+
+        @livecomponents_reducer  # <--- This is the key!
+        def __reduce__(self):
+            data = self.data if self.is_bound else None
+            constructor_kwargs = {
+                "initial": self.initial,
+                "data": data,
+            }
+            if hasattr(self, "instance"):
+                constructor_kwargs["instance"] = self.instance
+            return restore_dynamic_user_form, (form_fields, constructor_kwargs)
+
+    return DynamicUserForm
+
+
+def restore_dynamic_user_form(form_fields: list[str], constructor_kwargs: dict):
+    """Restore the dynamic User form with specified fields."""
+    instance = dynamic_user_form(form_fields)(**constructor_kwargs)
+    instance.full_clean()
+    return instance
+```

livecomponents/manager/serializers.py

@@ -2,6 +2,7 @@
 import io
 import pickle
 import pickletools
+from collections.abc import Callable
 from typing import Any
 
 from django.apps import apps
@@ -50,6 +51,10 @@ class LivecomponentsPickler(pickle.Pickler):
     """
 
     def reducer_override(self, obj):
+        if has_livecomponent_reducer(obj):
+            logger.debug("Custom pickling: using custom reducer for %s", obj.__class__)
+            return NotImplemented
+
         if isinstance(obj, DjangoTemplates):
             return pickle_django_templates(obj)
         if isinstance(obj, BaseForm):
@@ -180,3 +185,23 @@ def pickle_django_model(instance: Model):
 def unpickle_django_model(cls, field_data: dict):
     logger.debug("Custom unpickling: Django model: class=%s", cls.__name__)
     return cls(**field_data)
+
+
+def livecomponents_reducer(func: Callable) -> Callable:
+    """Mark that the reducer as to be used for pickling with LivecomponentsPickler.
+
+    The decorator has to be applied to the `__reduce__` method of a class when we want
+    to enforce its use even for the objects, for which LivecomponentsPickler
+    defines a custom reducer.
+
+    See docs/state_serialization.md for more details.
+    """
+    func._livecomponents_reducer = True  # type: ignore
+    return func
+
+
+def has_livecomponent_reducer(obj: Any) -> bool:
+    """Check if the object has a custom reducer for LivecomponentsPickler."""
+    return hasattr(obj, "__reduce__") and getattr(
+        obj.__reduce__, "_livecomponents_reducer", False
+    )

mkdocs.yml

@@ -35,6 +35,7 @@ nav:
   - Advanced:
     - context.md
     - templates.md
+    - state_serialization.md
     - component_ids.md
   - About:
       - Changelog: https://github.com/om-proptech/livecomponents/blob/main/CHANGELOG.md

tests/test_serializers.py

@@ -8,7 +8,10 @@
 from django.forms import ModelForm
 from pydantic import BaseModel
 
-from livecomponents.manager.serializers import PickleStateSerializer
+from livecomponents.manager.serializers import (
+    PickleStateSerializer,
+    livecomponents_reducer,
+)
 
 
 class MyModel(BaseModel):
@@ -29,6 +32,35 @@ class Meta:
         fields = ["username", "email"]
 
 
+def dynamic_user_form(form_fields: list[str]):
+    """Dynamically create a ModelForm for the User model with specified fields."""
+
+    class DynamicUserForm(ModelForm):
+        class Meta:
+            model = User
+            fields = form_fields
+
+        @livecomponents_reducer
+        def __reduce__(self):
+            data = self.data if self.is_bound else None
+            constructor_kwargs = {
+                "initial": self.initial,
+                "data": data,
+            }
+            if hasattr(self, "instance"):
+                constructor_kwargs["instance"] = self.instance
+            return restore_dynamic_user_form, (form_fields, constructor_kwargs)
+
+    return DynamicUserForm
+
+
+def restore_dynamic_user_form(form_fields: list[str], constructor_kwargs: dict):
+    """Restore the dynamic User form with specified fields."""
+    instance = dynamic_user_form(form_fields)(**constructor_kwargs)
+    instance.full_clean()
+    return instance
+
+
 @pytest.mark.parametrize(
     "obj, expected_arg",
     [
@@ -127,6 +159,14 @@ def test_model_form_serialization(admin_user):
     assert deserialized.instance == admin_user
 
 
+@pytest.mark.django_db
+def test_dynamic_model_with_custom_reducer_serialization(admin_user):
+    form = dynamic_user_form(form_fields=["username", "email"])(instance=admin_user)
+    deserialized = reserialize(form)
+    assert deserialized.fields.keys() == {"username", "email"}
+    assert deserialized.instance == admin_user
+
+
 def test_model_form_serialization_unsaved_instance():
     form = MyModelForm()
     form.instance.username = "foo"