Merge branch 'adamghill:main' into main

Author: ntuckovic

.eslintrc.js

@@ -14,6 +14,7 @@ module.exports = {
     "import/no-unresolved": 0,
     "linebreak-style": 0,
     "comma-dangle": 0,
+    "import/extensions": ["error", "always", { ignorePackages: true }],
     "import/prefer-default-export": 0,
     "no-unused-expressions": ["error", { allowTernary: true }],
     "no-underscore-dangle": 0,

.github/workflows/js.yml

@@ -16,5 +16,10 @@ jobs:
       - name: Install node packages
         run: npm install
 
+      - name: See if unicorn.min.js is up-to-date
+        run: |
+          npm run build
+          git diff --stat --exit-code
+
       - name: Test with ava
         run: npm run-script test

.github/workflows/python.yml

@@ -31,10 +31,10 @@ jobs:
         run: poetry install
 
       - name: black check
-        run: poetry run black . --check --extend-exclude migrations
+        run: poetry run black . --check
 
-      - name: isort check
-        run: poetry run isort --settings pyproject.toml --check .
+      - name: ruff check
+        run: poetry run ruff .
 
       - name: Run all tests
         run: poetry run nox

DEVELOPING.md

@@ -30,8 +30,8 @@
 
 1. Update changelog.md
 1. Update package.json
-1. Run all build processes: `poe build`
 1. `poetry version major|minor|patch`
+1. Run all build processes: `poe build`
 1. Commit/tag/push version bump
 1. `poe publish`
 1. Make sure test package can be installed as expected (https://test.pypi.org/project/django-unicorn/)

README.md

@@ -13,7 +13,9 @@
 [![All Contributors](https://img.shields.io/badge/all_contributors-17-orange.svg?style=flat-square)](#contributors-)
 <!-- ALL-CONTRIBUTORS-BADGE - Do not remove or modify above line -->
 
-[Unicorn](https://www.django-unicorn.com) adds modern reactive component functionality to your Django templates without having to learn a new templating language or fight with complicated JavaScript frameworks. It seamlessly extends Django past its server-side framework roots without giving up all of its niceties or forcing you to re-building your application. With Django Unicorn, you can quickly and easily add rich front-end interactions to your templates, all while using the power of Django.
+[Unicorn](https://www.django-unicorn.com) adds modern reactive component functionality to your Django templates without having to learn a new templating language or fight with complicated JavaScript frameworks. It seamlessly extends Django past its server-side framework roots without giving up all of its niceties or forcing you to rebuild your application. With Django Unicorn, you can quickly and easily add rich front-end interactions to your templates, all while using the power of Django.
+
+**[https://www.django-unicorn.com](https://www.django-unicorn.com) has extensive documentation, code examples, and more!**
 
 ## ⚡ Getting started
 
@@ -61,12 +63,12 @@ urlpatterns = (
 
 ### 5. [Create a component](https://www.django-unicorn.com/docs/components/)
 
-`python manage.py startunicorn COMPONENT_NAME`
+`python manage.py startunicorn myapp COMPONENT_NAME`
 
 `Unicorn` uses the term "component" to refer to a set of interactive functionality that can be put into templates. A component consists of a Django HTML template and a Python view class which contains the backend code. After running the management command, two new files will be created:
 
-- `your_app/templates/unicorn/COMPONENT_NAME.html` (component template)
-- `your_app/components/COMPONENT_NAME.py` (component view)
+- `myapp/templates/unicorn/COMPONENT_NAME.html` (component template)
+- `myapp/components/COMPONENT_NAME.py` (component view)
 
 ### 6. Add the component to your template
 
@@ -91,7 +93,7 @@ urlpatterns = (
 The `unicorn:` attributes bind the element to data and can also trigger methods by listening for events, e.g. `click`, `input`, `keydown`, etc.
 
 ```html
-<!-- ../templates/unicorn/todo.html -->
+<!-- todo.html -->
 
 <div>
   <form unicorn:submit.prevent="add">
@@ -118,7 +120,7 @@ The `unicorn:` attributes bind the element to data and can also trigger methods
 ```
 
 ```python
-# ../components/todo.py
+# todo.py
 
 from django_unicorn.components import UnicornView
 from django import forms

conftest.py

@@ -1,6 +1,5 @@
-from django.conf import settings
-
 import pytest
+from django.conf import settings
 
 
 def pytest_configure():

django_unicorn/call_method_parser.py

@@ -6,11 +6,10 @@
 
 from django_unicorn.utils import CASTERS
 
-
 logger = logging.getLogger(__name__)
 
 
-class InvalidKwarg(Exception):
+class InvalidKwargError(Exception):
     pass
 
 
@@ -85,7 +84,7 @@ def eval_value(value):
 
 
 @lru_cache(maxsize=128, typed=True)
-def parse_kwarg(kwarg: str, raise_if_unparseable=False) -> Dict[str, Any]:
+def parse_kwarg(kwarg: str, *, raise_if_unparseable=False) -> Dict[str, Any]:
     """
     Parses a potential kwarg as a string into a dictionary.
 
@@ -121,9 +120,9 @@ def parse_kwarg(kwarg: str, raise_if_unparseable=False) -> Dict[str, Any]:
                 value = _get_expr_string(assign.value)
                 return {target.id: value}
         else:
-            raise InvalidKwarg(f"'{kwarg}' is invalid")
-    except SyntaxError:
-        raise InvalidKwarg(f"'{kwarg}' could not be parsed")
+            raise InvalidKwargError(f"'{kwarg}' is invalid")
+    except SyntaxError as e:
+        raise InvalidKwargError(f"'{kwarg}' could not be parsed") from e
 
 
 @lru_cache(maxsize=128, typed=True)

django_unicorn/components/__init__.py

@@ -1,8 +1,7 @@
-from .mixins import ModelValueMixin
-from .typing import QuerySetType
-from .unicorn_view import UnicornField, UnicornView
-from .updaters import HashUpdate, LocationUpdate, PollUpdate
-
+from django_unicorn.components.mixins import ModelValueMixin
+from django_unicorn.components.typing import QuerySetType
+from django_unicorn.components.unicorn_view import UnicornField, UnicornView
+from django_unicorn.components.updaters import HashUpdate, LocationUpdate, PollUpdate
 
 __all__ = [
     "QuerySetType",

django_unicorn/components/typing.py

@@ -2,7 +2,6 @@
 
 from django.db.models import Model, QuerySet
 
-
 M_co = TypeVar("M_co", bound=Model, covariant=True)
 
 

django_unicorn/components/unicorn_template_response.py

@@ -2,21 +2,22 @@
 import re
 from collections import deque
 
-from django.template.response import TemplateResponse
-
 import orjson
 from bs4 import BeautifulSoup
 from bs4.dammit import EntitySubstitution
 from bs4.element import Tag
 from bs4.formatter import HTMLFormatter
+from django.template.response import TemplateResponse
 
+from django_unicorn.decorators import timed
+from django_unicorn.errors import (
+    MissingComponentElementError,
+    MissingComponentViewElementError,
+    MultipleRootComponentElementError,
+    NoRootComponentElementError,
+)
 from django_unicorn.settings import get_minify_html_enabled, get_script_location
-from django_unicorn.utils import sanitize_html
-
-from ..decorators import timed
-from ..errors import MissingComponentElement, MissingComponentViewElement
-from ..utils import generate_checksum
-
+from django_unicorn.utils import generate_checksum, sanitize_html
 
 logger = logging.getLogger(__name__)
 
@@ -60,6 +61,25 @@ def is_html_well_formed(html: str) -> bool:
     return len(stack) == 0
 
 
+def assert_has_single_wrapper_element(root_element: Tag, component_name: str) -> None:
+    # Check that the root element has at least one child
+    try:
+        next(root_element.descendants)
+    except StopIteration:
+        raise NoRootComponentElementError(
+            f"The '{component_name}' component does not appear to have one root element."
+        ) from None
+
+    # Check that there is not more than one root element
+    parent_element = root_element.parent
+    tag_count = len([c for c in parent_element.children if isinstance(c, Tag)])
+
+    if tag_count > 1:
+        raise MultipleRootComponentElementError(
+            f"The '{component_name}' component appears to have multiple root elements."
+        ) from None
+
+
 class UnsortedAttributes(HTMLFormatter):
     """
     Prevent beautifulsoup from re-ordering attributes.
@@ -69,23 +89,23 @@ def __init__(self):
         super().__init__(entity_substitution=EntitySubstitution.substitute_html)
 
     def attributes(self, tag: Tag):
-        for k, v in tag.attrs.items():
-            yield k, v
+        yield from tag.attrs.items()
 
 
 class UnicornTemplateResponse(TemplateResponse):
     def __init__(
         self,
         template,
         request,
+        *,
         context=None,
         content_type=None,
         status=None,
         charset=None,
         using=None,
         component=None,
         init_js=False,
-        **kwargs,
+        **kwargs,  # noqa: ARG002
     ):
         super().__init__(
             template=template,
@@ -111,7 +131,8 @@ def render(self):
 
         if not is_html_well_formed(content):
             logger.warning(
-                f"The HTML in '{self.component.component_name}' appears to be missing a closing tag. That can potentially cause errors in Unicorn."
+                f"The HTML in '{self.component.component_name}' appears to be missing a closing tag. That can \
+potentially cause errors in Unicorn."
             )
 
         frontend_context_variables = self.component.get_frontend_context_variables()
@@ -122,13 +143,19 @@ def render(self):
         # despite https://thehftguy.com/2020/07/28/making-beautifulsoup-parsing-10-times-faster/
         soup = BeautifulSoup(content, features="html.parser")
         root_element = get_root_element(soup)
+
+        try:
+            assert_has_single_wrapper_element(root_element, self.component.component_name)
+        except (NoRootComponentElementError, MultipleRootComponentElementError) as ex:
+            logger.warning(ex)
+
         root_element["unicorn:id"] = self.component.component_id
         root_element["unicorn:name"] = self.component.component_name
         root_element["unicorn:key"] = self.component.component_key
         root_element["unicorn:checksum"] = checksum
 
-        # Generate the hash based on the rendered content (without script tag)
-        hash = generate_checksum(UnicornTemplateResponse._desoupify(soup))
+        # Generate the checksum based on the rendered content (without script tag)
+        checksum = generate_checksum(UnicornTemplateResponse._desoupify(soup))
 
         if self.init_js:
             init = {
@@ -137,11 +164,13 @@ def render(self):
                 "key": self.component.component_key,
                 "data": orjson.loads(frontend_context_variables),
                 "calls": self.component.calls,
-                "hash": hash,
+                "hash": checksum,
             }
             init = orjson.dumps(init).decode("utf-8")
             json_element_id = f"unicorn:data:{self.component.component_id}"
-            init_script = f"Unicorn.componentInit(JSON.parse(document.getElementById('{json_element_id}').textContent));"
+            init_script = (
+                f"Unicorn.componentInit(JSON.parse(document.getElementById('{json_element_id}').textContent));"
+            )
 
             json_tag = soup.new_tag("script")
             json_tag["type"] = "application/json"
@@ -165,7 +194,8 @@ def render(self):
 
                 script_tag = soup.new_tag("script")
                 script_tag["type"] = "module"
-                script_tag.string = f"if (typeof Unicorn === 'undefined') {{ console.error('Unicorn is missing. Do you need {{% load unicorn %}} or {{% unicorn_scripts %}}?') }} else {{ {init_script} }}"
+                script_tag.string = f"if (typeof Unicorn === 'undefined') {{ console.error('Unicorn is missing. Do you \
+need {{% load unicorn %}} or {{% unicorn_scripts %}}?') }} else {{ {init_script} }}"
 
                 if get_script_location() == "append":
                     root_element.append(script_tag)
@@ -213,17 +243,17 @@ def get_root_element(soup: BeautifulSoup) -> Tag:
     for element in soup.contents:
         if isinstance(element, Tag) and element.name:
             if element.name == "html":
-                view_element = element.find_next(
-                    attrs={"unicorn:view": True}
-                ) or element.find_next(attrs={"u:view": True})
+                view_element = element.find_next(attrs={"unicorn:view": True}) or element.find_next(
+                    attrs={"u:view": True}
+                )
 
                 if not view_element:
-                    raise MissingComponentViewElement(
+                    raise MissingComponentViewElementError(
                         "An element with an `unicorn:view` attribute is required for a direct view"
                     )
 
                 return view_element
 
             return element
 
-    raise MissingComponentElement("No root element for the component was found")
+    raise MissingComponentElementError("No root element for the component was found")