hyperclass 0.0.4__tar.gz → 0.1.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyperclass
-Version: 0.0.4
+Version: 0.1.0
 Summary: Build interactive web applications as Python class hierarchies.
 Author: Grant Jenks
 License-Expression: Apache-2.0
@@ -23,7 +23,13 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Provides-Extra: flask
+Requires-Dist: Flask>=3.1; extra == "flask"
+Provides-Extra: django
+Requires-Dist: Django>=5.2; extra == "django"
 Provides-Extra: dev
+Requires-Dist: Django>=5.2; extra == "dev"
+Requires-Dist: Flask>=3.1; extra == "dev"
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: nox>=2024.4.15; extra == "dev"
 Dynamic: license-file
@@ -37,10 +43,14 @@ Python class hierarchies.
 
 HTML elements are Python base classes. Python subclasses become CSS classes.
 Styles follow inheritance. Routes are methods. Decorated handlers are URLs.
-Interaction is ordinary HTTP over WSGI, with htmx 4 in the browser.
+Interaction is ordinary HTTP, with htmx 4 in the browser. Run it with the tiny
+built-in WSGI host, or put the same components and routes inside Flask or
+Django.
 
 ~~~console
 pip install hyperclass
+# or: pip install "hyperclass[flask]"
+# or: pip install "hyperclass[django]"
 ~~~
 
 ## Sixty-second tour
@@ -83,7 +93,7 @@ class Guest:
     name: str
 
 
