hyperclass 0.0.1__tar.gz → 0.0.2__tar.gz

{hyperclass-0.0.1 → hyperclass-0.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyperclass
-Version: 0.0.1
+Version: 0.0.2
 Summary: Build interactive web applications as Python class hierarchies.
 Author: Grant Jenks
 License-Expression: Apache-2.0
@@ -85,6 +85,10 @@ Hyperclass treats classes and instances differently:
 - Multiple inheritance composes multiple CSS classes.
 - Classes are also usable as selectors and htmx targets.
 - Instances contain attributes, state, and child content.
+- Typed route parameters turn URL segments into handler arguments.
+- htmx 4 partials can update several object-selected regions from one response.
+- `id.some_name` creates an interned Python reference for `some-name`.
+- Decorated handlers are reversible route references; URLs need not be repeated.
 
 ~~~python
 class compact:
@@ -149,24 +153,23 @@ The class `counter` simultaneously represents:
 
 ## WSGI and htmx
 
-Routes return elements directly:
+Application subclasses collect decorated method routes:
 
 ~~~python
-from hyperclass import App
+from hyperclass import App, get, post
 
-app = App()
 
+class counter_app(App):
+    @get("/")
+    def index(self, request):
+        return counter(0)
 
-@app.get("/")
-def index(request):
-    return counter(0)
-
-
-@app.post("/counter")
-def increment(request):
-    return counter(request.form.int("value") + 1)
+    @post("/counter")
+    def increment(self, request):
+        return counter(request.form.int("value") + 1)
 
 
+app = counter_app()
 if __name__ == "__main__":
     app.run()
 ~~~
@@ -174,10 +177,88 @@ if __name__ == "__main__":
 The application is a normal WSGI callable. The development server can use
 Python's standard library; production deployment can use any WSGI server.
 
+Decorated handlers retain their routing metadata, so application code can refer
+to Python rather than repeat URL strings:
+
+~~~python
+hx.patch(
+    increment,
+    target=closest(counter),
+    swap=outer_morph,
+)
+~~~
+
+Typed path parameters are supplied alongside htmx options. Class attributes
+make the handler available to components without a route registry:
+
+~~~python
+hx.patch(
+    bookmarks.toggle,
+    bookmark_id=bookmark.id,
+    target=closest(bookmark_card),
+)
+~~~
+
+The same endpoint exposes `.url(...)` for ordinary links and form actions. IDs
+work similarly: `id.unread_count` renders as `unread-count` in an HTML
+attribute and as `#unread-count` when used as a selector.
+
 htmx supplies browser-to-server interaction without introducing a client-side
 component runtime. Hyperclass should favor native HTML and CSS for local
 behavior and use htmx when the server needs to participate.
 
+## Pages
+
+For ordinary browser requests, returning an element wraps it in a complete page.
+For htmx requests, the same route returns only the fragment to swap. Use
+`Page` when you want to control the document explicitly:
+
+~~~python
+from hyperclass import Page
+
+return Page(counter(0), title="Counter")
+~~~
+
+Pages collect the styles used by their element tree and include pinned htmx
+4.0.0 from its CDN.
+
+## Responsive CSS and states
+
+Pseudo-states and media rules are ordinary class attributes:
+
+~~~python
+from hyperclass import css, media, rem
+
+
+class primary_button(button):
+    style = css(background="#6d28d9", color="white")
+    hover = css(background="#5b21b6")
+    focus_visible = css(outline="3px solid #c4b5fd")
+    narrow = media(max_width=40 * rem, width="100%")
+~~~
+
+State names translate underscores to CSS hyphens, and named media rules can use
+Python values for width, orientation, and color-scheme conditions. They follow
+the same inheritance and collection rules as base styles.
+
+## Try the examples
+
+The repository includes the counter and a complete SQLite bookmark inbox:
+
+~~~console
+git clone https://github.com/grantjenks/python-hyperclass
+cd python-hyperclass
+python -m examples.bookmarks
+~~~
+
+Then open <http://127.0.0.1:8000>. The bookmark app supports adding, filtering,
+marking read or unread, and deleting bookmarks. Its implementation is still only
+Python and the standard library: semantic subclasses style read and unread
+cards, routes such as `/bookmarks/<int:bookmark_id>` receive typed arguments,
+and htmx 4 `<hx-partial>` responses update a card and the unread count together.
+
+Use `python -m examples.counter` for the smaller introduction.
+
 ## Principles
 
 - **Python is the authoring language.** Control flow, composition, inheritance,
@@ -195,5 +276,8 @@ behavior and use htmx when the server needs to participate.
 
 ## Status
 
-Hyperclass is currently a design exploration. The examples above describe the
-intended direction, not a released API.
+Version 0.0.2 is the first working vertical slice: HTML elements, semantic
+subclasses, inherited and responsive CSS, object and ID selectors, htmx
+attributes and partials, pages, request parsing, reversible typed WSGI routing,
+class-based applications, and a persistent example application. The API remains
+deliberately pre-alpha.

{hyperclass-0.0.1 → hyperclass-0.0.2}/README.md

@@ -55,6 +55,10 @@ Hyperclass treats classes and instances differently:
 - Multiple inheritance composes multiple CSS classes.
 - Classes are also usable as selectors and htmx targets.
 - Instances contain attributes, state, and child content.
+- Typed route parameters turn URL segments into handler arguments.
+- htmx 4 partials can update several object-selected regions from one response.
+- `id.some_name` creates an interned Python reference for `some-name`.
+- Decorated handlers are reversible route references; URLs need not be repeated.
 
 ~~~python
 class compact:
@@ -119,24 +123,23 @@ The class `counter` simultaneously represents:
 
 ## WSGI and htmx
 
-Routes return elements directly:
+Application subclasses collect decorated method routes:
 
 ~~~python
-from hyperclass import App
+from hyperclass import App, get, post
 
-app = App()
 
+class counter_app(App):
+    @get("/")
+    def index(self, request):
+        return counter(0)
 
-@app.get("/")
-def index(request):
-    return counter(0)
-
-
-@app.post("/counter")
-def increment(request):
-    return counter(request.form.int("value") + 1)
+    @post("/counter")
+    def increment(self, request):
+        return counter(request.form.int("value") + 1)
 
 
+app = counter_app()
 if __name__ == "__main__":
     app.run()
 ~~~
@@ -144,10 +147,88 @@ if __name__ == "__main__":
 The application is a normal WSGI callable. The development server can use
 Python's standard library; production deployment can use any WSGI server.
 
+Decorated handlers retain their routing metadata, so application code can refer
+to Python rather than repeat URL strings:
+
+~~~python
+hx.patch(
+    increment,
+    target=closest(counter),
+    swap=outer_morph,
+)
+~~~
+
+Typed path parameters are supplied alongside htmx options. Class attributes
+make the handler available to components without a route registry:
+
+~~~python
+hx.patch(
+    bookmarks.toggle,
+    bookmark_id=bookmark.id,
+    target=closest(bookmark_card),
+)
+~~~
+
+The same endpoint exposes `.url(...)` for ordinary links and form actions. IDs
+work similarly: `id.unread_count` renders as `unread-count` in an HTML
+attribute and as `#unread-count` when used as a selector.
+
 htmx supplies browser-to-server interaction without introducing a client-side
 component runtime. Hyperclass should favor native HTML and CSS for local
 behavior and use htmx when the server needs to participate.
 
+## Pages
+
+For ordinary browser requests, returning an element wraps it in a complete page.
+For htmx requests, the same route returns only the fragment to swap. Use
+`Page` when you want to control the document explicitly:
+
+~~~python
+from hyperclass import Page
+
+return Page(counter(0), title="Counter")
+~~~
+
+Pages collect the styles used by their element tree and include pinned htmx
+4.0.0 from its CDN.
+
+## Responsive CSS and states
+
+Pseudo-states and media rules are ordinary class attributes:
+
+~~~python
+from hyperclass import css, media, rem
+
+
+class primary_button(button):
+    style = css(background="#6d28d9", color="white")
+    hover = css(background="#5b21b6")
+    focus_visible = css(outline="3px solid #c4b5fd")
+    narrow = media(max_width=40 * rem, width="100%")
+~~~
+
+State names translate underscores to CSS hyphens, and named media rules can use
+Python values for width, orientation, and color-scheme conditions. They follow
+the same inheritance and collection rules as base styles.
+
+## Try the examples
+
+The repository includes the counter and a complete SQLite bookmark inbox:
+
+~~~console
+git clone https://github.com/grantjenks/python-hyperclass
+cd python-hyperclass
+python -m examples.bookmarks
+~~~
+
+Then open <http://127.0.0.1:8000>. The bookmark app supports adding, filtering,
+marking read or unread, and deleting bookmarks. Its implementation is still only
+Python and the standard library: semantic subclasses style read and unread
+cards, routes such as `/bookmarks/<int:bookmark_id>` receive typed arguments,
+and htmx 4 `<hx-partial>` responses update a card and the unread count together.
+
+Use `python -m examples.counter` for the smaller introduction.
+
 ## Principles
 
 - **Python is the authoring language.** Control flow, composition, inheritance,
@@ -165,5 +246,8 @@ behavior and use htmx when the server needs to participate.
 
 ## Status
 
-Hyperclass is currently a design exploration. The examples above describe the
-intended direction, not a released API.
+Version 0.0.2 is the first working vertical slice: HTML elements, semantic
+subclasses, inherited and responsive CSS, object and ID selectors, htmx
+attributes and partials, pages, request parsing, reversible typed WSGI routing,
+class-based applications, and a persistent example application. The API remains
+deliberately pre-alpha.

hyperclass-0.0.2/hyperclass/__init__.py

@@ -0,0 +1,132 @@
+"""Build interactive web applications as Python class hierarchies."""
+
+from . import html as _html
+from .css import (
+    AlphaColor,
+    Color,
+    Length,
+    Media,
+    Style,
+    Unit,
+    block,
+    css,
+    em,
+    flex,
+    grid,
+    inline,
+    media,
+    none,
+    orange,
+    percent,
+    pointer,
+    px,
+    rem,
+    vh,
+    vw,
+)
+from .htmx import (
+    Attributes,
+    Htmx,
+    Target,
+    after,
+    append,
+    before,
+    closest,
+    find,
+    hx,
+    inner_html,
+    inner_morph,
+    next,
+    outer_html,
+    outer_morph,
+    outer_sync,
+    prepend,
+    previous,
+)
+from .htmx import (
+    delete as delete_swap,
+)
+from .wsgi import (
+    App,
+    BoundEndpoint,
+    Endpoint,
+    Request,
+    Response,
+    Route,
+    Values,
+    get,
+    patch,
+    post,
+    put,
+    route,
+)
+from .wsgi import delete as delete_route
+
+__version__ = "0.0.2"
+
+hidden = "hidden"
+submit = "submit"
+
+for _name in _html.__all__:
+    globals()[_name] = getattr(_html, _name)
+
+__all__ = [
+    "__version__",
+    "AlphaColor",
+    "App",
+    "Attributes",
+    "BoundEndpoint",
+    "Color",
+    "Endpoint",
+    "Htmx",
+    "Length",
+    "Media",
+    "Request",
+    "Response",
+    "Route",
+    "Style",
+    "Target",
+    "Unit",
+    "Values",
+    "after",
+    "append",
+    "before",
+    "block",
+    "closest",
+    "css",
+    "delete_swap",
+    "delete_route",
+    "em",
+    "find",
+    "flex",
+    "grid",
+    "get",
+    "hidden",
+    "hx",
+    "inline",
+    "inner_html",
+    "inner_morph",
+    "media",
+    "next",
+    "none",
+    "orange",
+    "outer_html",
+    "outer_morph",
+    "outer_sync",
+    "percent",
+    "pointer",
+    "patch",
+    "prepend",
+    "previous",
+    "post",
+    "put",
+    "px",
+    "rem",
+    "route",
+    "submit",
+    "vh",
+    "vw",
+    *_html.__all__,
+]
+
+del _html, _name

hyperclass-0.0.2/hyperclass/css.py

@@ -0,0 +1,158 @@
+"""Small Python values for authoring CSS."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+def _number(value: int | float) -> str:
+    if isinstance(value, float) and value.is_integer():
+        return str(int(value))
+    return str(value)
+
+
+@dataclass(frozen=True)
+class Unit:
+    """A CSS unit which can be multiplied by a number."""
+
+    suffix: str
+
+    def __rmul__(self, value: int | float) -> Length:
+        return Length(value, self)
+
+
+@dataclass(frozen=True)
+class Length:
+    value: int | float
+    unit: Unit
+
+    def __str__(self) -> str:
+        return f"{_number(self.value)}{self.unit.suffix}"
+
+
+@dataclass(frozen=True)
+class Color:
+    name: str
+    rgb: tuple[int, int, int] | None = None
+
+    def __str__(self) -> str:
+        return self.name
+
+    def fade(self, alpha: float) -> AlphaColor:
+        if not 0 <= alpha <= 1:
+            raise ValueError("alpha must be between 0 and 1")
+        if self.rgb is None:
+            return AlphaColor(self.name, alpha)
+        red, green, blue = self.rgb
+        return AlphaColor(f"{red} {green} {blue}", alpha, rgb=True)
+
+
+@dataclass(frozen=True)
+class AlphaColor:
+    color: str
+    alpha: float
+    rgb: bool = False
+
+    def __str__(self) -> str:
+        if self.rgb:
+            return f"rgb({self.color} / {_number(self.alpha)})"
+        return f"color-mix(in srgb, {self.color} {self.alpha * 100:g}%, transparent)"
+
+
+def css_value(value: Any) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    return str(value)
+
+
+class Style:
+    """An ordered collection of CSS declarations."""
+
+    def __init__(self, **declarations: Any):
+        self.declarations = tuple(
+            (name.replace("_", "-"), value)
+            for name, value in declarations.items()
+            if value is not None
+        )
+
+    def render(self) -> str:
+        return ";".join(
+            f"{name}:{css_value(value)}" for name, value in self.declarations
+        )
+
+    def __str__(self) -> str:
+        return self.render()
+
+
+def css(**declarations: Any) -> Style:
+    return Style(**declarations)
+
+
+@dataclass(frozen=True)
+class Media:
+    """A stylesheet rule guarded by a CSS media query."""
+
+    conditions: tuple[tuple[str, Any], ...]
+    style: Style
+
+    def query(self) -> str:
+        return " and ".join(
+            f"({name.replace('_', '-')}:{css_value(value)})"
+            for name, value in self.conditions
+        )
+
+
+def media(
+    *,
+    min_width: Any = None,
+    max_width: Any = None,
+    orientation: str | None = None,
+    prefers_color_scheme: str | None = None,
+    **declarations: Any,
+) -> Media:
+    """Create a media rule with Python-named conditions and declarations."""
+
+    conditions = tuple(
+        (name, value)
+        for name, value in (
+            ("min_width", min_width),
+            ("max_width", max_width),
+            ("orientation", orientation),
+            ("prefers_color_scheme", prefers_color_scheme),
+        )
+        if value is not None
+    )
+    if not conditions:
+        raise ValueError("media requires at least one condition")
+    return Media(conditions, css(**declarations))
+
+
+PSEUDO_STATES = {
+    "active",
+    "checked",
+    "disabled",
+    "focus",
+    "focus_visible",
+    "focus_within",
+    "hover",
+    "invalid",
+    "visited",
+}
+
+
+px = Unit("px")
+rem = Unit("rem")
+em = Unit("em")
+percent = Unit("%")
+vh = Unit("vh")
+vw = Unit("vw")
+
+orange = Color("orange", (255, 165, 0))
+
+grid = "grid"
+flex = "flex"
+block = "block"
+inline = "inline"
+none = "none"
+pointer = "pointer"