use_query and use_mutation

.github/workflows/publish-docs.yml

@@ -7,8 +7,10 @@ jobs:
   deploy:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-python@v2
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v4
         with:
           python-version: 3.x
       - run: pip install -r requirements/build-docs.txt

.github/workflows/publish-py.yml

@@ -11,15 +11,15 @@ jobs:
   release-package:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-node@v2-beta
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
         with:
           node-version: "14.x"
       - name: Set up Python
         uses: actions/setup-python@v1
         with:
           python-version: "3.x"
-      - name: Install latest NPM
+      - name: Install NPM
         run: |
           npm install -g npm@7.22.0
           npm --version

.github/workflows/test-docs.yml

@@ -14,9 +14,12 @@ jobs:
   docs:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-python@v2
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v4
         with:
           python-version: 3.x
       - run: pip install -r requirements/build-docs.txt
+      - run: linkcheckMarkdown docs/ -v -r
       - run: mkdocs build --verbose

.github/workflows/test-src.yml

@@ -17,13 +17,13 @@ jobs:
       matrix:
         python-version: ["3.8", "3.9", "3.10"]
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - uses: nanasess/setup-chromedriver@master
-      - uses: actions/setup-node@v2-beta
+      - uses: actions/setup-node@v3
         with:
           node-version: "14"
       - name: Use Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install Python Dependencies
@@ -32,4 +32,4 @@ jobs:
         run: |
           npm install -g npm@latest
           npm --version
-          nox -s test -- --headless
+          nox -s test

CHANGELOG.md

@@ -25,6 +25,8 @@ Using the following categories, list your changes in this order:
 ### Added
 
 -   `auth_required` decorator to prevent your components from rendered to unauthenticated users.
+-   `use_query` hook for fetching database values.
+-   `use_mutation` hook for modifying database values.
 
 ## [1.1.0] - 2022-07-01
 

docs/features/decorators.md