-class guestbook(App):
+class GuestbookRoutes:
     @get("/")
     def index(self, request):
         return card(
@@ -102,6 +112,10 @@ class guestbook(App):
         return card(f"Hello, {form.name}!")
 
 
+class guestbook(GuestbookRoutes, App):
+    pass
+
+
 app = guestbook(title="Guestbook")
 ~~~
 
@@ -114,6 +128,10 @@ python -m hyperclass myapp:app
 Then open <http://127.0.0.1:8000>. There is no JavaScript build, template
 language, ASGI dependency, or CSS file hidden elsewhere.
 
+`App` is the zero-dependency host and remains the shortest way to start. The
+HTML, CSS, htmx, selector, route, and form-binding APIs are shared by every
+host.
+
 ## HTML classes are Python classes
 
 Every built-in element can be subclassed:
@@ -239,8 +257,9 @@ class primary_button(button):
     narrow = media(max_width=40 * rem, width="100%")
 ~~~
 
-Pages collect only the rules used by their element tree. Python inheritance and
-the CSS cascade cooperate instead of imitating one another.
+Pages collect only the rules used by their element tree. Rules use the concrete
+semantic class chain as their selector, so Python inheritance and the CSS
+cascade cooperate even when new component styles arrive later.
 
 ## Classes, IDs, and names are selectors
 
@@ -296,7 +315,7 @@ class bookmarks(App):
         return bookmark_card(...)
 ~~~
 
-Decorated handlers retain their route metadata:
+Decorated handlers retain their route metadata. Their URLs are lazy values:
 
 ~~~python
 bookmarks.toggle.url(bookmark_id=42)
@@ -311,6 +330,9 @@ hx.patch(
 
 Typed path parameters are converted before the handler runs. Query strings can
 be attached with `.url(query={...})` or the `query=` option on an htmx request.
+The URL is resolved only while rendering, so a Flask mount prefix or Django URL
+namespace is included automatically. Components never need to know where their
+application was mounted.
 
 ## Forms bind to dataclasses
 
@@ -334,16 +356,20 @@ class bookmarks(App):
 Binding supports strings, integers, floats, booleans, optional values, and
 lists or tuples of those values. Dataclass defaults remain defaults. Invalid or
 missing required values produce a `400 Bad Request`; application validation can
-return a more specific `Response`.
+return `(body, status)`.
+
+The lightweight host also exposes `request.form` and `request.query`. Flask and
+Django handlers receive their native request objects, so use `request.form` and
+`request.args` in Flask or `request.POST` and `request.GET` in Django. Their
+Werkzeug `MultiDict` and Django `QueryDict` values feed the same dataclass
+binder without a request wrapper.
 
-The underlying values remain available as `request.form`, `request.query`,
-`.get(...)`, `.getlist(...)`, and `.int(...)` when explicit parsing is clearer.
-Those accessors accept first-class `name.*` objects as well as strings.
+## Three hosts, one component model
 
-## WSGI and htmx 4
+### Lightweight
 
-A Hyperclass application is a normal WSGI callable. Use the standard-library
-development server:
+Top-level `App` is a deliberately small, dependency-free WSGI application. Use
+the standard-library development server:
 
 ~~~console
 python -m hyperclass package.module:app
@@ -354,10 +380,67 @@ Production can use any WSGI server. Returning an element from an ordinary
 browser request wraps it in a complete page. Returning the same element to an
 htmx request sends only the fragment to swap.
 
+The explicit import is `from hyperclass.lite import App`; top-level
+`from hyperclass import App` is its convenient and backward-compatible alias.
+
+### Flask
+
+Install `hyperclass[flask]`, then subclass the native Flask host:
+
+~~~python
+from hyperclass.flask import App
+
+
+class guestbook(GuestbookRoutes, App):
+    pass
+
+
+app = guestbook(title="Guestbook")
+~~~
+
+`hyperclass.flask.App` is a real `flask.Flask` subclass. Route handlers receive
+Flask's request object, native Flask responses pass through unchanged, and
+Flask extensions, middleware, test clients, and WSGI deployment continue to
+work normally. Hyperclass route references use `url_for()` when rendered.
+
+### Django
+
+Install `hyperclass[django]`, create the route application, and include it in a
+normal Django URLconf:
+
+~~~python
+from django.urls import include, path
+from hyperclass.django import App
+
+
+class guestbook(GuestbookRoutes, App):
+    pass
+
+
+guestbook_app = guestbook(title="Guestbook", namespace="guestbook")
+
+urlpatterns = [
+    path("guestbook/", include(guestbook_app.urls)),
+]
+~~~
+
+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.
+
+### htmx 4
+
 `Page(...)` controls the document explicitly. Pages include a pinned htmx 4
 asset from jsDelivr. htmx 4 `<hx-partial>` responses can update several
 object-selected regions from one request.
 
+When an htmx response introduces a component that was not present on the first
+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.
+
 ## Try the examples
 
 Clone the repository and run the persistent SQLite bookmark inbox:
@@ -366,11 +449,13 @@ Clone the repository and run the persistent SQLite bookmark inbox:
 git clone https://github.com/grantjenks/python-hyperclass
 cd python-hyperclass
 python -m hyperclass examples.bookmarks:app
+# Flask: flask --app examples.bookmarks_flask run
 ~~~
 
 The bookmark app adds, searches, filters, edits, marks, and deletes bookmarks.
-Its implementation is Python plus SQLite, WSGI, generated CSS, and htmx. It is
-also a compact integration test for the framework's ideas.
+Its route mixin and component tree are shared by Lite, Flask, and Django. The
+same browser contract adds, toggles, edits, searches, and deletes a bookmark on
+all three hosts.
 
 For the smallest example:
 
@@ -390,8 +475,27 @@ python -m hyperclass examples.counter:app
   client component lifecycle.
 - **Output should be boring.** Generated markup stays readable in View Source
   and DevTools.
-- **Small is a feature.** Prefer the standard library, WSGI, and a pinned htmx
-  asset over a framework stack.
+- **Choose your host.** Start with the standard library, or use Flask/Django
+  where their ecosystem and infrastructure are already the right answer.
+
+## Development
+
+Run the Python test matrix locally with:
+
+~~~console
+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:
+
+~~~console
+uvx nox -s browser
+~~~
+
+Playwright is used only by that development session and is not a Hyperclass
+runtime dependency.
 
 ## Status
 

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

@@ -7,10 +7,14 @@ Python class hierarchies.
 
 HTML elements are Python base classes. Python subclasses become CSS classes.
 Styles follow inheritance. Routes are methods. Decorated handlers are URLs.
-Interaction is ordinary HTTP over WSGI, with htmx 4 in the browser.
+Interaction is ordinary HTTP, with htmx 4 in the browser. Run it with the tiny
+built-in WSGI host, or put the same components and routes inside Flask or
+Django.
 
 ~~~console
 pip install hyperclass
+# or: pip install "hyperclass[flask]"
+# or: pip install "hyperclass[django]"
 ~~~
 
 ## Sixty-second tour
@@ -53,7 +57,7 @@ class Guest:
     name: str
 
 
-class guestbook(App):
+class GuestbookRoutes:
     @get("/")
     def index(self, request):
         return card(
@@ -72,6 +76,10 @@ class guestbook(App):
         return card(f"Hello, {form.name}!")
 
 
+class guestbook(GuestbookRoutes, App):
+    pass
+
+
 app = guestbook(title="Guestbook")
 ~~~
 
@@ -84,6 +92,10 @@ python -m hyperclass myapp:app
 Then open <http://127.0.0.1:8000>. There is no JavaScript build, template
 language, ASGI dependency, or CSS file hidden elsewhere.
 
+`App` is the zero-dependency host and remains the shortest way to start. The
+HTML, CSS, htmx, selector, route, and form-binding APIs are shared by every
+host.
+
 ## HTML classes are Python classes
 
 Every built-in element can be subclassed:
@@ -209,8 +221,9 @@ class primary_button(button):
     narrow = media(max_width=40 * rem, width="100%")
 ~~~
 
-Pages collect only the rules used by their element tree. Python inheritance and
-the CSS cascade cooperate instead of imitating one another.
+Pages collect only the rules used by their element tree. Rules use the concrete
+semantic class chain as their selector, so Python inheritance and the CSS
+cascade cooperate even when new component styles arrive later.
 
 ## Classes, IDs, and names are selectors
 
@@ -266,7 +279,7 @@ class bookmarks(App):
         return bookmark_card(...)
 ~~~
 
-Decorated handlers retain their route metadata:
+Decorated handlers retain their route metadata. Their URLs are lazy values:
 
 ~~~python
 bookmarks.toggle.url(bookmark_id=42)
@@ -281,6 +294,9 @@ hx.patch(
 
 Typed path parameters are converted before the handler runs. Query strings can
 be attached with `.url(query={...})` or the `query=` option on an htmx request.
+The URL is resolved only while rendering, so a Flask mount prefix or Django URL
+namespace is included automatically. Components never need to know where their
+application was mounted.
 
 ## Forms bind to dataclasses
 
@@ -304,16 +320,20 @@ class bookmarks(App):
 Binding supports strings, integers, floats, booleans, optional values, and
 lists or tuples of those values. Dataclass defaults remain defaults. Invalid or
 missing required values produce a `400 Bad Request`; application validation can
-return a more specific `Response`.
+return `(body, status)`.
+
+The lightweight host also exposes `request.form` and `request.query`. Flask and
+Django handlers receive their native request objects, so use `request.form` and
+`request.args` in Flask or `request.POST` and `request.GET` in Django. Their
+Werkzeug `MultiDict` and Django `QueryDict` values feed the same dataclass
+binder without a request wrapper.
 
-The underlying values remain available as `request.form`, `request.query`,
-`.get(...)`, `.getlist(...)`, and `.int(...)` when explicit parsing is clearer.
-Those accessors accept first-class `name.*` objects as well as strings.
+## Three hosts, one component model
 
-## WSGI and htmx 4
+### Lightweight
 
-A Hyperclass application is a normal WSGI callable. Use the standard-library
-development server:
+Top-level `App` is a deliberately small, dependency-free WSGI application. Use
+the standard-library development server:
 
 ~~~console
 python -m hyperclass package.module:app
@@ -324,10 +344,67 @@ Production can use any WSGI server. Returning an element from an ordinary
 browser request wraps it in a complete page. Returning the same element to an
 htmx request sends only the fragment to swap.
 
+The explicit import is `from hyperclass.lite import App`; top-level
+`from hyperclass import App` is its convenient and backward-compatible alias.
+
+### Flask
+
+Install `hyperclass[flask]`, then subclass the native Flask host:
+
+~~~python
+from hyperclass.flask import App
+
+
+class guestbook(GuestbookRoutes, App):
+    pass
+
+
+app = guestbook(title="Guestbook")
+~~~
+
+`hyperclass.flask.App` is a real `flask.Flask` subclass. Route handlers receive
+Flask's request object, native Flask responses pass through unchanged, and
+Flask extensions, middleware, test clients, and WSGI deployment continue to
+work normally. Hyperclass route references use `url_for()` when rendered.
+
+### Django
+
+Install `hyperclass[django]`, create the route application, and include it in a
+normal Django URLconf:
+
+~~~python
+from django.urls import include, path
+from hyperclass.django import App
+
+
+class guestbook(GuestbookRoutes, App):
+    pass
+
+
+guestbook_app = guestbook(title="Guestbook", namespace="guestbook")
+
+urlpatterns = [
+    path("guestbook/", include(guestbook_app.urls)),
+]
+~~~
+
+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.
+
+### htmx 4
+
 `Page(...)` controls the document explicitly. Pages include a pinned htmx 4
 asset from jsDelivr. htmx 4 `<hx-partial>` responses can update several
 object-selected regions from one request.
 
+When an htmx response introduces a component that was not present on the first
+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.
+
 ## Try the examples
 
 Clone the repository and run the persistent SQLite bookmark inbox:
@@ -336,11 +413,13 @@ Clone the repository and run the persistent SQLite bookmark inbox:
 git clone https://github.com/grantjenks/python-hyperclass
 cd python-hyperclass
 python -m hyperclass examples.bookmarks:app
+# Flask: flask --app examples.bookmarks_flask run
 ~~~
 
 The bookmark app adds, searches, filters, edits, marks, and deletes bookmarks.
-Its implementation is Python plus SQLite, WSGI, generated CSS, and htmx. It is
-also a compact integration test for the framework's ideas.
+Its route mixin and component tree are shared by Lite, Flask, and Django. The
+same browser contract adds, toggles, edits, searches, and deletes a bookmark on
+all three hosts.
 
 For the smallest example:
 
@@ -360,8 +439,27 @@ python -m hyperclass examples.counter:app
   client component lifecycle.
 - **Output should be boring.** Generated markup stays readable in View Source
   and DevTools.
-- **Small is a feature.** Prefer the standard library, WSGI, and a pinned htmx
-  asset over a framework stack.
+- **Choose your host.** Start with the standard library, or use Flask/Django
+  where their ecosystem and infrastructure are already the right answer.
+
+## Development
+
+Run the Python test matrix locally with:
+
+~~~console
+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:
+
+~~~console
+uvx nox -s browser
+~~~
+
+Playwright is used only by that development session and is not a Hyperclass
+runtime dependency.
 
 ## Status
 

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

@@ -46,13 +46,14 @@ from .htmx import (
 from .htmx import (
     delete as delete_swap,
 )
-from .wsgi import (
+from .lite import (
     App,
     BoundEndpoint,
     Endpoint,
     Request,
     Response,
     Route,
+    RouteURL,
     Values,
     get,
     patch,
@@ -62,7 +63,7 @@ from .wsgi import (
 )
 from .wsgi import delete as delete_route
 
-__version__ = "0.0.4"
+__version__ = "0.1.0"
 
 hidden = "hidden"
 submit = "submit"
@@ -84,6 +85,7 @@ __all__ = [
     "Request",
     "Response",
     "Route",
+    "RouteURL",
     "Style",
     "Target",
     "Unit",

hyperclass-0.1.0/hyperclass/binding.py

@@ -0,0 +1,116 @@
+"""Bind form-like multidicts to typed dataclasses."""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Iterator, Mapping
+from dataclasses import MISSING, fields, is_dataclass
+from types import UnionType
+from typing import Any, Protocol, Union, get_args, get_origin, get_type_hints
+
+
+class MultiValues(Protocol):
+    def getlist(self, key: Any) -> list[Any]: ...
+
+
+class Values(Mapping[str, str]):
+    def __init__(self, values: Mapping[str, list[str]] | None = None):
+        self._values = dict(values or {})
+
+    def __getitem__(self, key: Any) -> str:
+        return self._values[str(key)][-1]
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._values)
+
+    def __len__(self) -> int:
+        return len(self._values)
+
+    def get(self, key: Any, default: Any = None) -> Any:
+        values = self._values.get(str(key))
+        return values[-1] if values else default
+
+    def getlist(self, key: Any) -> list[str]:
+        return list(self._values.get(str(key), ()))
+
+    def int(self, key: Any, default: int | None = None) -> int:
+        value = self.get(key)
+        if value is None:
+            if default is not None:
+                return default
+            raise ValueError(f"missing integer form value: {key}")
+        try:
+            return int(value)
+        except ValueError as error:
+            raise ValueError(
+                f"invalid integer form value for {key}: {value!r}"
+            ) from error
+
+    def bind(self, model: type[Any]) -> Any:
+        return bind(self, model)
+
+
+def bind(values: MultiValues, model: type[Any]) -> Any:
+    """Build a dataclass from any Werkzeug/Django-style multidict."""
+
+    if not isinstance(model, type) or not is_dataclass(model):
+        raise TypeError("values can only bind to a dataclass type")
+    hints = get_type_hints(model)
+    arguments: dict[str, Any] = {}
+    for field in fields(model):
+        annotation = hints.get(field.name, field.type)
+        raw = [str(value) for value in values.getlist(field.name)]
+        if not raw:
+            if field.default is not MISSING or field.default_factory is not MISSING:
+                continue
+            if _optional(annotation):
+                arguments[field.name] = None
+            elif annotation is bool:
+                arguments[field.name] = False
+            else:
+                raise ValueError(f"missing form value: {field.name}")
+            continue
+        try:
+            arguments[field.name] = _convert_values(raw, annotation)
+        except (TypeError, ValueError) as error:
+            raise ValueError(
+                f"invalid form value for {field.name}: {raw[-1]!r}"
+            ) from error
+    return model(**arguments)
+
+
+def _optional(annotation: Any) -> bool:
+    return get_origin(annotation) in (Union, UnionType) and type(None) in get_args(
+        annotation
+    )
+
+
+def _convert_values(values: list[str], annotation: Any) -> Any:
+    origin = get_origin(annotation)
+    arguments = get_args(annotation)
+    if origin in (list, tuple):
+        item_type = arguments[0] if arguments else str
+        converted = [_convert_value(value, item_type) for value in values]
+        return converted if origin is list else tuple(converted)
+    if _optional(annotation):
+        item_type = next(value for value in arguments if value is not type(None))
+        return None if values[-1] == "" else _convert_value(values[-1], item_type)
+    return _convert_value(values[-1], annotation)
+
+
+def _convert_value(value: str, annotation: Any) -> Any:
+    if annotation in (Any, inspect.Parameter.empty, str):
+        return value
+    if annotation is bool:
+        normalized = value.lower()
+        if normalized in {"1", "true", "yes", "on"}:
+            return True
+        if normalized in {"0", "false", "no", "off", ""}:
+            return False
+        raise ValueError(value)
+    if annotation in (int, float):
+        return annotation(value)
+    raise TypeError(f"unsupported form type: {annotation!r}")
+
+
+__all__ = ["MultiValues", "Values", "bind"]