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

.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/pr.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/overrides/main.html

@@ -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/python/auth-required-attribute.py

@@ -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/auth-required-component-fallback.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-custom-attribute-model.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-custom-attribute.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-vdom-fallback.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.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/configure-asgi.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/configure-channels.py

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

docs/python/configure-installed-apps.py

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

docs/python/configure-urls.py

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

docs/python/django-css-external-link.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/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.link({"rel": "stylesheet", "href": static("css/buttons.css")}),
+ html.button("My Button!"),
+ )

docs/python/django-css.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-js-local-script.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-js-remote-script.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.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-query-postprocessor.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/example/models.py

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

docs/python/example/urls.py

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

docs/python/example/views.py

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

docs/python/settings.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/template-tag-args-kwargs.py

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