v3.0.0a1: Bump IDOM to 1.0.0 pre-release (#125)

- Modify docs to use the upcoming IDOM-Core docs styling
   - Move docs python examples to individual files so we can run tests on them
   - CI for type checking + linting docs examples
   - Minor wording and section naming changes to feel more React-like
- Bump IDOM to 1.0.0 pre-release
   - Use the new `idom.html` API
   - Update package.json to be compatible with `idom>=1.0.0`
- Make the main `requirements.txt` be fully inclusive of all dev/user/docs dependencies to simplify development workflow
- Update `setup.py` to automatically install the latest NPM, and be easier to debug when things fail

Author: Archmonger

.github/workflows/test-docs.yml

@@ -20,6 +20,16 @@ jobs:
             - 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 --strict
+            - name: Check docs build
+              run: |
+                  pip install -r requirements/build-docs.txt
+                  linkcheckMarkdown docs/ -v -r
+                  mkdocs build --strict
+            - name: Check docs examples
+              run: |
+                  pip install -r requirements/check-types.txt
+                  pip install -r requirements/check-style.txt
+                  mypy --show-error-codes docs/python/
+                  black docs/python/ --check
+                  isort docs/python/ --check-only
+                  flake8 docs/python/

.gitignore

@@ -38,6 +38,7 @@ settings.json
 *$py.class
 
 # Distribution / packaging
+build/
 .Python build/
 develop-eggs/
 dist/

CHANGELOG.md

@@ -10,30 +10,58 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 <!--
 Using the following categories, list your changes in this order:
-    - "Added" for new features.
-    - "Changed" for changes in existing functionality.
-    - "Deprecated" for soon-to-be removed features.
-    - "Removed" for now removed features.
-    - "Fixed" for any bug fixes.
-    - "Security" in case of vulnerabilities.
+
+### Added
+-   for new features.
+
+### Changed
+-   for changes in existing functionality.
+
+### Deprecated
+-   for soon-to-be removed features.
+
+### Removed
+-   for removed features.
+
+### Fixed
+-   for bug fixes.
+
+### Security
+-   for vulnerability fixes.
  -->
 
 <!--changelog-start-->
 
 ## [Unreleased]
 
+-   Nothing (yet)
+
+## [3.0.0a1] - 2023-02-02
+
+???+ note
+
+    This is Django-IDOM's biggest update yet!
+
+    To upgrade from previous version you will need to...
+
+    1. Install `django-idom >= 3.0.0`
+    2. Run `idom update-html-usages <DIR>` to update your `idom.html.*` calls to the new syntax
+    3. Run `python manage.py migrate` to create the new Django-IDOM database entries
+
 ### Added
 
 -   The `idom` client will automatically configure itself to debug mode depending on `settings.py:DEBUG`.
 -   `use_connection` hook for returning the browser's active `Connection`
 
 ### Changed
 
+-   It is now mandatory to run `manage.py migrate` after installing IDOM.
+-   Bumped the minimum IDOM version to 1.0.0
+    -   Due to IDOM 1.0.0, `idom.html.*`, HTML properties are now `snake_case` `**kwargs` rather than a `dict` of values.
+    -   You can auto-convert to the new style using `idom update-html-usages <DIR>`.
 -   The `component` template tag now supports both positional and keyword arguments.
 -   The `component` template tag now supports non-serializable arguments.
 -   `IDOM_WS_MAX_RECONNECT_TIMEOUT` setting has been renamed to `IDOM_RECONNECT_MAX`.
--   It is now mandatory to run `manage.py migrate` after installing IDOM.
--   Bumped the minimum IDOM version to 0.43.0
 
 ### Removed
 
@@ -51,7 +79,7 @@ Using the following categories, list your changes in this order:
 -   Fixed a potential method of component template tag argument spoofing.
 -   Exception information will no longer be displayed on the page, based on the value of `settings.py:DEBUG`.
 
-## [2.2.1] - 2022-01-09
+## [2.2.1] - 2023-01-09
 
 ### Fixed
 
@@ -218,7 +246,8 @@ Using the following categories, list your changes in this order:
 
 -   Support for IDOM within the Django
 
-[unreleased]: https://github.com/idom-team/django-idom/compare/2.2.1...HEAD
+[unreleased]: https://github.com/idom-team/django-idom/compare/3.0.0a1...HEAD
+[3.0.0a1]: https://github.com/idom-team/django-idom/compare/2.2.1...3.0.0a1
 [2.2.1]: https://github.com/idom-team/django-idom/compare/2.2.0...2.2.1
 [2.2.0]: https://github.com/idom-team/django-idom/compare/2.1.0...2.2.0
 [2.1.0]: https://github.com/idom-team/django-idom/compare/2.0.1...2.1.0

README.md

@@ -1,6 +1,6 @@
 <!--header-start-->
 
-# Django IDOM &middot; [![Tests](https://github.com/idom-team/django-idom/workflows/Test/badge.svg?event=push)](https://github.com/idom-team/django-idom/actions?query=workflow%3ATest) [![PyPI Version](https://img.shields.io/pypi/v/django-idom.svg?label=PyPI)](https://pypi.python.org/pypi/django-idom) [![License](https://img.shields.io/badge/License-MIT-purple.svg)](https://github.com/idom-team/django-idom/blob/main/LICENSE) [![Docs](https://img.shields.io/website?down_message=offline&label=Docs&logo=read%20the%20docs&logoColor=white&up_message=online&url=https%3A%2F%2Fidom-team.github.io%2Fdjango-idom%2F)](https://idom-team.github.io/django-idom/)
+# Django-IDOM &middot; [![Tests](https://github.com/idom-team/django-idom/workflows/Test/badge.svg?event=push)](https://github.com/idom-team/django-idom/actions?query=workflow%3ATest) [![PyPI Version](https://img.shields.io/pypi/v/django-idom.svg?label=PyPI)](https://pypi.python.org/pypi/django-idom) [![License](https://img.shields.io/badge/License-MIT-purple.svg)](https://github.com/idom-team/django-idom/blob/main/LICENSE) [![Docs](https://img.shields.io/website?down_message=offline&label=Docs&logo=read%20the%20docs&logoColor=white&up_message=online&url=https%3A%2F%2Fidom-team.github.io%2Fdjango-idom%2F)](https://idom-team.github.io/django-idom/)
 
 <!--header-end-->
 <!--intro-start-->

docs/includes/examples.md

@@ -0,0 +1,3 @@
+Now, you can create/modify the Django-IDOM source code, and Pull Request (PR) your changes to our GitHub repository.
+
+To learn how to create GitHub PRs, [click here](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request).

docs/includes/pr.md

@@ -0,0 +1,13 @@
+{% extends "base.html" %}
+
+{% block content %}
+{{ super() }}
+
+{% if git_page_authors %}
+<div class="md-source-date">
+    <small>
+        Authors: {{ git_page_authors | default('enable mkdocs-git-authors-plugin') }}
+    </small>
+</div>
+{% endif %}
+{% endblock %}

docs/overrides/main.html

@@ -0,0 +1,9 @@
+from idom import component, html
+
+from django_idom.decorators import auth_required
+
+
+@component
+@auth_required(auth_attribute="is_staff")
+def my_component():
+    return html.div("I am logged in!")

docs/python/__init__.py

@@ -0,0 +1,14 @@
+from idom import component, html
+
+from django_idom.decorators import auth_required
+
+
+@component
+def my_component_fallback():
+    return html.div("I am NOT logged in!")
+
+
+@component
+@auth_required(fallback=my_component_fallback)
+def my_component():
+    return html.div("I am logged in!")

docs/python/auth-required-attribute.py

@@ -0,0 +1,7 @@
+from django.contrib.auth.models import AbstractBaseUser
+
+
+class CustomUserModel(AbstractBaseUser):
+    @property
+    def is_really_cool(self):
+        return True

docs/python/auth-required-component-fallback.py

@@ -0,0 +1,9 @@
+from idom import component, html
+
+from django_idom.decorators import auth_required
+
+
+@component
+@auth_required(auth_attribute="is_really_cool")
+def my_component():
+    return html.div("I am logged in!")

docs/python/auth-required-custom-attribute-model.py

@@ -0,0 +1,9 @@
+from idom import component, html
+
+from django_idom.decorators import auth_required
+
+
+@component
+@auth_required(fallback=html.div("I am NOT logged in!"))
+def my_component():
+    return html.div("I am logged in!")

docs/python/auth-required-custom-attribute.py

@@ -0,0 +1,9 @@
+from idom import component, html
+
+from django_idom.decorators import auth_required
+
+
+@component
+@auth_required
+def my_component():
+    return html.div("I am logged in!")

docs/python/auth-required-vdom-fallback.py

@@ -0,0 +1,27 @@
+import os
+
+from django.core.asgi import get_asgi_application
+
+
+# Ensure DJANGO_SETTINGS_MODULE is set properly based on your project name!
+os.environ.setdefault("DJANGO_SETTINGS_MODULE", "example_project.settings")
+
+# Fetch ASGI application before importing dependencies that require ORM models.
+django_asgi_app = get_asgi_application()
+
+
+from channels.auth import AuthMiddlewareStack  # noqa: E402
+from channels.routing import ProtocolTypeRouter, URLRouter  # noqa: E402
+from channels.sessions import SessionMiddlewareStack  # noqa: E402
+
+from django_idom import IDOM_WEBSOCKET_PATH  # noqa: E402
+
+
+application = ProtocolTypeRouter(
+    {
+        "http": django_asgi_app,
+        "websocket": SessionMiddlewareStack(
+            AuthMiddlewareStack(URLRouter([IDOM_WEBSOCKET_PATH]))
+        ),
+    }
+)

docs/python/auth-required.py

@@ -0,0 +1,5 @@
+INSTALLED_APPS = [
+    "daphne",
+    ...,
+]
+ASGI_APPLICATION = "example_project.asgi.application"

docs/python/configure-asgi.py

@@ -0,0 +1,4 @@
+INSTALLED_APPS = [
+    "django_idom",
+    ...,
+]

docs/python/configure-channels.py

@@ -0,0 +1,7 @@
+from django.urls import include, path
+
+
+urlpatterns = [
+    path("idom/", include("django_idom.http.urls")),
+    ...,
+]

docs/python/configure-installed-apps.py

@@ -0,0 +1,11 @@
+from idom import component, html
+
+
+@component
+def my_component():
+    return html.div(
+        html.link(
+            {"rel": "stylesheet", "href": "https://example.com/external-styles.css"}
+        ),
+        html.button("My Button!"),
+    )

docs/python/configure-urls.py

@@ -0,0 +1,10 @@
+from django.templatetags.static import static
+from idom import component, html
+
+
+@component
+def my_component():
+    return html.div(
+        html.link({"rel": "stylesheet", "href": static("css/buttons.css")}),
+        html.button("My Button!"),
+    )

docs/python/django-css-external-link.py

@@ -0,0 +1,11 @@
+from idom import component, html
+
+from django_idom.components import django_css
+
+
+@component
+def my_component():
+    return html.div(
+        django_css("css/buttons.css"),
+        html.button("My Button!"),
+    )

docs/python/django-css-local-link.py

@@ -0,0 +1,10 @@
+from django.templatetags.static import static
+from idom import component, html
+
+
+@component
+def my_component():
+    return html.div(
+        html.script({"src": static("js/scripts.js")}),
+        html.button("My Button!"),
+    )

docs/python/django-css.py

@@ -0,0 +1,9 @@
+from idom import component, html
+
+
+@component
+def my_component():
+    return html.div(
+        html.script({"src": "https://example.com/external-scripts.js"}),
+        html.button("My Button!"),
+    )

docs/python/django-js-local-script.py

@@ -0,0 +1,11 @@
+from idom import component, html
+
+from django_idom.components import django_js
+
+
+@component
+def my_component():
+    return html.div(
+        html.button("My Button!"),
+        django_js("js/scripts.js"),
+    )

docs/python/django-js-remote-script.py

@@ -0,0 +1,24 @@
+from example.models import TodoItem
+from idom import component
+
+from django_idom.hooks import use_query
+from django_idom.types import QueryOptions
+from django_idom.utils import django_query_postprocessor
+
+
+def get_items():
+    return TodoItem.objects.all()
+
+
+@component
+def todo_list():
+    # These `QueryOptions` are functionally equivalent to Django-IDOM's default values
+    item_query = use_query(
+        QueryOptions(
+            postprocessor=django_query_postprocessor,
+            postprocessor_kwargs={"many_to_many": True, "many_to_one": True},
+        ),
+        get_items,
+    )
+
+    return item_query.data

docs/python/django-js.py

@@ -0,0 +1,5 @@
+from django.db.models import CharField, Model
+
+
+class TodoItem(Model):
+    text: CharField = CharField(max_length=255)

docs/python/django-query-postprocessor.py

@@ -0,0 +1,7 @@
+from django.urls import path
+from example import views
+
+
+urlpatterns = [
+    path("example/", views.index),
+]

docs/python/example/__init__.py

@@ -0,0 +1,5 @@
+from django.shortcuts import render
+
+
+def index(request):
+    return render(request, "my-template.html")

docs/python/example/models.py

@@ -0,0 +1,15 @@
+# If "idom" cache is not configured, then "default" will be used
+# IDOM works best with a multiprocessing-safe and thread-safe cache backend.
+CACHES = {
+    "idom": {"BACKEND": ...},
+}
+
+# Maximum seconds between reconnection attempts before giving up.
+# Use `0` to prevent component reconnection.
+IDOM_RECONNECT_MAX = 259200
+
+# The URL for IDOM to serve the component rendering websocket
+IDOM_WEBSOCKET_URL = "idom/"
+
+# Dotted path to the default postprocessor function, or `None`
+IDOM_DEFAULT_QUERY_POSTPROCESSOR = "example_project.utils.my_postprocessor"

docs/python/example/urls.py

@@ -0,0 +1,6 @@
+from idom import component
+
+
+@component
+def frog_greeter(number, name, species=""):
+    return f"Hello #{number}, {name} the {species}!"