Remove automatic extension dependencies

Author: matthiask

CHANGELOG.rst

@@ -4,6 +4,14 @@ Change log
 Next version
 ~~~~~~~~~~~~
 
+- **Backwards incompatible**: Removed the automatic dependency management of
+  some extensions. For example, adding ``BulletList`` would automatically add
+  the ``ListItem`` extension. This didn't work nicely when replacing the
+  ``ListItem`` extension with a hypothetical ``ExtendedListItem`` extension
+  because then the configuration would contain several list item nodes. The
+  config resolver tries detecting invalid configurations and warns if it
+  suspects missing extensions, but that's not completely watertight. The
+  warnings will be removed after a few releases.
 - Added a ``NodeClass`` extension for applying CSS classes to nodes.
 
 

django_prose_editor/config.py

@@ -5,6 +5,7 @@
 corresponding sanitization rules for server-side HTML cleaning.
 """
 
+import warnings
 from typing import Any
 
 from django.conf import settings
@@ -246,8 +247,9 @@ def process_node_class(config, shared_config):
     "Placeholder": html_tags([]),
 }
 
-# Automatic dependencies (extensions that require other extensions)
-EXTENSION_DEPENDENCIES = {
+# DEPRECATED: This dictionary is no longer used for automatic dependency management
+# but kept for backwards compatibility checking
+LEGACY_EXTENSION_DEPENDENCIES = {
     "BulletList": ["ListItem"],
     "OrderedList": ["ListItem"],
     "Table": ["TableRow", "TableHeader", "TableCell"],
@@ -260,7 +262,7 @@ def process_node_class(config, shared_config):
 
 def expand_extensions(extensions: dict[str, Any]) -> dict[str, Any]:
     """
-    Expand extension configuration by applying defaults and resolving dependencies.
+    Expand extension configuration by applying defaults.
 
     Args:
         extensions: Dictionary of extension configurations
@@ -292,16 +294,52 @@ def expand_extensions(extensions: dict[str, Any]) -> dict[str, Any]:
         if config is not False
     }
 
-    # Resolve dependencies
-    for extension, deps in EXTENSION_DEPENDENCIES.items():
-        if extension in expanded:
-            for dep in deps:
-                if dep not in expanded:
-                    expanded[dep] = True
+    # Check for legacy dependency issues and warn
+    dependency_warnings = check_legacy_dependencies(extensions)
+    for warning_msg in dependency_warnings:
+        warnings.warn(
+            warning_msg,
+            UserWarning,
+            stacklevel=3,  # Point to the calling code, not this function
+        )
 
     return expanded
 
 
+def check_legacy_dependencies(extensions: dict[str, Any]) -> list[str]:
+    """
+    Check if the extension configuration relies on legacy automatic dependency management.
+
+    This function identifies configurations that would have worked with automatic
+    dependency resolution but may now be incomplete.
+
+    Args:
+        extensions: Dictionary of extension configurations (raw, not expanded)
+
+    Returns:
+        List of warning messages about missing dependencies
+    """
+    warnings = []
+
+    # Filter enabled extensions (don't call expand_extensions to avoid recursion)
+    enabled_extensions = {
+        extension: config
+        for extension, config in extensions.items()
+        if config is not False
+    }
+
+    for extension, deps in LEGACY_EXTENSION_DEPENDENCIES.items():
+        if extension in enabled_extensions:
+            for dep in deps:
+                if dep not in enabled_extensions:
+                    warnings.append(
+                        f"Extension '{extension}' typically requires '{dep}' to function properly. "
+                        f"Consider adding '{dep}': True to your configuration."
+                    )
+
+    return warnings
+
+
 def js_from_extensions(
     extensions: dict[str, Any],
 ) -> list[str]:

tests/README.md

@@ -0,0 +1,20 @@
+# Testing
+
+## Running Tests
+
+To run all tests:
+```bash
+tox -e py313-dj52
+```
+
+To run specific test files:
+```bash
+tox -e py313-dj52 -- tests/testapp/test_config.py -v
+```
+
+To run specific test methods:
+```bash
+tox -e py313-dj52 -- tests/testapp/test_config.py::ConfigFunctionsTestCase::test_expand_extensions_without_auto_dependencies -v
+```
+
+You can pass any pytest arguments after the double dash (`--`).

tests/testapp/models.py

@@ -29,12 +29,16 @@ class TableProseEditorModel(models.Model):
                 "HorizontalRule",
                 "Italic",
                 "Link",
+                "ListItem",
                 "OrderedList",
                 "Strike",
                 "Subscript",
                 "Superscript",
                 "Underline",
                 "Table",
+                "TableRow",
+                "TableHeader",
+                "TableCell",
             ],
             "history": True,
             "html": True,