@@ -42,7 +42,6 @@ def my_component():
 
     ```python title="components.py"
     from django_idom.decorators import auth_required
-    from django_idom.hooks import use_websocket
     from idom import component, html
 
     @component

docs/features/hooks.md

@@ -2,6 +2,163 @@
 
     Check out the [IDOM Core docs](https://idom-docs.herokuapp.com/docs/reference/hooks-api.html?highlight=hooks) on hooks!
 
+## Use Query
+
+The `use_query` hook is used fetch Django ORM queries.
+
+=== "components.py"
+
+    ```python
+    from example_project.my_app.models import TodoItem
+    from idom import component, html
+    from django_idom.hooks import use_query
+
+    def get_items():
+        return TodoItem.objects.all()
+
+    @component
+    def todo_list():
+        item_query = use_query(get_items)
+
+        if item_query.loading:
+            rendered_items = html.h2("Loading...")
+        elif item_query.error:
+            rendered_items = html.h2("Error when loading!")
+        else:
+            rendered_items = html.ul(html.li(item, key=item) for item in item_query.data)
+
+        return rendered_items
+    ```
+
+=== "models.py"
+
+    ```python
+    from django.db import models
+
+    class TodoItem(models.Model):
+        text = models.CharField(max_length=255)
+    ```
+
+??? question "Can I make ORM calls without hooks?"
+
+    Due to Django's ORM design, database queries must be deferred using hooks. Otherwise, you will see a `SynchronousOnlyOperation` exception.
+
+    This may be resolved in a future version of Django with a natively asynchronous ORM.
+
+??? question "What is an "ORM"?"
+
+    A Python **Object Relational Mapper** is an API for your code to access a database.
+
+    See the [Django ORM documentation](https://docs.djangoproject.com/en/dev/topics/db/queries/) for more information.
+
+## Use Mutation
+
+The `use_mutation` hook is used to modify Django ORM objects.
+
+=== "components.py"
+
+    ```python
+    from example_project.my_app.models import TodoItem
+    from idom import component, html
+    from django_idom.hooks import use_mutation
+
+    def add_item(text: str):
+        TodoItem(text=text).save()
+
+    @component
+    def todo_list():
+        item_mutation = use_mutation(add_item)
+
+        if item_mutation.loading:
+            mutation_status = html.h2("Adding...")
+        elif item_mutation.error:
+            mutation_status = html.h2("Error when adding!")
+        else:
+            mutation_status = ""
+
+        def submit_event(event):
+            if event["key"] == "Enter":
+                item_mutation.execute(text=event["target"]["value"])
+
+        return html.div(
+            html.label("Add an item:"),
+            html.input({"type": "text", "onKeyDown": submit_event}),
+            mutation_status,
+        )
+    ```
+
+=== "models.py"
+
+    ```python
+    from django.db import models
+
+    class TodoItem(models.Model):
+        text = models.CharField(max_length=255)
+    ```
+
+??? question "Can `use_mutation` trigger a refetch of `use_query`?"
+
+    Yes, `use_mutation` can queue a refetch of a `use_query` via the `refetch=...` argument.
+
+    The example below is a merge of the `use_query` and `use_mutation` examples above with the addition of a `refetch` argument on `use_mutation`.
+
+    Please note that any `use_query` hooks that use `get_items` will be refetched upon a successful mutation.
+
+    ```python title="components.py"
+    from example_project.my_app.models import TodoItem
+    from idom import component, html
+    from django_idom.hooks import use_mutation
+
+    def get_items():
+        return TodoItem.objects.all()
+
+    def add_item(text: str):
+        TodoItem(text=text).save()
+
+    @component
+    def todo_list():
+        item_query = use_query(get_items)
+        if item_query.loading:
+            rendered_items = html.h2("Loading...")
+        elif item_query.error:
+            rendered_items = html.h2("Error when loading!")
+        else:
+            rendered_items = html.ul(html.li(item, key=item) for item in item_query.data)
+
+        item_mutation = use_mutation(add_item, refetch=get_items)
+        if item_mutation.loading:
+            mutation_status = html.h2("Adding...")
+        elif item_mutation.error:
+            mutation_status = html.h2("Error when adding!")
+        else:
+            mutation_status = ""
+
+        def submit_event(event):
+            if event["key"] == "Enter":
+                item_mutation.execute(text=event["target"]["value"])
+
+        return html.div(
+            html.label("Add an item:"),
+            html.input({"type": "text", "onKeyDown": submit_event}),
+            mutation_status,
+            rendered_items,
+        )
+    ```
+
+??? question "Can I make ORM calls without hooks?"
+
+    Due to Django's ORM design, database queries must be deferred using hooks. Otherwise, you will see a `SynchronousOnlyOperation` exception.
+
+    This may be resolved in a future version of Django with a natively asynchronous ORM.
+
+    However, even when resolved it is best practice to perform ORM queries within the `use_query` in order to handle `loading` and `error` states.
+
+??? question "What is an "ORM"?"
+
+    A Python **Object Relational Mapper** is an API for your code to access a database.
+
+    See the [Django ORM documentation](https://docs.djangoproject.com/en/dev/topics/db/queries/) for more information.
+
 ## Use Websocket
 
 You can fetch the Django Channels websocket at any time by using `use_websocket`.

mkdocs.yml

@@ -12,7 +12,6 @@ nav:
           - Components: features/components.md
           - Hooks: features/hooks.md
           - Decorators: features/decorators.md
-          - ORM: features/orm.md
           - Template Tag: features/templatetag.md
           - Settings: features/settings.md
     - Contribute:
@@ -52,6 +51,8 @@ markdown_extensions:
     - pymdownx.emoji:
           emoji_index: !!python/name:materialx.emoji.twemoji
           emoji_generator: !!python/name:materialx.emoji.to_svg
+    - pymdownx.tabbed:
+          alternate_style: true
     - pymdownx.highlight
     - pymdownx.superfences
     - pymdownx.details

noxfile.py

@@ -51,40 +51,40 @@ def test_suite(session: Session) -> None:
     session.env["IDOM_DEBUG_MODE"] = "1"
 
     posargs = session.posargs[:]
-    if "--headless" in posargs:
-        posargs.remove("--headless")
-        session.env["SELENIUM_HEADLESS"] = "1"
+    if "--headed" in posargs:
+        posargs.remove("--headed")
+        session.env["PLAYWRIGHT_HEADED"] = "1"
 
     if "--no-debug-mode" not in posargs:
         posargs.append("--debug-mode")
 
+    session.run("playwright", "install", "chromium")
     session.run("python", "manage.py", "test", *posargs)
 
 
 @nox.session
 def test_types(session: Session) -> None:
     install_requirements_file(session, "check-types")
     install_requirements_file(session, "pkg-deps")
-    session.run("mypy", "--show-error-codes", "src/django_idom", "tests/test_app")
+    session.run("mypy", "--show-error-codes", "src/django_idom")
 
 
 @nox.session
 def test_style(session: Session) -> None:
     """Check that style guidelines are being followed"""
     install_requirements_file(session, "check-style")
     session.run("flake8", "src/django_idom", "tests")
-    black_default_exclude = r"\.eggs|\.git|\.hg|\.mypy_cache|\.nox|\.tox|\.venv|\.svn|_build|buck-out|build|dist"
     session.run(
         "black",
         ".",
         "--check",
-        "--exclude",
-        rf"/({black_default_exclude}|venv|node_modules)/",
+        "--extend-exclude",
+        "/migrations/",
     )
     session.run("isort", ".", "--check-only")
 
 
 def install_requirements_file(session: Session, name: str) -> None:
-    file_path = HERE / "requirements" / (name + ".txt")
+    file_path = HERE / "requirements" / f"{name}.txt"
     assert file_path.exists(), f"requirements file {file_path} does not exist"
     session.install("-r", str(file_path))

pyproject.toml

@@ -12,7 +12,7 @@ line_length = 88
 lines_after_imports = 2
 
 [tool.mypy]
-ignore_missing_imports = "True"
-warn_unused_configs = "True"
-warn_redundant_casts = "True"
-warn_unused_ignores = "True"
+ignore_missing_imports = true
+warn_unused_configs = true
+warn_redundant_casts = true
+warn_unused_ignores = true

requirements/build-docs.txt

@@ -1,4 +1,5 @@
 mkdocs
 mkdocs-git-revision-date-localized-plugin
 mkdocs-material
-mkdocs-include-markdown-plugin
+mkdocs-include-markdown-plugin
+linkcheckmd

requirements/pkg-deps.txt

@@ -1,3 +1,4 @@
 channels >=3.0.0
-idom >=0.39.0, <0.40.0
+idom >=0.40.2, <0.41.0
 aiofile >=3.0
+typing_extensions