hyperclass 0.1.1__tar.gz → 0.2.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyperclass
-Version: 0.1.1
+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
@@ -442,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.
@@ -487,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
@@ -501,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.1 → 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
@@ -406,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.
@@ -451,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
@@ -465,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.1 → 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.1"
+__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.1 → 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,

{hyperclass-0.1.1 → 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.1 → 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.1 → 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.1 → 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()
 

hyperclass-0.2.0/hyperclass/streaming.py

@@ -0,0 +1,113 @@
+"""Host-neutral server-sent event responses."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator
+from dataclasses import dataclass
+from typing import Any
+
+from .html import (
+    Fragment,
+    Markup,
+    Page,
+    RenderContext,
+    element,
+    id as html_id,
+    markup,
+    partial,
+    render,
+)
+from .rendering import render_result
+from .routing import URLResolver
+
+
+@dataclass(frozen=True)
+class SSEEvent:
+    """One server-sent event containing a renderable Hyperclass value."""
+
+    content: Any
+    name: str | None = None
+    id: str | None = None
+    retry: int | None = None
+
+
+def event(
+    content: Any,
+    *,
+    name: str | None = None,
+    id: str | None = None,
+    retry: int | None = None,
+) -> SSEEvent:
+    return SSEEvent(content, name=name, id=id, retry=retry)
+
+
+class EventStream:
+    """An iterable response rendered as ``text/event-stream``."""
+
+    def __init__(self, events: Iterable[Any]):
+        self.events = events
+
+    def iter_text(
+        self,
+        *,
+        title: str = "Hyperclass",
+        url_resolver: URLResolver | None = None,
+    ) -> Iterator[str]:
+        context = RenderContext(url_resolver=url_resolver)
+        emitted_styles = ""
+        for value in self.events:
+            current = value if isinstance(value, SSEEvent) else SSEEvent(value)
+            content = current.content
+            if isinstance(content, Page):
+                text = render_result(
+                    content,
+                    title=title,
+                    is_htmx=True,
+                    url_resolver=url_resolver,
+                )
+            elif isinstance(content, (element, Fragment, Markup)):
+                text = render(content, context=context)
+                stylesheet = context.stylesheet()
+                if stylesheet.startswith(emitted_styles):
+                    new_styles = stylesheet[len(emitted_styles) :]
+                else:
+                    new_styles = stylesheet
+                emitted_styles = stylesheet
+                if new_styles:
+                    text += render(
+                        partial(
+                            markup(new_styles),
+                            id=html_id.hyperclass_styles,
+                            hx_swap="append",
+                        ),
+                        context=context,
+                    )
+            else:
+                text = render(content)
+            fields: list[str] = []
+            if current.name is not None:
+                fields.append(f"event: {current.name}")
+            if current.id is not None:
+                fields.append(f"id: {current.id}")
+            if current.retry is not None:
+                fields.append(f"retry: {current.retry}")
+            fields.extend(f"data: {line}" for line in text.splitlines() or [""])
+            yield "\n".join(fields) + "\n\n"
+
+    def iter_bytes(
+        self,
+        *,
+        title: str = "Hyperclass",
+        url_resolver: URLResolver | None = None,
+    ) -> Iterator[bytes]:
+        for value in self.iter_text(title=title, url_resolver=url_resolver):
+            yield value.encode("utf-8")
+
+
+def stream(events: Iterable[Any]) -> EventStream:
+    """Create a streaming response from renderable values or ``event`` objects."""
+
+    return EventStream(events)
+
+
+__all__ = ["EventStream", "SSEEvent", "event", "stream"]

{hyperclass-0.1.1 → hyperclass-0.2.0}/hyperclass.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyperclass
-Version: 0.1.1
+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
@@ -442,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.
@@ -487,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
@@ -501,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.1 → hyperclass-0.2.0}/hyperclass.egg-info/SOURCES.txt

@@ -12,6 +12,7 @@ hyperclass/htmx.py
 hyperclass/lite.py
 hyperclass/rendering.py
 hyperclass/routing.py
+hyperclass/streaming.py
 hyperclass/wsgi.py
 hyperclass.egg-info/PKG-INFO
 hyperclass.egg-info/SOURCES.txt
@@ -19,10 +20,12 @@ hyperclass.egg-info/dependency_links.txt
 hyperclass.egg-info/requires.txt
 hyperclass.egg-info/top_level.txt
 tests/test_bookmarks.py
+tests/test_chat.py
 tests/test_cli.py
 tests/test_django.py
 tests/test_flask.py
 tests/test_html.py
 tests/test_htmx.py
 tests/test_package.py
+tests/test_streaming.py
 tests/test_wsgi.py

{hyperclass-0.1.1 → hyperclass-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "hyperclass"
-version = "0.1.1"
+version = "0.2.0"
 description = "Build interactive web applications as Python class hierarchies."
 readme = "README.md"
 requires-python = ">=3.10"

hyperclass-0.2.0/tests/test_chat.py

@@ -0,0 +1,112 @@
+from io import BytesIO
+from urllib.parse import urlencode
+from wsgiref.util import setup_testing_defaults
+
+from examples.chat import create_app
+
+
+def request(app, method="GET", path="/", data=None, htmx=False):
+    environ = {}
+    setup_testing_defaults(environ)
+    body = urlencode(data or {}).encode()
+    environ.update(
+        REQUEST_METHOD=method,
+        PATH_INFO=path,
+        CONTENT_TYPE="application/x-www-form-urlencoded",
+        CONTENT_LENGTH=str(len(body)),
+        **{"wsgi.input": BytesIO(body)},
+    )
+    if htmx:
+        environ["HTTP_HX_REQUEST"] = "true"
+    captured = {}
+
+    def start_response(status, headers):
+        captured["status"] = status
+        captured["headers"] = dict(headers)
+
+    payload = b"".join(app(environ, start_response)).decode()
+    return captured, payload
+
+
+def test_chat_page_uses_indexed_ids_routes_and_sse_extension(tmp_path):
+    app = create_app(tmp_path / "chat.db", model=lambda prompt: ["Hello"], token_delay=0)
+    captured, payload = request(app)
+    conversation = app.store.latest_or_create()
+
+    assert captured["status"] == "200 OK"
+    assert "dist/ext/hx-sse.min.js" in payload
+    assert f'hx-post="/chats/{conversation.id}/messages"' in payload
+    assert 'hx-disable="find .composer-fields"' in payload
+    assert 'hx-on::before:request="this.reset()"' in payload
+
+
+def test_chat_stream_persists_and_targets_each_message(tmp_path):
+    app = create_app(
+        tmp_path / "chat.db",
+        model=lambda prompt: ["Hello ", prompt],
+        token_delay=0,
+    )
+    conversation = app.store.latest_or_create()
+    captured, payload = request(
+        app,
+        "POST",
+        f"/chats/{conversation.id}/messages",
+        {"message": "Python"},
+        htmx=True,
+    )
+
+    assert captured["headers"]["Content-Type"] == "text/event-stream; charset=utf-8"
+    assert f'hx-target="#messages" hx-swap="append"' in payload
+    messages = app.store.messages(conversation.id)
+    assert [message.role for message in messages] == ["user", "assistant"]
+    assistant = messages[-1]
+    assert assistant.content == "Hello Python"
+    assert assistant.status == "complete"
+    assert f'id="message-{assistant.id}"' in payload
+    assert f'hx-target="#message-{assistant.id}" hx-swap="outerMorph"' in payload
+
+
+def test_chat_accepts_an_injected_model_and_regenerates(tmp_path):
+    prompts = []
+
+    def model(prompt):
+        prompts.append(prompt)
+        yield "Replied"
+
+    app = create_app(tmp_path / "chat.db", model=model, token_delay=0)
+    conversation = app.store.latest_or_create()
+    request(
+        app,
+        "POST",
+        f"/chats/{conversation.id}/messages",
+        {"message": "Again"},
+        htmx=True,
+    )
+    assistant = app.store.messages(conversation.id)[-1]
+    captured, payload = request(
+        app,
+        "POST",
+        f"/messages/{assistant.id}/regenerate",
+        htmx=True,
+    )
+    assert captured["status"] == "200 OK"
+    assert "Replied" in payload
+    assert prompts == ["Again", "Again"]
+
+
+def test_superseded_generator_cannot_write_into_a_regeneration(tmp_path):
+    app = create_app(tmp_path / "chat.db", token_delay=0)
+    conversation = app.store.latest_or_create()
+    assistant = app.store.add_message(
+        conversation.id, "assistant", "old", "streaming", generation=1
+    )
+    app.store.stop(assistant.id)
+    restarted = app.store.restart(assistant.id)
+
+    assert restarted.generation == 2
+    assert app.store.update_generation(
+        assistant.id, generation=1, content="stale write", status="streaming"
+    ) is None
+    current = app.store.message(assistant.id)
+    assert current.content == ""
+    assert current.status == "streaming"

{hyperclass-0.1.1 → hyperclass-0.2.0}/tests/test_django.py

@@ -21,7 +21,7 @@ from django.http import HttpRequest, HttpResponse
 from django.test import Client
 from django.urls import clear_url_caches, include, path
 
-from hyperclass import div, form, get, hx, post
+from hyperclass import div, form, get, hx, post, stream
 from hyperclass.django import App
 
 
@@ -95,3 +95,16 @@ def test_django_dispatches_methods_on_one_url_pattern():
     client = mounted(DjangoRoutes(namespace="methods"))
     response = client.get("/mounted/items/3")
     assert response.status_code == 405
+
+
+def test_django_streams_server_sent_events():
+    class Events(App):
+        @get("/events")
+        def events(self, request):
+            return stream([div("one"), div("two")])
+
+    response = mounted(Events(namespace="events")).get("/mounted/events")
+    assert response["Content-Type"] == "text/event-stream; charset=utf-8"
+    assert b"".join(response.streaming_content) == (
+        b"data: <div>one</div>\n\ndata: <div>two</div>\n\n"
+    )

{hyperclass-0.1.1 → hyperclass-0.2.0}/tests/test_flask.py

@@ -2,7 +2,7 @@ from dataclasses import dataclass
 
 from flask import Request, Response
 
-from hyperclass import div, form, get, hx, post, render
+from hyperclass import div, form, get, hx, post, render, stream
 from hyperclass.flask import App
 from examples.bookmarks import BookmarkRoutes
 
@@ -83,3 +83,16 @@ def test_flask_bookmark_routes_read_native_query_keys(tmp_path):
     )
     assert response.status_code == 200
     assert "No bookmarks matching "missing"." in response.text
+
+
+def test_flask_streams_server_sent_events():
+    app = App()
+
+    @app.get("/events")
+    def events(request):
+        return stream([div("one"), div("two")])
+
+    response = app.test_client().get("/events")
+    assert response.content_type == "text/event-stream; charset=utf-8"
+    assert response.text.startswith("data: <div>one</div>\n\n")
+    assert response.text.endswith("data: <div>two</div>\n\n")

{hyperclass-0.1.1 → hyperclass-0.2.0}/tests/test_html.py

@@ -101,6 +101,14 @@ def test_ids_are_lazy_interned_python_references():
     )
 
 
+def test_ids_can_be_parameterized_with_python_values():
+    assert id.message[42] is id.message[42]
+    assert id.message["draft_reply"] is id.message["draft_reply"]
+    assert str(id.message[42]) == "message-42"
+    assert id.message[42].selector == "#message-42"
+    assert str(id.message["draft_reply"]) == "message-draft-reply"
+
+
 def test_page_collects_state_and_media_styles_from_classes():
     class interactive_card(card):
         hover = css(background="lavender")

hyperclass-0.2.0/tests/test_htmx.py

@@ -0,0 +1,64 @@
+from hyperclass import Page, closest, div, find, hx, id, name, outer_morph, render
+
+
+class counter(div):
+    pass
+
+
+def test_htmx_request_attributes_accept_class_selectors():
+    value = div(
+        "Update",
+        hx=hx.post(
+            "/counter",
+            target=closest(counter),
+            swap=outer_morph,
+        ),
+    )
+    assert render(value) == (
+        '<div hx-post="/counter" hx-target="closest .counter" '
+        'hx-swap="outerMorph">Update</div>'
+    )
+
+
+def test_plain_class_target_becomes_a_selector():
+    assert render(div(hx=hx.get("/counter", target=counter))) == (
+        '<div hx-get="/counter" hx-target=".counter"></div>'
+    )
+
+
+def test_class_attributes_can_declare_htmx_and_name_selectors():
+    class live_search(div):
+        hx = hx.get(
+            "/search",
+            include=name.query,
+            target=id.results,
+            swap=outer_morph,
+        )
+
+    assert render(live_search()) == (
+        '<div class="live-search" hx-get="/search" '
+        'hx-include="[name=&quot;query&quot;]" hx-target="#results" '
+        'hx-swap="outerMorph"></div>'
+    )
+
+
+def test_htmx_attributes_compose_and_support_modifiers():
+    attributes = (
+        hx.post("/messages", target=id.messages, stream=True, disable=find("fieldset"))
+        | hx.on.before_request("this.reset()")
+        | hx.headers.inherited({"X-CSRFToken": "token"})
+    )
+    document = Page(div(hx=attributes)).render()
+    assert 'hx-post="/messages"' in document
+    assert 'hx-target="#messages"' in document
+    assert 'hx-disable="find fieldset"' in document
+    assert 'hx-on::before:request="this.reset()"' in document
+    assert 'hx-headers:inherited="{&quot;X-CSRFToken&quot;:&quot;token&quot;}"' in document
+    assert "dist/ext/hx-sse.min.js" in document
+
+
+def test_htmx_sse_connect_loads_extension_without_a_fake_html_attribute():
+    document = Page(div(hx=hx.sse.connect("/events"))).render()
+    assert 'hx-sse:connect="/events"' in document
+    assert "dist/ext/hx-sse.min.js" in document
+    assert "_hyperclass" not in document

hyperclass-0.2.0/tests/test_package.py

@@ -0,0 +1,5 @@
+import hyperclass
+
+
+def test_version():
+    assert hyperclass.__version__ == "0.2.0"

hyperclass-0.2.0/tests/test_streaming.py

@@ -0,0 +1,48 @@
+from io import BytesIO
+
+from hyperclass import App, div, event, id, partial, post, stream
+
+
+def test_event_stream_escapes_text_and_renders_hyperclass_partials():
+    response = stream(
+        [
+            "<thinking>",
+            event(partial(div("Hello", id=id.message[7]), id=id.message[7]), name="done"),
+        ]
+    )
+    assert list(response.iter_text()) == [
+        "data: &lt;thinking&gt;\n\n",
+        "event: done\ndata: <hx-partial id=\"message-7\"><div id=\"message-7\">Hello</div></hx-partial>\n\n",
+    ]
+
+
+def test_lite_serves_streaming_responses_without_content_length():
+    class StreamingApp(App):
+        @post("/reply")
+        def reply(self, request):
+            return stream([div("one"), event(div("two"), name="done")])
+
+    statuses = []
+    headers = []
+
+    def start_response(status, values):
+        statuses.append(status)
+        headers.extend(values)
+
+    environ = {
+        "REQUEST_METHOD": "POST",
+        "PATH_INFO": "/reply",
+        "QUERY_STRING": "",
+        "CONTENT_TYPE": "application/x-www-form-urlencoded",
+        "CONTENT_LENGTH": "0",
+        "wsgi.input": BytesIO(),
+        "HTTP_HX_REQUEST": "true",
+    }
+    chunks = list(StreamingApp()(environ, start_response))
+    assert statuses == ["200 OK"]
+    assert ("Content-Type", "text/event-stream; charset=utf-8") in headers
+    assert not any(name == "Content-Length" for name, _ in headers)
+    assert chunks == [
+        b"data: <div>one</div>\n\n",
+        b"event: done\ndata: <div>two</div>\n\n",
+    ]

hyperclass-0.1.1/tests/test_htmx.py

@@ -1,42 +0,0 @@
-from hyperclass import closest, div, hx, id, name, outer_morph, render
-
-
-class counter(div):
-    pass
-
-
-def test_htmx_request_attributes_accept_class_selectors():
-    value = div(
-        "Update",
-        hx=hx.post(
-            "/counter",
-            target=closest(counter),
-            swap=outer_morph,
-        ),
-    )
-    assert render(value) == (
-        '<div hx-post="/counter" hx-target="closest .counter" '
-        'hx-swap="outerMorph">Update</div>'
-    )
-
-
-def test_plain_class_target_becomes_a_selector():
-    assert render(div(hx=hx.get("/counter", target=counter))) == (
-        '<div hx-get="/counter" hx-target=".counter"></div>'
-    )
-
-
-def test_class_attributes_can_declare_htmx_and_name_selectors():
-    class live_search(div):
-        hx = hx.get(
-            "/search",
-            include=name.query,
-            target=id.results,
-            swap=outer_morph,
-        )
-
-    assert render(live_search()) == (
-        '<div class="live-search" hx-get="/search" '
-        'hx-include="[name=&quot;query&quot;]" hx-target="#results" '
-        'hx-swap="outerMorph"></div>'
-    )

hyperclass-0.1.1/tests/test_package.py

@@ -1,5 +0,0 @@
-import hyperclass
-
-
-def test_version():
-    assert hyperclass.__version__ == "0.1.1"