@@ -52,7 +56,10 @@ class ConfigurableProseEditorModel(models.Model):
             "extensions": {
                 "Bold": True,
                 "Italic": True,
-                "Table": True,  # This should automatically include TableRow, TableHeader, TableCell
+                "Table": True,
+                "TableRow": True,
+                "TableHeader": True,
+                "TableCell": True,
                 "Heading": {"levels": [1, 2, 3]},  # Limit to h1, h2, h3
                 "BlueBold": True,
                 "HTML": True,

tests/testapp/test_config.py

@@ -5,6 +5,7 @@
 
 from django_prose_editor.config import (
     allowlist_from_extensions,
+    check_legacy_dependencies,
     expand_extensions,
     html_tags,
     js_from_extensions,
@@ -132,8 +133,8 @@ def test_js_from_extensions_with_invalid_extension(self):
         assert isinstance(js_modules, list)
         assert js_modules == []
 
-    def test_expand_extensions_with_dependencies(self):
-        """Test that expand_extensions correctly adds dependent extensions."""
+    def test_expand_extensions_without_auto_dependencies(self):
+        """Test that expand_extensions no longer automatically adds dependent extensions."""
         extensions = {
             "Bold": True,
             "Table": True,
@@ -147,17 +148,59 @@ def test_expand_extensions_with_dependencies(self):
         assert "Table" in expanded
         assert "Figure" in expanded
 
-        # Dependencies should be added
-        assert "TableRow" in expanded
-        assert "TableHeader" in expanded
-        assert "TableCell" in expanded
-        assert "Caption" in expanded
-        assert "Image" in expanded
+        # Dependencies should NOT be automatically added anymore
+        assert "TableRow" not in expanded
+        assert "TableHeader" not in expanded
+        assert "TableCell" not in expanded
+        assert "Caption" not in expanded
+        assert "Image" not in expanded
 
         # Core extensions should always be included
         assert "Document" in expanded
         assert "Paragraph" in expanded
-        assert "Text" in expanded
+
+    def test_check_legacy_dependencies(self):
+        """Test that check_legacy_dependencies correctly identifies missing dependencies."""
+        extensions = {
+            "Bold": True,
+            "BulletList": True,
+            "Table": True,
+        }
+
+        warnings = check_legacy_dependencies(extensions)
+
+        # Should warn about missing ListItem for BulletList
+        assert any(
+            "BulletList" in warning and "ListItem" in warning for warning in warnings
+        )
+
+        # Should warn about missing Table dependencies
+        assert any("Table" in warning and "TableRow" in warning for warning in warnings)
+        assert any(
+            "Table" in warning and "TableHeader" in warning for warning in warnings
+        )
+        assert any(
+            "Table" in warning and "TableCell" in warning for warning in warnings
+        )
+
+        # Should not warn about Bold (no dependencies)
+        assert not any("Bold" in warning for warning in warnings)
+
+    def test_check_legacy_dependencies_with_explicit_deps(self):
+        """Test that no warnings are generated when dependencies are explicitly included."""
+        extensions = {
+            "BulletList": True,
+            "ListItem": True,
+            "Table": True,
+            "TableRow": True,
+            "TableHeader": True,
+            "TableCell": True,
+        }
+
+        warnings = check_legacy_dependencies(extensions)
+
+        # Should have no warnings since all dependencies are explicitly included
+        assert len(warnings) == 0
 
     def test_disabled_extensions(self):
         """Test that disabled extensions are properly handled."""

tests/testapp/test_configurable.py

@@ -11,8 +11,8 @@
 class ConfigurableFormTestCase(TestCase):
     """Tests for the configurable field form rendering."""
 
-    def test_dependencies_expanded(self):
-        """Test that all dependencies are properly expanded in raw_extensions."""
+    def test_extensions_explicit_configuration(self):
+        """Test that extensions are configured as explicitly specified."""
 
         class TestForm(ModelForm):
             class Meta:
@@ -27,15 +27,18 @@ class Meta:
             context["widget"]["attrs"]["data-django-prose-editor-configurable"]
         )
 
-        # The original extensions only had Bold, Italic, and Table
+        # The original extensions should be there
         assert "Bold" in config["extensions"]
         assert "Italic" in config["extensions"]
         assert "Table" in config["extensions"]
 
         # The custom BlueBold extension should also be included
         assert "BlueBold" in config["extensions"]
 
-        # The following should be included as dependencies
+        # ListItem should be there because it's explicitly configured
+        assert "ListItem" in config["extensions"]
+
+        # Table dependencies are now explicitly configured in the model
         assert "TableRow" in config["extensions"]
         assert "TableHeader" in config["extensions"]
         assert "TableCell" in config["extensions"]
@@ -77,9 +80,7 @@ class Meta:
             "NoSpellCheck": True,
             # Enable history by default unless explicitly disabled
             "History": True,
-            "TableRow": True,
-            "TableCell": True,
-            "TableHeader": True,
+            # No automatic dependencies are added
         }
 
     def test_sanitization_works(self):

tests/testapp/test_prose_editor_e2e.py

@@ -599,7 +599,6 @@ def test_nodeclass_textclass(live_server, page):
     editor_container = page.locator(".prose-editor")
     expect(editor_container).to_be_visible()
 
-    page.get_by_role("paragraph").click()
     page.get_by_role("textbox").fill("Blubbering Hello World")
     page.locator("div").filter(has_text=re.compile(r"^default$")).click()
     page.locator("div").filter(has_text=re.compile(r"^Block style$")).click()