pywebview-htmx 0.4.0__tar.gz → 0.4.2__tar.gz

{pywebview_htmx-0.4.0 → pywebview_htmx-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pywebview-htmx
-Version: 0.4.0
+Version: 0.4.2
 Summary: HTMX-style declarative UI bindings for PyWebview apps
 Author-Email: "B.T. Franklin" <brandon.franklin@gmail.com>
 License: MIT License
@@ -195,6 +195,9 @@ Injects the runtime script tag into an HTML string (idempotent).
 Returns HTML-escaped JSON that is safe to place in a `data-py-params`
 attribute.
 
+Non-finite numbers (`NaN` and positive or negative infinity) raise `ValueError`.
+JSON does not support these values.
+
 ```python
 from pywebview_htmx import encode_params_attr
 
@@ -237,6 +240,9 @@ form submission, link navigation, and submit/reset controls associated with a
 form. Ordinary buttons and the native state changes of checkboxes, radio
 buttons, and labels are preserved.
 
+A label that contains its control calls Python once per activation. Clicking
+the label text still changes the checkbox or radio state.
+
 ### `data-py-params` (optional)
 
 JSON payload passed to Python method.
@@ -319,6 +325,10 @@ newer request had already been issued in the same request scope when the error
 was emitted. Errors from stale requests remain observable even though stale
 successful responses do not update the DOM.
 
+`event.detail.element` identifies the original control. If that control has
+been removed, the runtime dispatches the error on `document.body` so application
+listeners can still receive it.
+
 Example:
 
 ```js
@@ -342,6 +352,9 @@ The `py-wait` selector is resolved for each accepted request. Loading state is
 counted separately per resolved wait element, so a shared spinner stays active
 until every request using that particular element finishes.
 
+The bundled loading styles show `.py-waiting` without blocking pointer input.
+The request policy controls whether another trigger is accepted.
+
 ### `latest-wins` (default)
 
 Multiple rapid requests are allowed; stale responses in the same request state
@@ -352,6 +365,29 @@ scope are ignored. Only the latest request for that scope updates the DOM.
 If a request is already in flight for the same request state scope, new triggers
 are ignored and `py:ignored` is emitted.
 
+### Python Handler Concurrency
+
+`latest-wins` does not cancel Python work. Each accepted call still runs, even
+when its returned HTML is later ignored. PyWebview runs exposed handlers in
+separate threads. Protect shared mutable data with a lock or a database
+transaction when needed.
+
+`drop` applies to the same request scope. It does not prevent calls from other
+scopes from changing the same Python data.
+
+### Bridge Readiness
+
+PyWebview creates the bridge after the document loads. Wait for the
+`pywebviewready` event before starting programmatic calls:
+
+```js
+window.addEventListener("pywebviewready", () => {
+  document.querySelector("#load-button").click();
+});
+```
+
+A call made before the bridge is available emits `py:error`. It is not queued.
+
 ## Dynamic Content Re-processing
 
 After a swap, `pywebview-htmx` automatically scans swapped content for new `py-call`

{pywebview_htmx-0.4.0 → pywebview_htmx-0.4.2}/README.md

@@ -155,6 +155,9 @@ Injects the runtime script tag into an HTML string (idempotent).
 Returns HTML-escaped JSON that is safe to place in a `data-py-params`
 attribute.
 
+Non-finite numbers (`NaN` and positive or negative infinity) raise `ValueError`.
+JSON does not support these values.
+
 ```python
 from pywebview_htmx import encode_params_attr
 
@@ -197,6 +200,9 @@ form submission, link navigation, and submit/reset controls associated with a
 form. Ordinary buttons and the native state changes of checkboxes, radio
 buttons, and labels are preserved.
 
+A label that contains its control calls Python once per activation. Clicking
+the label text still changes the checkbox or radio state.
+
 ### `data-py-params` (optional)
 
 JSON payload passed to Python method.
@@ -279,6 +285,10 @@ newer request had already been issued in the same request scope when the error
 was emitted. Errors from stale requests remain observable even though stale
 successful responses do not update the DOM.
 
+`event.detail.element` identifies the original control. If that control has
+been removed, the runtime dispatches the error on `document.body` so application
+listeners can still receive it.
+
 Example:
 
 ```js
@@ -302,6 +312,9 @@ The `py-wait` selector is resolved for each accepted request. Loading state is
 counted separately per resolved wait element, so a shared spinner stays active
 until every request using that particular element finishes.
 
+The bundled loading styles show `.py-waiting` without blocking pointer input.
+The request policy controls whether another trigger is accepted.
+
 ### `latest-wins` (default)
 
 Multiple rapid requests are allowed; stale responses in the same request state
@@ -312,6 +325,29 @@ scope are ignored. Only the latest request for that scope updates the DOM.
 If a request is already in flight for the same request state scope, new triggers
 are ignored and `py:ignored` is emitted.
 
+### Python Handler Concurrency
+
+`latest-wins` does not cancel Python work. Each accepted call still runs, even
+when its returned HTML is later ignored. PyWebview runs exposed handlers in
+separate threads. Protect shared mutable data with a lock or a database
+transaction when needed.
+
+`drop` applies to the same request scope. It does not prevent calls from other
+scopes from changing the same Python data.
+
+### Bridge Readiness
+
+PyWebview creates the bridge after the document loads. Wait for the
+`pywebviewready` event before starting programmatic calls:
+
+```js
+window.addEventListener("pywebviewready", () => {
+  document.querySelector("#load-button").click();
+});
+```
+
+A call made before the bridge is available emits `py:error`. It is not queued.
+
 ## Dynamic Content Re-processing
 
 After a swap, `pywebview-htmx` automatically scans swapped content for new `py-call`

{pywebview_htmx-0.4.0 → pywebview_htmx-0.4.2}/pyproject.toml

@@ -21,7 +21,7 @@ classifiers = [
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Topic :: Internet :: WWW/HTTP",
 ]
-version = "0.4.0"
+version = "0.4.2"
 
 [project.license]
 file = "LICENSE"
@@ -69,5 +69,6 @@ includes = [
 
 [tool.pdm.scripts]
 test = "pytest"
+test-native = "python tests/native_smoke.py"
 lint = "ruff check ."
 install-browser = "playwright install chromium"

{pywebview_htmx-0.4.0 → pywebview_htmx-0.4.2}/src/pywebview_htmx/runtime.py

@@ -2,24 +2,77 @@ from __future__ import annotations
 
 from importlib.resources import files
 import json
-import re
 from html import escape as html_escape
+from html.parser import HTMLParser
 from typing import Any
 
 import webview
 
-_SCRIPT_TAG_RE = re.compile(
-    r"<script[^>]*\bdata-pywebview-htmx\s*=\s*(?:[\"']true[\"']|true\b)",
-    re.IGNORECASE,
-)
-_THEME_TAG_RE = re.compile(
-    r"<style[^>]*\bdata-pywebview-theme\s*=\s*[\"'](?P<name>[^\"']+)[\"'][^>]*>.*?</style>",
-    re.IGNORECASE | re.DOTALL,
-)
 _THEME_BASE_NAME = "base"
 DEFAULT_THEME = "aurora"
 
 
+class _AssetTags(HTMLParser):
+    """Find active asset tags and closing tags in the original HTML."""
+
+    CDATA_CONTENT_ELEMENTS = (
+        *HTMLParser.CDATA_CONTENT_ELEMENTS, "title", "textarea", "noscript",
+    )
+
+    def __init__(self, html: str) -> None:
+        super().__init__(convert_charrefs=False)
+        self._html = html
+        self._line_starts = [0] + [
+            index + 1 for index, char in enumerate(html) if char == "\n"
+        ]
+        self._template_depth = 0
+        self._theme_start: tuple[int, str] | None = None
+        self.runtime_present = False
+        self.theme: tuple[int, int, str] | None = None
+        self.closing_tags: dict[str, int] = {}
+        self.feed(html)
+        self.close()
+
+    def _offset(self) -> int:
+        line, column = self.getpos()
+        return self._line_starts[line - 1] + column
+
+    def handle_starttag(
+        self, tag: str, attrs: list[tuple[str, str | None]],
+    ) -> None:
+        if tag == "template":
+            self._template_depth += 1
+        if self._template_depth:
+            return
+
+        attributes: dict[str, str | None] = {}
+        for name, value in attrs:
+            attributes.setdefault(name, value)
+        marker = attributes.get("data-pywebview-htmx")
+        if tag == "script" and marker is not None and marker.lower() == "true":
+            self.runtime_present = True
+        if tag == "style" and self.theme is None:
+            theme = attributes.get("data-pywebview-theme")
+            if theme is not None:
+                self._theme_start = (self._offset(), theme)
+
+    def handle_endtag(self, tag: str) -> None:
+        if tag == "template" and self._template_depth:
+            self._template_depth -= 1
+            return
+        if self._template_depth:
+            return
+
+        offset = self._offset()
+        if tag in {"head", "body"}:
+            self.closing_tags[tag] = offset
+        if tag == "style" and self._theme_start is not None:
+            start, theme = self._theme_start
+            end = self._html.index(">", offset) + 1
+            self.theme = (start, end, theme)
+            self._theme_start = None
+
+
 def list_themes() -> list[str]:
     """Return all bundled selectable theme names."""
     themes_dir = files("pywebview_htmx").joinpath("static/themes")
@@ -61,24 +114,21 @@ def get_runtime_script() -> str:
 def encode_params_attr(params: Any) -> str:
     """Encode a payload for safe embedding in ``data-py-params``."""
     return html_escape(
-        json.dumps(params, sort_keys=True),
+        json.dumps(params, sort_keys=True, allow_nan=False),
         quote=True,
     )
 
 
 def inject_runtime(html: str) -> str:
     """Inject the runtime script into an HTML string before ``</body>`` when present."""
-    if _SCRIPT_TAG_RE.search(html):
+    tags = _AssetTags(html)
+    if tags.runtime_present:
         return html
 
     script_content = get_runtime_script()
     injection = f'<script data-pywebview-htmx="true">{script_content}</script>'
 
-    lower_html = html.lower()
-    body_close_idx = lower_html.rfind("</body>")
-    if body_close_idx == -1:
-        return f"{html}{injection}"
-
+    body_close_idx = tags.closing_tags.get("body", len(html))
     return f"{html[:body_close_idx]}{injection}{html[body_close_idx:]}"
 
 
@@ -88,24 +138,18 @@ def inject_theme(html: str, theme: str = DEFAULT_THEME) -> str:
     css = get_theme_css(normalized_theme)
     injection = f'<style data-pywebview-theme="{normalized_theme}">{css}</style>'
 
-    match = _THEME_TAG_RE.search(html)
-    if match:
-        current_theme = match.group("name").strip().lower()
+    tags = _AssetTags(html)
+    if tags.theme is not None:
+        start, end, current_theme = tags.theme
+        current_theme = current_theme.strip().lower()
         if current_theme == normalized_theme:
             return html
-        start, end = match.span()
         return f"{html[:start]}{injection}{html[end:]}"
 
-    lower_html = html.lower()
-    head_close_idx = lower_html.rfind("</head>")
-    if head_close_idx != -1:
-        return f"{html[:head_close_idx]}{injection}{html[head_close_idx:]}"
-
-    body_close_idx = lower_html.rfind("</body>")
-    if body_close_idx != -1:
-        return f"{html[:body_close_idx]}{injection}{html[body_close_idx:]}"
-
-    return f"{injection}{html}"
+    insertion_idx = tags.closing_tags.get(
+        "head", tags.closing_tags.get("body", 0),
+    )
+    return f"{html[:insertion_idx]}{injection}{html[insertion_idx:]}"
 
 
 def create_window(

{pywebview_htmx-0.4.0 → pywebview_htmx-0.4.2}/src/pywebview_htmx/static/runtime.js

@@ -10,6 +10,8 @@
   const selfRequestState = new WeakMap();
   const targetedRequestState = new Map();
   const waitState = new WeakMap();
+  const boundElements = new WeakSet();
+  const pendingLabelControlClicks = new WeakSet();
 
   function $(selector, root = document) {
     if (!selector) return null;
@@ -79,7 +81,7 @@
   }
 
   function serializeForm(form, event) {
-    const params = {};
+    const params = Object.create(null);
     const formData = new FormData(form);
 
     for (const [key, value] of formData.entries()) {
@@ -206,21 +208,44 @@
     elements.push(...root.querySelectorAll("[py-call]"));
 
     elements.forEach((element) => {
-      if (element.getAttribute("data-pywebview-bound") === "true") {
+      if (boundElements.has(element)) {
         return;
       }
-      element.setAttribute("data-pywebview-bound", "true");
 
       const functionName = element.getAttribute("py-call");
       const eventName = element.getAttribute("py-trigger") || "click";
       const targetSelector = (element.getAttribute("py-target") || "").trim() || null;
+      const labelControl = element.tagName === "LABEL" && eventName === "click"
+        ? element.control
+        : null;
 
       if (!functionName) {
         console.warn("PyWebview HTMX: py-call is empty", element);
         return;
       }
+      boundElements.add(element);
 
       element.addEventListener(eventName, async (event) => {
+        if (eventName === "click" && pendingLabelControlClicks.has(element)) {
+          pendingLabelControlClicks.delete(element);
+          return;
+        }
+        if (labelControl && event.target === labelControl) {
+          if (pendingLabelControlClicks.has(labelControl)) {
+            pendingLabelControlClicks.delete(labelControl);
+            return;
+          }
+          if (
+            labelControl.hasAttribute("py-call") &&
+            (labelControl.getAttribute("py-trigger") || "click") === "click"
+          ) {
+            return;
+          }
+        } else if (labelControl && event.target !== labelControl) {
+          pendingLabelControlClicks.add(labelControl);
+          setTimeout(() => pendingLabelControlClicks.delete(labelControl), 0);
+        }
+
         if (shouldPreventDefault(element, eventName) && event.cancelable) {
           event.preventDefault();
         }
@@ -257,7 +282,7 @@
             throw new Error("PyWebview HTMX: Python API methods must return an HTML string");
           }
 
-          const target = targetSelector ? $(targetSelector) : element;
+          let target = targetSelector ? $(targetSelector) : element;
           if (!target) {
             console.warn("PyWebview HTMX: target element not found", targetSelector);
             return;
@@ -271,6 +296,12 @@
             return;
           }
 
+          target = targetSelector ? $(targetSelector) : element;
+          if (!target || !target.isConnected) {
+            console.warn("PyWebview HTMX: target element not found", targetSelector);
+            return;
+          }
+
           const processRoot = pySwap(target, response, swapStyle);
           const afterSwapTarget =
             swapStyle === "outerHTML"
@@ -284,7 +315,9 @@
           }
         } catch (error) {
           console.error("PyWebview HTMX: error calling Python function", error);
-          triggerEvent(element, "py:error", {
+          const errorTarget = element.isConnected ? element : document.body || document;
+          triggerEvent(errorTarget, "py:error", {
+            element,
             error,
             requestId,
             stale: requestId !== state.lastIssued,

{pywebview_htmx-0.4.0 → pywebview_htmx-0.4.2}/src/pywebview_htmx/static/themes/base.css

@@ -258,7 +258,6 @@ body {
 
 .py-waiting {
   opacity: 0.88;
-  pointer-events: none;
 }
 
 .pyh-event-log {

{pywebview_htmx-0.4.0 → pywebview_htmx-0.4.2}/tests/conftest.py

@@ -1,7 +1,5 @@
 from __future__ import annotations
 
-import re
-
 import pytest
 
 from pywebview_htmx import get_runtime_script
@@ -10,8 +8,3 @@ from pywebview_htmx import get_runtime_script
 @pytest.fixture(scope="session")
 def js_source() -> str:
     return get_runtime_script()
-
-
-@pytest.fixture(scope="session")
-def js_compact(js_source: str) -> str:
-    return re.sub(r"\s+", " ", js_source).strip()

pywebview_htmx-0.4.2/tests/native_smoke.py

@@ -0,0 +1,104 @@
+"""Check a real Python bridge in the local desktop renderer."""
+
+from __future__ import annotations
+
+from html import escape
+from threading import Event
+from time import monotonic, sleep
+
+import webview
+
+from pywebview_htmx import create_window, encode_params_attr
+
+
+class API:
+    def __init__(self) -> None:
+        self._done = Event()
+        self._params: dict[str, object] | None = None
+        self._result: dict[str, object] | None = None
+
+    def greeting(self, params: dict[str, object]) -> str:
+        self._params = params
+        return f'<p>Hello, {escape(str(params["name"]))}!</p>'
+
+    def fail(self, params: dict[str, object]) -> str:
+        raise ValueError("Expected native smoke test failure")
+
+    def report(self, result: dict[str, object]) -> str:
+        self._result = result
+        self._done.set()
+        return ""
+
+
+def main() -> None:
+    name = 'İstanbul <bridge> "test"'
+    params = encode_params_attr({"name": name})
+    api = API()
+    html = f"""<!doctype html>
+    <html><head><title>İstanbul</title></head><body>
+      <button id="greeting" py-call="greeting" py-target="#result"
+              data-py-params="{params}">İstanbul</button>
+      <button id="failure" py-call="fail" py-target="#error-result">Fail</button>
+      <div id="result"></div><div id="error-result"></div>
+      <script>
+        document.addEventListener('DOMContentLoaded', () => {{
+          document.body.addEventListener('py:afterSwap', event => {{
+            if (event.target.id === 'result') {{
+              document.querySelector('#failure').click();
+            }}
+          }});
+          document.body.addEventListener('py:error', event => {{
+            pywebview.api.report({{
+              text: document.querySelector('#result').textContent,
+              error: event.detail.error.message,
+              name: event.detail.error.name,
+              element: event.detail.element.id,
+              stale: event.detail.stale
+            }}).then(() => {{ window.nativeReportDone = true; }});
+          }});
+        }});
+      </script>
+    </body></html>"""
+    window = create_window(
+        "pywebview-htmx native smoke test", html, js_api=api,
+        start=False, hidden=True, focus=False,
+    )
+    failures: list[Exception] = []
+    verified = Event()
+
+    def check() -> None:
+        try:
+            if not window.events.loaded.wait(15):
+                raise TimeoutError("The native window did not load")
+            window.evaluate_js("document.querySelector('#greeting').click()")
+            if not api._done.wait(15):
+                raise TimeoutError("The native bridge did not finish")
+            deadline = monotonic() + 15
+            while not window.evaluate_js("window.nativeReportDone === true"):
+                if monotonic() >= deadline:
+                    raise TimeoutError("The native report did not finish")
+                sleep(0.01)
+            assert api._params == {"name": name}, api._params
+            assert api._result == {
+                "text": f"Hello, {name}!",
+                "error": "Expected native smoke test failure",
+                "name": "ValueError",
+                "element": "failure",
+                "stale": False,
+            }, api._result
+            verified.set()
+        except Exception as error:
+            failures.append(error)
+        finally:
+            window.destroy()
+
+    webview.start(check)
+    if failures:
+        raise failures[0]
+    if not verified.is_set():
+        raise RuntimeError("The native smoke test did not complete")
+    print(f"Native smoke test passed ({webview.renderer})")
+
+
+if __name__ == "__main__":
+    main()

pywebview_htmx-0.4.2/tests/test_html_assets_browser.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+import pytest
+from playwright.sync_api import Page
+
+from pywebview_htmx import inject_runtime, inject_theme
+
+
+@pytest.mark.parametrize(
+    "inactive_markup",
+    [
+        '<!-- <script data-pywebview-htmx="true"></script> -->',
+        '<template><script data-pywebview-htmx="true"></script></template>',
+        '<textarea><script data-pywebview-htmx="true"></script></textarea>',
+        '<!-- <style data-pywebview-theme="paper">example</style> -->',
+        '<template><style data-pywebview-theme="paper">example</style></template>',
+    ],
+)
+def test_injected_assets_work_with_unicode_and_inactive_markup(
+    page: Page, inactive_markup: str,
+) -> None:
+    html = (
+        "<html>\n<head><title>İstanbul</title></head>\n<body>"
+        f"{inactive_markup}"
+        '<button id="load" py-call="load" py-target="#result">İstanbul</button>'
+        '<div id="result"></div></body></html><!-- </body> </head> -->'
+    )
+    page_errors: list[str] = []
+    page.on("pageerror", lambda error: page_errors.append(str(error)))
+    page.set_content(inject_runtime(inject_theme(html)))
+    page.evaluate(
+        """() => {
+          window.pywebview = {api: {load: () => '<p>İstanbul loaded</p>'}};
+        }"""
+    )
+
+    page.locator("#load").click()
+    page.locator("#result").get_by_text("İstanbul loaded").wait_for()
+    assert page.title() == "İstanbul"
+    assert page.locator('body > script[data-pywebview-htmx="true"]').count() == 1
+    assert page.locator('head > style[data-pywebview-theme="aurora"]').count() == 1
+    assert not page_errors