hyperclass 0.1.0__tar.gz → 0.2.0__tar.gz

{hyperclass-0.1.0 → hyperclass-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyperclass
-Version: 0.1.0
+Version: 0.2.0
 Summary: Build interactive web applications as Python class hierarchies.
 Author: Grant Jenks
 License-Expression: Apache-2.0
@@ -279,11 +279,16 @@ span("3 unread", id=id.unread_count)
 hx.get(count, target=id.unread_count)
 
 assert id.unread_count is id.unread_count
+assert id.message[42] is id.message[42]
 ~~~
 
 As an HTML attribute, `id.unread_count` renders as `unread-count`. As a
 selector, it renders as `#unread-count`.
 
+IDs can carry application keys without returning to strings. `id.message[42]`
+renders as `message-42` in an `id=` attribute and `#message-42` when used as a
+selector. String keys translate underscores to dashes too.
+
 Form names work the same way while preserving Python underscores:
 
 ~~~python
@@ -427,8 +432,9 @@ urlpatterns = [
 Handlers receive native `HttpRequest` objects and may return native
 `HttpResponse` objects. Routes sharing a path are dispatched by HTTP method,
 and route references use Django `reverse()`, including the mount and namespace.
-Full Hyperclass pages inherit an htmx `X-CSRFToken` header and request a Django
-CSRF cookie, so unsafe htmx requests work with `CsrfViewMiddleware` enabled.
+Full Hyperclass pages emit htmx 4's explicit `hx-headers:inherited` modifier
+with an `X-CSRFToken` header and request a Django CSRF cookie, so unsafe htmx
+requests work with `CsrfViewMiddleware` enabled.
 
 ### htmx 4
 
@@ -441,15 +447,71 @@ page, Hyperclass includes its CSS in a partial targeting the page's stable
 `hyperclass-styles` stylesheet. The new fragment is styled immediately, without
 a reload or a global CSS build.
 
+htmx attributes are mappings and compose with `|`. Modifiers and events remain
+Python expressions:
+
+~~~python
+attributes = (
+    hx.post(send, stream=True, target=id.stream_sink, swap="none")
+    | hx.on.before_request("this.reset()")
+    | hx.headers.inherited({"X-Workspace": "demo"})
+)
+~~~
+
+`stream=True` enables htmx 4's SSE response handling and adds the pinned
+`hx-sse` extension to that page. `hx.sse.connect(events)` is available for
+persistent connections.
+
+## Streaming responses
+
+Any host can return a `stream(...)` of ordinary Hyperclass values. Each value
+becomes one correctly framed, escaped server-sent event:
+
+~~~python
+from hyperclass import id, outer_morph, partial, stream
+
+
+@post("/messages/<int:message_id>/regenerate")
+def regenerate(self, request, message_id):
+    def events():
+        answer = ""
+        for token in model(prompt):
+            answer += token
+            yield partial(
+                message_view(message_id, answer),
+                hx_target=id.message[message_id].selector,
+                hx_swap=outer_morph,
+            )
+
+    return stream(events())
+~~~
+
+The response is streamed by Lite, Flask, or Django with the same handler.
+`event(value, name=..., id=..., retry=...)` exposes named events and replay
+fields when an application needs them. Component CSS discovered during a
+stream is carried to the browser once, just like a normal htmx fragment.
+
 ## Try the examples
 
-Clone the repository and run the persistent SQLite bookmark inbox:
+Clone the repository and run the persistent streaming chat:
 
 ~~~console
 git clone https://github.com/grantjenks/python-hyperclass
 cd python-hyperclass
+python -m hyperclass examples.chat:app
+# Flask: flask --app examples.chat_flask run
+~~~
+
+The chat demonstrates an AI-style interface without an API key: persistent
+conversations, responsive history, token streaming, stop, and regenerate. Pass
+any `model(prompt) -> iterable[str]` to `create_app` or `ChatRoutes` to replace
+the deterministic local demo model. Its components and routes are shared by
+Lite, Flask, and Django.
+
+The SQLite bookmark inbox remains a smaller CRUD example:
+
+~~~console
 python -m hyperclass examples.bookmarks:app
-# Flask: flask --app examples.bookmarks_flask run
 ~~~
 
 The bookmark app adds, searches, filters, edits, marks, and deletes bookmarks.
@@ -486,9 +548,9 @@ Run the Python test matrix locally with:
 uvx nox -s tests
 ~~~
 
-The browser contract starts each of the Lite, Flask, and Django bookmark hosts
-on an ephemeral port and exercises add, toggle, edit, search, and delete
-through htmx in Chromium:
+The browser contract starts the Lite, Flask, and Django bookmark and chat hosts
+on ephemeral ports. It exercises CRUD plus streamed send, concurrent stop,
+regenerate, and persistence through htmx in Chromium:
 
 ~~~console
 uvx nox -s browser
@@ -500,6 +562,7 @@ runtime dependency.
 ## Status
 
 Hyperclass is deliberately pre-alpha: useful enough to build small applications
-and young enough for its API to change. Python 3.10 through 3.14 are tested.
+and young enough for its API to change. Python 3.10 through 3.14 and the
+cross-host browser contract are tested on every change.
 
 Apache-2.0 licensed.

{hyperclass-0.1.0 → hyperclass-0.2.0}/README.md

@@ -243,11 +243,16 @@ span("3 unread", id=id.unread_count)
 hx.get(count, target=id.unread_count)
 
 assert id.unread_count is id.unread_count
+assert id.message[42] is id.message[42]
 ~~~
 
 As an HTML attribute, `id.unread_count` renders as `unread-count`. As a
 selector, it renders as `#unread-count`.
 
+IDs can carry application keys without returning to strings. `id.message[42]`
+renders as `message-42` in an `id=` attribute and `#message-42` when used as a
+selector. String keys translate underscores to dashes too.
+
 Form names work the same way while preserving Python underscores:
 
 ~~~python
@@ -391,8 +396,9 @@ urlpatterns = [
 Handlers receive native `HttpRequest` objects and may return native
 `HttpResponse` objects. Routes sharing a path are dispatched by HTTP method,
 and route references use Django `reverse()`, including the mount and namespace.
-Full Hyperclass pages inherit an htmx `X-CSRFToken` header and request a Django
-CSRF cookie, so unsafe htmx requests work with `CsrfViewMiddleware` enabled.
+Full Hyperclass pages emit htmx 4's explicit `hx-headers:inherited` modifier
+with an `X-CSRFToken` header and request a Django CSRF cookie, so unsafe htmx
+requests work with `CsrfViewMiddleware` enabled.
 
 ### htmx 4
 
@@ -405,15 +411,71 @@ page, Hyperclass includes its CSS in a partial targeting the page's stable
 `hyperclass-styles` stylesheet. The new fragment is styled immediately, without
 a reload or a global CSS build.
 
+htmx attributes are mappings and compose with `|`. Modifiers and events remain
+Python expressions:
+
+~~~python
+attributes = (
+    hx.post(send, stream=True, target=id.stream_sink, swap="none")
+    | hx.on.before_request("this.reset()")
+    | hx.headers.inherited({"X-Workspace": "demo"})
+)
+~~~
+
+`stream=True` enables htmx 4's SSE response handling and adds the pinned
+`hx-sse` extension to that page. `hx.sse.connect(events)` is available for
+persistent connections.
+
+## Streaming responses
+
+Any host can return a `stream(...)` of ordinary Hyperclass values. Each value
+becomes one correctly framed, escaped server-sent event:
+
+~~~python
+from hyperclass import id, outer_morph, partial, stream
+
+
+@post("/messages/<int:message_id>/regenerate")
+def regenerate(self, request, message_id):
+    def events():
+        answer = ""
+        for token in model(prompt):
+            answer += token
+            yield partial(
+                message_view(message_id, answer),
+                hx_target=id.message[message_id].selector,
+                hx_swap=outer_morph,
+            )
+
+    return stream(events())
+~~~
+
+The response is streamed by Lite, Flask, or Django with the same handler.
+`event(value, name=..., id=..., retry=...)` exposes named events and replay
+fields when an application needs them. Component CSS discovered during a
+stream is carried to the browser once, just like a normal htmx fragment.
+
 ## Try the examples
 
-Clone the repository and run the persistent SQLite bookmark inbox:
+Clone the repository and run the persistent streaming chat:
 
 ~~~console
 git clone https://github.com/grantjenks/python-hyperclass
 cd python-hyperclass
+python -m hyperclass examples.chat:app
+# Flask: flask --app examples.chat_flask run
+~~~
+
+The chat demonstrates an AI-style interface without an API key: persistent
+conversations, responsive history, token streaming, stop, and regenerate. Pass
+any `model(prompt) -> iterable[str]` to `create_app` or `ChatRoutes` to replace
+the deterministic local demo model. Its components and routes are shared by
+Lite, Flask, and Django.
+
+The SQLite bookmark inbox remains a smaller CRUD example:
+
+~~~console
 python -m hyperclass examples.bookmarks:app
-# Flask: flask --app examples.bookmarks_flask run
 ~~~
 
 The bookmark app adds, searches, filters, edits, marks, and deletes bookmarks.
@@ -450,9 +512,9 @@ Run the Python test matrix locally with:
 uvx nox -s tests
 ~~~
 
-The browser contract starts each of the Lite, Flask, and Django bookmark hosts
-on an ephemeral port and exercises add, toggle, edit, search, and delete
-through htmx in Chromium:
+The browser contract starts the Lite, Flask, and Django bookmark and chat hosts
+on ephemeral ports. It exercises CRUD plus streamed send, concurrent stop,
+regenerate, and persistence through htmx in Chromium:
 
 ~~~console
 uvx nox -s browser
@@ -464,6 +526,7 @@ runtime dependency.
 ## Status
 
 Hyperclass is deliberately pre-alpha: useful enough to build small applications
-and young enough for its API to change. Python 3.10 through 3.14 are tested.
+and young enough for its API to change. Python 3.10 through 3.14 and the
+cross-host browser contract are tested on every change.
 
 Apache-2.0 licensed.

{hyperclass-0.1.0 → hyperclass-0.2.0}/hyperclass/__init__.py

@@ -62,8 +62,9 @@ from .lite import (
     route,
 )
 from .wsgi import delete as delete_route
+from .streaming import EventStream, SSEEvent, event, stream
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 
 hidden = "hidden"
 submit = "submit"
@@ -79,6 +80,7 @@ __all__ = [
     "BoundEndpoint",
     "Color",
     "Endpoint",
+    "EventStream",
     "Htmx",
     "Length",
     "Media",
@@ -87,6 +89,7 @@ __all__ = [
     "Route",
     "RouteURL",
     "Style",
+    "SSEEvent",
     "Target",
     "Unit",
     "Values",
@@ -99,6 +102,7 @@ __all__ = [
     "delete_swap",
     "delete_route",
     "em",
+    "event",
     "find",
     "flex",
     "grid",
@@ -126,6 +130,7 @@ __all__ = [
     "rem",
     "route",
     "submit",
+    "stream",
     "vh",
     "vw",
     *_html.__all__,

{hyperclass-0.1.0 → hyperclass-0.2.0}/hyperclass/django.py

@@ -8,7 +8,7 @@ from collections.abc import Callable
 from typing import Any
 from urllib.parse import urlencode
 
-from django.http import HttpRequest, HttpResponse, QueryDict
+from django.http import HttpRequest, HttpResponse, QueryDict, StreamingHttpResponse
 from django.middleware.csrf import get_token
 from django.urls import URLPattern, reverse
 from django.urls import path as django_path
@@ -17,6 +17,7 @@ from .html import Fragment, Page, element
 from .lite import call_handler
 from .rendering import render_result, unpack_result
 from .routing import Endpoint, Handler, Route, RouteURL, class_endpoints, route
+from .streaming import EventStream
 
 _BARE_PARAMETER = re.compile(r"<([A-Za-z_]\w*)>")
 
@@ -136,6 +137,17 @@ class App:
             return result
 
         body, status, headers = unpack_result(result)
+        if isinstance(body, EventStream):
+            response = StreamingHttpResponse(
+                body.iter_bytes(title=self.title, url_resolver=self.resolve_url),
+                status=status,
+                content_type="text/event-stream; charset=utf-8",
+            )
+            response["Cache-Control"] = "no-cache"
+            response["X-Accel-Buffering"] = "no"
+            for name, value in headers:
+                response[name] = value
+            return response
         if isinstance(body, (element, Fragment, Page)):
             body = render_result(
                 body,
@@ -143,7 +155,7 @@ class App:
                 is_htmx=request.headers.get("HX-Request", "").lower() == "true",
                 url_resolver=self.resolve_url,
                 body_attributes={
-                    "hx_headers": json.dumps(
+                    "hx-headers:inherited": json.dumps(
                         {"X-CSRFToken": get_token(request)}, separators=(",", ":")
                     )
                 },

{hyperclass-0.1.0 → hyperclass-0.2.0}/hyperclass/flask.py

@@ -6,13 +6,14 @@ from collections.abc import Callable
 from typing import Any
 from urllib.parse import urlencode
 
-from flask import Flask, request, url_for
+from flask import Flask, request, stream_with_context, url_for
 from flask import Response as FlaskResponse
 
 from .html import Fragment, Page, element
 from .lite import call_handler
 from .rendering import render_result, unpack_result
 from .routing import Endpoint, Handler, Route, RouteURL, class_endpoints, route
+from .streaming import EventStream
 
 
 class App(Flask):
@@ -106,6 +107,18 @@ class App(Flask):
             return super().make_response(rv)
 
         body, status, headers = unpack_result(rv)
+        if isinstance(body, EventStream):
+            response = FlaskResponse(
+                stream_with_context(
+                    body.iter_text(title=self.title, url_resolver=self.resolve_url)
+                ),
+                status=status,
+                headers=headers,
+                content_type="text/event-stream; charset=utf-8",
+            )
+            response.headers.setdefault("Cache-Control", "no-cache")
+            response.headers.setdefault("X-Accel-Buffering", "no")
+            return response
         if isinstance(body, (element, Fragment, Page)):
             body = render_result(
                 body,

{hyperclass-0.1.0 → hyperclass-0.2.0}/hyperclass/html.py

@@ -13,6 +13,9 @@ HTMX_SRC = "https://cdn.jsdelivr.net/npm/htmx.org@4.0.0"
 HTMX_INTEGRITY = (
     "sha384-BvJpBiO8Kh31EqtJe5DRIeWrHWnCGkwytKs9NKFi86Hhw96dEqdEMzZDeK9iEGTc"
 )
+HTMX_EXTENSIONS = {
+    "sse": "https://cdn.jsdelivr.net/npm/htmx.org@4.0.0/dist/ext/hx-sse.min.js",
+}
 
 
 def class_name(value: type) -> str:
@@ -32,6 +35,11 @@ class Id:
     def __str__(self) -> str:
         return self.name
 
+    def __getitem__(self, value: Any) -> Id:
+        """Return an interned child id, e.g. ``id.message[42]``."""
+
+        return id._intern(f"{self.name}-{str(value).replace('_', '-')}")
+
 
 class IdNamespace:
     def __init__(self) -> None:
@@ -40,12 +48,15 @@ class IdNamespace:
     def __getattr__(self, name: str) -> Id:
         if name.startswith("_"):
             raise AttributeError(name)
+        return self._intern(name.replace("_", "-"))
+
+    def _intern(self, value: str) -> Id:
         try:
-            return self._values[name]
+            return self._values[value]
         except KeyError:
-            value = Id(name.replace("_", "-"))
-            self._values[name] = value
-            return value
+            identity = Id(value)
+            self._values[value] = identity
+            return identity
 
 
 id = IdNamespace()
@@ -176,6 +187,8 @@ class RenderContext:
         self.url_resolver = url_resolver
         self.styled_elements: list[type] = []
         self._seen_elements: set[type] = set()
+        self.extensions: list[str] = []
+        self._seen_extensions: set[str] = set()
 
     def register(self, value: type) -> None:
         if value in self._seen_elements:
@@ -189,6 +202,12 @@ class RenderContext:
             self._seen_elements.add(value)
             self.styled_elements.append(value)
 
+    def register_extensions(self, values: Iterable[str]) -> None:
+        for value in values:
+            if value not in self._seen_extensions:
+                self._seen_extensions.add(value)
+                self.extensions.append(value)
+
     def stylesheet(self) -> str:
         rules: list[str] = []
         for element_type in self.styled_elements:
@@ -229,6 +248,10 @@ def _attribute_value(value: Any, context: RenderContext) -> str:
 def _attribute(target: dict[str, Any], name: str, value: Any) -> None:
     if name == "hx" and isinstance(value, Mapping):
         target.update(value)
+        extensions = getattr(value, "extensions", ())
+        if extensions:
+            existing = target.setdefault("_hyperclass_extensions", set())
+            existing.update(extensions)
     else:
         target[_attribute_name(name)] = value
 
@@ -279,7 +302,7 @@ Element = element
 TAG_NAMES = (
     "html head body title meta link style script main header footer nav section "
     "article "
-    "aside div span p a h1 h2 h3 h4 h5 h6 ul ol li dl dt dd form label input "
+    "aside div span p a h1 h2 h3 h4 h5 h6 ul ol li dl dt dd form fieldset legend label input "
     "button output textarea select option table thead tbody tfoot tr th td figure "
     "figcaption picture source img video audio canvas template details summary dialog "
     "blockquote pre code strong em small br hr"
@@ -321,6 +344,7 @@ def _render_attributes(
 ) -> str:
     attributes = _class_attributes(type(node))
     attributes.update(getattr(node, "_attrs", {}))
+    context.register_extensions(attributes.pop("_hyperclass_extensions", ()))
     generated = [class_name(value) for value in classes]
     explicit = attributes.pop("class", attributes.pop("class-", None))
     if explicit:
@@ -413,6 +437,10 @@ class Page:
                 f'<script src="{HTMX_SRC}" integrity="{HTMX_INTEGRITY}" '
                 'crossorigin="anonymous"></script>'
             )
+            script_html += "".join(
+                f'<script src="{escape(HTMX_EXTENSIONS[value], quote=True)}"></script>'
+                for value in context.extensions
+            )
         return (
             "<!doctype html>"
             f'<html lang="{escape(self.lang, quote=True)}"><head>'
@@ -437,6 +465,7 @@ __all__ = [
     "Element",
     "Fragment",
     "HTMX_INTEGRITY",
+    "HTMX_EXTENSIONS",
     "HTMX_SRC",
     "Id",
     "IdNamespace",

{hyperclass-0.1.0 → hyperclass-0.2.0}/hyperclass/htmx.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from collections.abc import Iterator, Mapping
+import json
 from typing import Any
 
 from .html import selector
@@ -33,8 +34,9 @@ def previous(value: Any | None = None) -> Target:
 
 
 class Attributes(Mapping[str, Any]):
-    def __init__(self, values: Mapping[str, Any]):
+    def __init__(self, values: Mapping[str, Any], *, extensions: tuple[str, ...] = ()):
         self.values = dict(values)
+        self.extensions = extensions
 
     def __getitem__(self, key: str) -> Any:
         return self.values[key]
@@ -45,13 +47,55 @@ class Attributes(Mapping[str, Any]):
     def __len__(self) -> int:
         return len(self.values)
 
+    def __or__(self, other: Mapping[str, Any]) -> Attributes:
+        values = {**self.values, **dict(other)}
+        extensions = tuple(
+            dict.fromkeys((*self.extensions, *getattr(other, "extensions", ())))
+        )
+        return Attributes(values, extensions=extensions)
+
+    def __ror__(self, other: Mapping[str, Any]) -> Attributes:
+        return Attributes(other) | self
+
 
 def _option_name(value: str) -> str:
     return f"hx-{value.rstrip('_').replace('_', '-')}"
 
 
+class HtmxAttribute:
+    def __init__(self, *parts: str):
+        self.parts = parts
+
+    def __getattr__(self, name: str) -> HtmxAttribute:
+        if name.startswith("_"):
+            raise AttributeError(name)
+        return HtmxAttribute(*self.parts, name)
+
+    def __call__(self, value: Any = True) -> Attributes:
+        root, *modifiers = self.parts
+        extension = ("sse",) if root == "sse" else ()
+        if root == "on":
+            suffix = ":".join(part.replace("_", ":") for part in modifiers)
+            attribute = f"hx-on::{suffix}"
+        else:
+            attribute = _option_name(root)
+            if modifiers:
+                attribute += ":" + ":".join(
+                    part.rstrip("_").replace("_", "-") for part in modifiers
+                )
+        if isinstance(value, Mapping):
+            value = json.dumps(value, separators=(",", ":"))
+        return Attributes({attribute: value}, extensions=extension)
+
+
 class Htmx:
+    def __getattr__(self, name: str) -> HtmxAttribute:
+        if name.startswith("_"):
+            raise AttributeError(name)
+        return HtmxAttribute(name)
+
     def request(self, method: str, url: Any, **options: Any) -> Attributes:
+        stream = bool(options.pop("stream", False))
         route_url = getattr(url, "url", None)
         route_parameters = getattr(url, "parameters", None)
         if callable(route_url) and callable(route_parameters):
@@ -66,10 +110,17 @@ class Htmx:
         for name, value in options.items():
             if value is None:
                 continue
-            if name in {"include", "target", "select", "select_oob", "sync"}:
+            if name in {
+                "disable",
+                "include",
+                "target",
+                "select",
+                "select_oob",
+                "sync",
+            }:
                 value = selector(value) if not isinstance(value, Target) else value
             values[_option_name(name)] = value
-        return Attributes(values)
+        return Attributes(values, extensions=("sse",) if stream else ())
 
     def get(self, url: Any, **options: Any) -> Attributes:
         return self.request("get", url, **options)

{hyperclass-0.1.0 → hyperclass-0.2.0}/hyperclass/lite.py

@@ -3,12 +3,13 @@
 from __future__ import annotations
 
 import inspect
-from collections.abc import Callable, Mapping
+from collections.abc import Callable, Iterable, Mapping
 from dataclasses import dataclass, is_dataclass
 from http import HTTPStatus
+from socketserver import ThreadingMixIn
 from typing import Any, get_type_hints
 from urllib.parse import parse_qs
-from wsgiref.simple_server import make_server
+from wsgiref.simple_server import WSGIServer, make_server
 
 from .binding import Values, bind
 from .rendering import render_result, unpack_result
@@ -26,10 +27,17 @@ from .routing import (
     put,
     route,
 )
+from .streaming import EventStream
 
 StartResponse = Callable[[str, list[tuple[str, str]]], Any]
 
 
+class ThreadingWSGIServer(ThreadingMixIn, WSGIServer):
+    """The standard WSGI server with concurrent request handling."""
+
+    daemon_threads = True
+
+
 class Request:
     def __init__(self, environ: Mapping[str, Any]):
         self.environ = environ
@@ -146,7 +154,7 @@ class App:
 
     def __call__(
         self, environ: Mapping[str, Any], start_response: StartResponse
-    ) -> list[bytes]:
+    ) -> Iterable[bytes]:
         request = Request(environ)
         handler = self.routes.get((request.method, request.path))
         parameters: dict[str, Any] = {}
@@ -179,7 +187,21 @@ class App:
 
     def _respond(
         self, start_response: StartResponse, response: Response, request: Request
-    ) -> list[bytes]:
+    ) -> Iterable[bytes]:
+        if isinstance(response.body, EventStream):
+            headers = [
+                ("Content-Type", "text/event-stream; charset=utf-8"),
+                ("Cache-Control", "no-cache"),
+                ("X-Accel-Buffering", "no"),
+            ]
+            headers.extend(response.headers)
+            start_response(
+                f"{response.status} {HTTPStatus(response.status).phrase}", headers
+            )
+            return response.body.iter_bytes(
+                title=self.title,
+                url_resolver=self.resolve_url,
+            )
         text = render_result(
             response.body,
             title=self.title,
@@ -205,7 +227,12 @@ class App:
         )
 
     def run(self, host: str = "127.0.0.1", port: int = 8000) -> None:
-        with make_server(host, port, self) as server:
+        with make_server(
+            host,
+            port,
+            self,
+            server_class=ThreadingWSGIServer,
+        ) as server:
             print(f"Serving on http://{host}:{port}")
             server.serve_forever()