htpy-htmx 0.1.0__tar.gz

htpy_htmx-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,52 @@
+name: tests
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  tests:
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: pytest (3.10)
+            python: "3.10"
+          - name: pytest (3.11)
+            python: "3.11"
+          - name: pytest (3.12)
+            python: "3.12"
+          - name: pytest (3.13)
+            python: "3.13"
+          - name: pytest (3.14)
+            python: "3.14"
+    name: ${{ matrix.name }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          python-version: ${{ matrix.python }}
+          activate-environment: true
+      - run: uv sync
+      - run: uv run --python ${{ matrix.python }} pytest
+
+  mypy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          python-version: "3.10"
+      - run: uv sync
+      - run: uv run mypy .
+
+  black:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          python-version: "3.10"
+      - run: uv sync
+      - run: uv run black --check .

htpy_htmx-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.idea
+__pycache__
+.venv
+build
+*.egg-info
+dist

htpy_htmx-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,20 @@
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+repos:
+-   repo: https://github.com/psf/black
+    rev: 26.5.1
+    hooks:
+    -   id: black
+-   repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v2.3.0
+    hooks:
+    -   id: mypy
+-   repo: local
+    hooks:
+    -   id: pytest
+        name: pytest
+        entry: ./.venv/bin/pytest
+        language: system
+        types: [python]
+        pass_filenames: false
+        always_run: true

htpy_htmx-0.1.0/LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 August Malmdahl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

htpy_htmx-0.1.0/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: htpy-htmx
+Version: 0.1.0
+Summary: Helpers for using htmx in htpy
+Author-email: August Malmdahl <august.malmdahl@gmail.com>
+Project-URL: Repository, https://github.com/augustifolia/htpy-htmx
+Project-URL: Issues, https://github.com/augustifolia/htpy-htmx/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENCE
+Requires-Dist: htpy
+Dynamic: license-file
+
+# htpy-htmx
+
+htpy-htmx is a library to make it easier to work with [htmx](https://four.htmx.org/) in [htpy](https://htpy.dev/).
+
+This library is intended to work with htmx 4.
+
+Note: This project is still a work in progress and there may be breaking changes.
+
+## Usage
+
+You can import htpy-htmx as htpy_htmx.hx. All normal htmx attributes are available from the module,
+but without the "hx-" prefix. So `hx-get="url"` would become `hx.get("url")`.
+
+Some htmx extension attributes are available in the htpy_htmx.ext module.
+
+```python
+import htpy as h
+from htpy_htmx import hx
+from htpy_htmx import ext
+
+# pass htmx attributes as functions
+h.div("#div-id", hx.get("/some-url/"), hx.trigger("click"))
+
+# hx-partial is also available as a htpy element
+h.div("#div-id")[
+    h.h2["header"],
+    hx.partial("#part-id", hx.target("#some-element"))[
+        h.div("#div1")[
+            h.p["part one"]
+        ]
+    ],
+]
+
+h.div(
+    # trigger allows a list of trigger events
+    hx.trigger("blur", "keyup[key=='Enter']"),
+    # swap takes a swap style as string and modifiers as keyword arguments
+    hx.swap("before", swap="1s", scroll="bottom"),
+    # hx-on takes an event and a JavaScript expression
+    hx.on("htmx:before:request", "showSpinner()"),
+    # vals takes a dict of data.
+    # To evaluate JavaScript, wrap your js expression in hx.JS() and pass js=True.
+    hx.vals({"foo": "bar", "some_js": hx.JS("getSomeData()")}, js=True),
+)
+
+# to enable inheritance pass inherited=True to a hx-function
+h.div(hx.confirm("Are you sure?", inherited=True))[
+    h.button(hx.delete("/account"))["Delete My Account"],
+    h.button(hx.put("/account"))["Update My Account"],
+]
+
+# Some extension attributes are available in ext:
+h.div(
+    ext.preload("touchstart"),
+    ext.optimistic("#msg-opt"),
+    ext.ws(connect="click"),
+)
+```
+
+## Installation
+
+To install with pip run:
+
+    pip install htpy-htmx

htpy_htmx-0.1.0/README.md

@@ -0,0 +1,64 @@
+# htpy-htmx
+
+htpy-htmx is a library to make it easier to work with [htmx](https://four.htmx.org/) in [htpy](https://htpy.dev/).
+
+This library is intended to work with htmx 4.
+
+Note: This project is still a work in progress and there may be breaking changes.
+
+## Usage
+
+You can import htpy-htmx as htpy_htmx.hx. All normal htmx attributes are available from the module,
+but without the "hx-" prefix. So `hx-get="url"` would become `hx.get("url")`.
+
+Some htmx extension attributes are available in the htpy_htmx.ext module.
+
+```python
+import htpy as h
+from htpy_htmx import hx
+from htpy_htmx import ext
+
+# pass htmx attributes as functions
+h.div("#div-id", hx.get("/some-url/"), hx.trigger("click"))
+
+# hx-partial is also available as a htpy element
+h.div("#div-id")[
+    h.h2["header"],
+    hx.partial("#part-id", hx.target("#some-element"))[
+        h.div("#div1")[
+            h.p["part one"]
+        ]
+    ],
+]
+
+h.div(
+    # trigger allows a list of trigger events
+    hx.trigger("blur", "keyup[key=='Enter']"),
+    # swap takes a swap style as string and modifiers as keyword arguments
+    hx.swap("before", swap="1s", scroll="bottom"),
+    # hx-on takes an event and a JavaScript expression
+    hx.on("htmx:before:request", "showSpinner()"),
+    # vals takes a dict of data.
+    # To evaluate JavaScript, wrap your js expression in hx.JS() and pass js=True.
+    hx.vals({"foo": "bar", "some_js": hx.JS("getSomeData()")}, js=True),
+)
+
+# to enable inheritance pass inherited=True to a hx-function
+h.div(hx.confirm("Are you sure?", inherited=True))[
+    h.button(hx.delete("/account"))["Delete My Account"],
+    h.button(hx.put("/account"))["Update My Account"],
+]
+
+# Some extension attributes are available in ext:
+h.div(
+    ext.preload("touchstart"),
+    ext.optimistic("#msg-opt"),
+    ext.ws(connect="click"),
+)
+```
+
+## Installation
+
+To install with pip run:
+
+    pip install htpy-htmx

htpy_htmx-0.1.0/htpy_htmx/_types.py

@@ -0,0 +1,107 @@
+from typing import TypeAlias, Literal
+
+_swap_style: TypeAlias = (
+    str  # This allows extensions to add new swap_styles (like upsert and download)
+    | Literal[
+        "innerHTML",
+        "outerHTML",
+        "beforebegin",
+        "before",
+        "afterbegin",
+        "prepend",
+        "beforeend",
+        "append",
+        "afterend",
+        "after",
+        "delete",
+        "none",
+        "innerMorph",
+        "outerMorph",
+        "textContent",
+        "outerSync",
+        # "upsert",  # Requires the hx-upsert extension.
+        # "download",  # Required the hx-download extension.
+    ]
+)
+
+_selector: TypeAlias = (
+    str | Literal["this", "next", "previous", "body", "document", "window", "host"]
+)
+
+_event: TypeAlias = (
+    str
+    | Literal[
+        "load",
+        "revealed",
+        "intersect",
+        "submit",
+        "change",
+        "input",
+        "focus",
+        "blur",
+        "click",
+        "dblclick",
+        "mousedown",
+        "mouseup",
+        "mousemove",
+        "mouseenter",
+        "mouseleave",
+        "wheel",
+        "mousewheel",
+        "keyup",
+        "keydown",
+        "keypress",
+        "dragstart",
+        "drag",
+        "dragend",
+        "dragenter",
+        "dragover",
+        "dragleave",
+        "drop",
+        "play",
+        "pause",
+        "ended",
+        "volumechange",
+        "touchstart",
+        "touchend",
+        "touchmove",
+        "touchcancel",
+        "resize",
+        "scroll",
+        "select",
+        "search",
+        "invalid",
+        "contextmenu",
+        "reset",
+    ]
+)
+
+_htmx_events: TypeAlias = Literal[
+    "htmx:config:request",
+    "htmx:before:request",
+    "htmx:after:request",
+    "htmx:finally:request",
+    "htmx:before:swap",
+    "htmx:after:swap",
+    "htmx:finally:swap",
+    "htmx:before:cleanup",
+    "htmx:after:cleanup",
+    "htmx:confirm",
+    "htmx:error",
+    "htmx:abort",
+    "htmx:before:init",
+    "htmx:after:init",
+    "htmx:before:process",
+    "htmx:after:process",
+    "htmx:before:history:update",
+    "htmx:after:history:update",
+    "htmx:after:history:push",
+    "htmx:after:history:replace",
+    "htmx:before:history:restore",
+    "htmx:before:viewTransition",
+    "htmx:after:viewTransition",
+    "htmx:before:response",
+    "htmx:before:settle",
+    "htmx:after:settle",
+    "htmx:response:error",
+]

htpy_htmx-0.1.0/htpy_htmx/ext.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+from typing import Literal
+from ._types import _selector, _event
+
+
+def multipart(*, connect: str, close: _event, inherited: bool = False) -> dict[str, str]:
+    """Stream HTML with multipart/mixed.
+
+    https://four.htmx.org/extensions/hx-multipart
+    """
+    data: dict[str, str] = {}
+    if connect:
+        data[f"hx-multipart:connect{':inherited' if inherited else ''}"] = connect
+    if close:
+        data[f"hx-multipart:close{':inherited' if inherited else ''}"] = close
+    return data
+
+
+def sse(*, connect: _event = "", close: _event = "", inherited: bool = False) -> dict[str, str]:
+    """Stream HTML with text/event-stream (SSE).
+
+    https://four.htmx.org/extensions/hx-sse
+    """
+    data: dict[str, str] = {}
+    if connect:
+        data[f"hx-sse:connect{':inherited' if inherited else ''}"] = connect
+    if close:
+        data[f"hx-sse:close{':inherited' if inherited else ''}"] = close
+    return data
+
+
+def ws(*, connect: _event = "", send: bool = False, inherited: bool = False) -> dict[str, str]:
+    """Stream HTML and send data over WebSockets.
+
+    https://four.htmx.org/extensions/hx-ws
+    """
+    data: dict[str, str] = {}
+    if connect:
+        data[f"hx-ws:connect{':inherited' if inherited else ''}"] = connect
+    if send:
+        data[f"hx-ws:send{':inherited' if inherited else ''}"] = ""
+    return data
+
+
+def live(attribute: str, expression: str, *, inherited: bool = False) -> dict[str, str]:
+    """Add reactive bindings to HTML.
+
+    https://four.htmx.org/extensions/hx-live
+    """
+    return {f"hx-live:{attribute}{':inherited' if inherited else ''}": expression}
+
+
+def optimistic(selector: _selector, *, inherited: bool = False) -> dict[str, str]:
+    """Shows optimistic content during request.
+
+    Note: This is an extension attribute. To use it, you must include the optimistic extension.
+    https://four.htmx.org/reference/attributes/hx-optimistic
+    """
+    return {f"hx-optimistic{':inherited' if inherited else ''}": selector}
+
+
+def browser_indicator(show_indicator: bool = True, *, inherited: bool = False) -> dict[str, str]:
+    """Show tab's spinner with hx-browser-indicator.
+
+    https://four.htmx.org/extensions/hx-browser-indicator
+    """
+    return {f"hx-browser-indicator{':inherited' if inherited else ''}": str(show_indicator).lower()}
+
+
+def prompt(prompt: str, *, inherited: bool = False) -> dict[str, str]:
+    """Prompt before requests with hx-prompt='Reason?'
+
+    https://four.htmx.org/extensions/hx-prompt
+    """
+    return {f"hx-prompt{':inherited' if inherited else ''}": prompt}
+
+
+def preload(
+    event: Literal["mouseenter", "mouseover", "touchstart"], *, inherited: bool = False
+) -> dict[str, str]:
+    """Preloads content before user triggers request.
+
+    Note: This is an extension attribute. To use it, you must include the preload extension.
+    https://four.htmx.org/reference/attributes/hx-preload
+    """
+    return {f"hx-preload{':inherited' if inherited else ''}": event}
+
+
+def ptag(tag: str, *, inherited: bool = False) -> dict[str, str]:
+    """Skip unchanged polls with HX-PTag: "v42".
+
+    https://four.htmx.org/extensions/hx-ptag
+    """
+    return {f"hx-ptag{':inherited' if inherited else ''}": tag}
+
+
+def history(save_to_cache: bool, *, inherited: bool = False) -> dict[str, str]:
+    """Restore back/forward pages from sessionStorage.
+
+    https://four.htmx.org/extensions/hx-history-cache
+    """
+    return {f"hx-history{':inherited' if inherited else ''}": str(save_to_cache).lower()}
+
+
+def head(
+    strategy: Literal["merge", "append", "re-eval"], *, inherited: bool = False
+) -> dict[str, str]:
+    """Merge <head> tags with hx-head='merge'.
+
+    https://four.htmx.org/extensions/hx-head
+    """
+    return {f"hx-head{':inherited' if inherited else ''}": strategy}
+
+
+def targets(*selector: _selector, inherited: bool = False) -> dict[str, str]:
+    """Target many elements.
+
+    Requires the hx-targets extension
+    https://four.htmx.org/extensions/hx-targets
+    """
+    return {f"hx-targets{':inherited' if inherited else ''}": ", ".join(selector)}
+
+
+def nonce(csp_nonce: str, *, inherited: bool = False) -> dict[str, str]:
+    """Make htmx work under strict Content Security Policy.
+
+    https://four.htmx.org/extensions/hx-csp
+    """
+    return {f"hx-nonce{':inherited' if inherited else ''}": csp_nonce}