wtforms-htmx 0.1.0__py3-none-any.whl

wtforms_htmx/tree.py

@@ -0,0 +1,147 @@
+"""Walk the field tree of a form and resolve fields by name or id."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+from typing import TYPE_CHECKING
+
+from wtforms.fields import FieldList
+from wtforms.fields import FormField
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from wtforms import Field
+
+
+_PY_PATH_RE = re.compile(r"[A-Za-z_]\w*(?:\.[A-Za-z_]\w*)*")
+
+_PLAIN_ID_RE = re.compile(r"[A-Za-z_][\w-]*")
+
+
+def _state(field: Any, name: str, default: Any = None) -> Any:
+    """Return the wtforms-htmx attribute ``name`` set on ``field``, or ``default``.
+
+    It reads ``__dict__``: ``FormField.__getattr__`` recurses while its form
+    is being built.
+    """
+    return field.__dict__.get(name, default)
+
+
+def _looks_like_python_path(name: str) -> bool:
+    """Whether ``name`` is a Python identifier path (``"a"``, ``"a.b.c"``).
+
+    Anything else (``#id``, ``.class``, ``closest form``, a dashed name) is
+    a selector.
+    """
+    return _PY_PATH_RE.fullmatch(name) is not None
+
+
+def _fields_of(container: Any) -> dict[str, Any]:
+    """Return the direct fields of a form, a FormField or a FieldList."""
+    # A sub-form still being built must not recurse through FormField.__getattr__.
+    if isinstance(container, FormField):
+        form = container.__dict__.get("form")
+        return form._fields if form is not None else {}
+
+    if isinstance(container, FieldList):
+        entries = container.__dict__.get("entries")
+        return {entry.name: entry for entry in entries} if entries else {}
+
+    return container._fields
+
+
+def _walk_fields(container: Any) -> Iterator[Any]:
+    """Yield every field of ``container``, descending into FieldList and FormField."""
+    for field in _fields_of(container).values():
+        yield field
+        if isinstance(field, FieldList | FormField):
+            yield from _walk_fields(field)
+
+
+def _root_of(form: Any) -> Any:
+    """Walk up ``_parent_form`` links to the top-level form."""
+    while form._parent_form is not None:
+        form = form._parent_form
+
+    return form
+
+
+def _resolve_field_by_id(container: Any, field_id: str) -> Field | None:
+    """Find the field whose ``id`` is ``field_id`` anywhere in the form tree."""
+    return next(
+        (f for f in _walk_fields(container) if getattr(f, "id", None) == field_id),
+        None,
+    )
+
+
+def _resolve_field(container: Any, name: str) -> Field | None:
+    """Find a field by its HTML ``name``, descending into FormField and FieldList."""
+    fields = _fields_of(container)
+    if name in fields:
+        return fields[name]
+
+    remaining = name
+    while True:
+        dash = remaining.rfind("-")
+        if dash == -1:
+            return None
+
+        prefix = remaining[:dash]
+        remaining = prefix
+        if prefix not in fields:
+            continue
+
+        field = fields[prefix]
+        tail = name[len(prefix) + 1 :]
+        if isinstance(field, FieldList):
+            return _descend_into_fieldlist(field, tail)
+
+        if isinstance(field, FormField):
+            return _resolve_field(field, tail)
+
+        return None
+
+
+def _descend_into_fieldlist(field: Any, tail: str) -> Field | None:
+    """Walk into a FieldList's entries from the remaining ``<index>[-rest]`` tail."""
+    idx_str, sep, rest = tail.partition("-")
+    try:
+        idx = int(idx_str)
+    except ValueError:
+        return None
+
+    if idx < 0 or idx >= len(field):
+        return None
+
+    entry = field[idx]
+    if not sep:
+        return entry
+
+    if isinstance(entry, FormField):
+        return _resolve_field(entry, rest)
+
+    return None
+
+
+def _classify_target(host: Any, root: Any, target: str):
+    """Classify a trigger target string.
+
+    Return ``("field", field)`` for a Python path resolved in the *host*
+    scope, or a ``"#id"`` matching a field from the *root*;
+    ``("selector", target)`` for any other selector; ``("unbound", target)``
+    for a Python path that matches no field.
+    """
+    if _looks_like_python_path(target):
+        field = _resolve_field(host, target.replace(".", "-"))
+        return ("field", field) if field is not None else ("unbound", target)
+
+    if (
+        target.startswith("#")
+        and _PLAIN_ID_RE.fullmatch(target[1:])
+        and (field := _resolve_field_by_id(root, target[1:])) is not None
+    ):
+        return ("field", field)
+
+    return ("selector", target)

wtforms_htmx/triggers.py

@@ -0,0 +1,182 @@
+"""Trigger declarations: the ``.triggers()`` and ``.triggered_by()`` field methods."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+from typing import NamedTuple
+from typing import TypeAlias
+
+from wtforms.fields.core import UnboundField
+
+TriggerCallback: TypeAlias = Callable[[Any, Any, Any], Any]
+"""A ``(form, source, target) -> result`` callback of a trigger declaration.
+
+``form`` is the form that holds the declaring field. ``source`` is the
+field that fired, or ``None`` for the ``"*"`` wildcard. ``target`` is a
+field, or the selector string of a DOM target. See :ref:`callback-return`
+for the ``result``.
+"""
+
+
+class _TriggerEntry(NamedTuple):
+    """Per-link declaration set by ``.triggers()`` / ``.triggered_by()``."""
+
+    event: str | None = None
+    """Optional ``hx-trigger`` event override.
+
+    ``None`` defers to the form-wide ``htmx_default_trigger``.
+    """
+
+    callback: TriggerCallback | None = None
+    """Optional ``(form, source, target) -> result`` callback.
+
+    ``None`` means a plain re-render.
+    """
+
+
+def _normalize_trigger_args(
+    target: str | list[str],
+    callback: TriggerCallback | None,
+    on: str | None,
+    *,
+    method_name: str,
+) -> dict[str, _TriggerEntry]:
+    """Turn ``.triggers()`` / ``.triggered_by()`` arguments into ``{name: _TriggerEntry}``.
+
+    Raise on a wrong type, an empty list, or a misplaced wildcard.
+    """
+    if on is not None and not isinstance(on, str):
+        raise TypeError(
+            f".{method_name}(..., on=...): event must be str or None, "
+            f"got {type(on).__name__}"
+        )
+
+    if callback is not None and not callable(callback):
+        raise TypeError(
+            f".{method_name}(..., callback): callback must be callable or None, "
+            f"got {type(callback).__name__}"
+        )
+
+    if not isinstance(target, str | list):
+        raise TypeError(
+            f".{method_name}(...): target must be str or list[str], "
+            f"got {type(target).__name__}"
+        )
+
+    if target == []:
+        raise ValueError(f".{method_name}([]): target list must not be empty")
+
+    if isinstance(target, list) and "*" in target:
+        raise ValueError(
+            f'.{method_name}([..., "*", ...]): wildcard "*" cannot be mixed in a list'
+        )
+
+    if target == "*" and method_name == "triggers":
+        raise ValueError(
+            f'.{method_name}("*", ...): wildcard is only supported on .triggered_by(...)'
+        )
+
+    names = [target] if isinstance(target, str) else target
+    for name in names:
+        if not isinstance(name, str):
+            raise TypeError(
+                f".{method_name}(...): list items must be str, "
+                f"got {type(name).__name__}"
+            )
+
+    return dict.fromkeys(names, _TriggerEntry(event=on, callback=callback))
+
+
+def _unbound_triggers(
+    self,
+    target: str | list[str],
+    callback: TriggerCallback | None = None,
+    *,
+    on: str | None = None,
+):
+    """Declare what an event on this field re-renders, optionally running a callback first.
+
+    Each call adds (or refines) one or more of this field's trigger
+    declarations. Calls compose. If a target name is declared twice,
+    the later call wins.
+
+    :param target: a field name, a list of field names, or an htmx
+        selector. A Python identifier resolves to a field by name. When
+        no field matches, a :exc:`UserWarning` is emitted and the name is
+        used as a selector, except for ``this``, ``next``, ``previous``
+        and ``body``. A
+        dotted ``"address.region"`` descends into a sub-form. A
+        ``"#id"`` matching a field's :mdn-global-attr:`id` anywhere in
+        the form re-renders that field. Any other string is passed
+        through verbatim to :htmx-attr:`hx-target`: any selector htmx
+        understands
+        (``".result"``, ``"closest .toast"``, ``"this"``,
+        ``"find .inner"``, ``"next"`` / ``"previous"``, …). See
+        :ref:`dom-targets`. A source has at most one selector target
+        over all its declarations, and a field with a selector target
+        cannot also listen to another field. Either case raises
+        :exc:`ValueError` when the form is built.
+    :param callback: optional ``(form, source, target) -> result``
+        callable run server-side before the target is re-rendered.
+        ``target`` is a :class:`~wtforms.fields.Field` for a field
+        target, or the raw selector ``str`` for a DOM target. The
+        ``result`` drives the response body (see :ref:`callback-return`).
+        Without a callback, the target re-renders from the current form
+        state. See :mod:`wtforms_htmx.mutations` for built-in callbacks.
+    :param on: optional :htmx-attr:`hx-trigger` event override. When ``None``,
+        the form-wide :attr:`~wtforms_htmx.HtmxMeta.htmx_default_trigger`
+        applies.
+
+    .. code-block:: python
+
+        country  = StringField().triggers("region")
+        country  = StringField().triggers("region", on="change")
+        postal   = StringField().triggers(["city", "region"])
+        eur      = IntegerField().triggers("jpy", eur_to_jpy)
+        add_item = ButtonField("Add item").triggers("items", list_add)
+        content  = TextAreaField().triggers("#preview", render_md, on="input delay:100ms")
+        # mixed events: chain
+        src = StringField().triggers("a").triggers("b", on="click")
+    """
+    entries = _normalize_trigger_args(target, callback, on, method_name="triggers")
+    self._htmx_triggers = {**getattr(self, "_htmx_triggers", {}), **entries}
+    return self
+
+
+def _unbound_triggered_by(
+    self,
+    source: str | list[str],
+    callback: TriggerCallback | None = None,
+    *,
+    on: str | None = None,
+):
+    """Declare which field events re-render this field, optionally running a callback first.
+
+    Symmetric to :meth:`.triggers() <wtforms.fields.core.UnboundField.triggers>`:
+    same shapes, same ``on`` / ``callback`` / return-value semantics.
+
+    The wildcard ``"*"``, used as a single string (not in a list), means
+    *any field of the form*: nested fields, the target itself, and
+    :class:`~wtforms.fields.FieldList` rows, including rows added later.
+    Inputs in the form that are not WTForms fields are not covered. The
+    callback receives ``source=None``, since there is no single source
+    field.
+
+    Unlike :meth:`triggers <wtforms.fields.core.UnboundField.triggers>`,
+    ``triggered_by`` does *not* accept DOM selectors: the source must be
+    a real field of the form. A string that matches none emits a
+    :exc:`UserWarning`, and the declaration is ignored.
+
+    .. code-block:: python
+
+        status = ButtonField("").triggered_by("*", autosave, on="input delay:800ms")
+    """
+    entries = _normalize_trigger_args(source, callback, on, method_name="triggered_by")
+    self._htmx_triggered_by = {**getattr(self, "_htmx_triggered_by", {}), **entries}
+    return self
+
+
+UnboundField.triggers = _unbound_triggers
+
+UnboundField.triggered_by = _unbound_triggered_by

wtforms_htmx/wrapper.py

@@ -0,0 +1,24 @@
+"""The ``wrapper=`` argument of every field declaration."""
+
+from __future__ import annotations
+
+from wtforms.fields.core import UnboundField
+
+_UNSET = object()
+
+_original_unbound_init = UnboundField.__init__
+
+
+def _patched_unbound_init(self, field_class, *args, **kwargs):
+    """Take the ``wrapper=`` kwarg off before WTForms sees it.
+
+    It is stored on the unbound field, and ``bind_field`` copies it to the
+    bound field.
+    """
+    wrapper = kwargs.pop("wrapper", _UNSET)
+    _original_unbound_init(self, field_class, *args, **kwargs)
+    if wrapper is not _UNSET:
+        self._htmx_wrapper = wrapper
+
+
+UnboundField.__init__ = _patched_unbound_init

wtforms_htmx-0.1.0.dist-info/METADATA

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: wtforms-htmx
+Version: 0.1.0
+Summary: Interactive WTForms forms declared in Python and powered by htmx, with no JavaScript to write.
+Keywords: wtforms,htmx,forms,validation
+License-Expression: BSD-3-Clause
+License-File: LICENSE.rst
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Requires-Dist: wtforms>=3.3.0,<4
+Maintainer: Éloi Rivard
+Maintainer-email: Éloi Rivard <eloi@yaal.coop>
+Requires-Python: >=3.11
+Project-URL: Documentation, https://wtforms-htmx.readthedocs.io/
+Project-URL: Changes, https://wtforms-htmx.readthedocs.io/changes/
+Project-URL: Source Code, https://github.com/yaal-coop/wtforms-htmx
+Project-URL: Issue Tracker, https://github.com/yaal-coop/wtforms-htmx/issues
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/_static/logo-dark.webp">
+    <img src="docs/_static/logo.webp" alt="wtforms-htmx">
+  </picture>
+</p>
+
+# wtforms-htmx
+
+Interactive [WTForms](https://wtforms.readthedocs.io/) forms declared in
+Python and powered by [htmx](https://htmx.org/), with no JavaScript to
+write, or even any htmx.
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://wtforms-htmx.readthedocs.io/en/latest/_static/screencasts/title-slug-dark.webp">
+    <img src="https://wtforms-htmx.readthedocs.io/en/latest/_static/screencasts/title-slug-light.webp" width="700" alt="Typing a title fills in its slug as you type.">
+  </picture>
+</p>
+
+Here's (almost) everything wtforms-htmx adds on top of a regular form:
+
+```python
+class PostForm(HtmxForm):
+    title = StringField().triggers("slug", slugify)
+    slug = StringField()
+```
+
+## Features
+
+- **Declare interactivity in Python.**
+  Right on the field declaration, not scattered across `hx-*`
+  attributes.
+- **No extra endpoints.** Interactions are handled by the form's
+  existing view. You don't write a route for each one.
+- **Progressive enhancement.** The form works without JavaScript;
+  htmx layers live updates and partial swaps on top. Same form, two
+  render paths.
+- **Opinionated defaults, fully overridable.** wtforms-htmx renders
+  the right `hx-*` for you, but they're yours to override.
+- **Common patterns in a few lines.** Inline validation and `FieldList`
+  add/remove/reorder are built in. The examples show how to build
+  autocomplete, comboboxes and dependent fields.
+
+Full documentation: <https://wtforms-htmx.readthedocs.io/>
+
+## Example app
+
+A runnable gallery of examples lives in `examples/`. The
+[documentation](https://wtforms-htmx.readthedocs.io/) shows most of them with a
+screencast. To run it locally:
+
+```sh
+uv sync --group example
+uv run python -m examples
+```
+
+Then open <http://127.0.0.1:5000/>.

wtforms_htmx-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+wtforms_htmx/__init__.py,sha256=zxluhBiIU6y0rjWgojAFFcl_2Pbcgge7MHLnOFpVjuQ,419
+wtforms_htmx/form.py,sha256=BlIEywrUJswQVG4CUnZorpTXfFbUVYLrdSBbleQ9ySk,29994
+wtforms_htmx/headers.py,sha256=InOnCf5yvjeVK_FykuSHgAYGtvULDQYe0OtaSZ7bkk8,1718
+wtforms_htmx/meta.py,sha256=5OFuRLPhb0cnFpqMjWEqA3_rvSLg9de7DJLYUwck8Qk,16629
+wtforms_htmx/mutations.py,sha256=QwGgg5BoEA0EoG77q-KmeH7CoHFkc2JPBU4i2FIeakY,10314
+wtforms_htmx/partial.py,sha256=DScIcDB_wG36ac2X7zVV37iv5ru6l85YHARgTUNCRfo,10276
+wtforms_htmx/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+wtforms_htmx/tree.py,sha256=cw6mAFVxoRIwJz9kqk-fATV-2iqnrFn14a-8fx75kZE,4377
+wtforms_htmx/triggers.py,sha256=5OM9_iJg5xBF0Obb6FRfSffJib4eR-I5AIF1Ri_Z3ko,7035
+wtforms_htmx/wrapper.py,sha256=ZRaphAFfxWqq-PulGkbPaFLDsgXgwVa_UTLM5m3UWXY,660
+wtforms_htmx-0.1.0.dist-info/licenses/LICENSE.rst,sha256=_H3YS-sMh9nVxo79jXhnJ4h6vhp8Gzo6q4q-0SZhk7w,1475
+wtforms_htmx-0.1.0.dist-info/WHEEL,sha256=1dD_GoEqEIxQ7VnrUExgdj_eExY4b4UgfR0iBlGKVac,80
+wtforms_htmx-0.1.0.dist-info/METADATA,sha256=fumxwGeDx8uQxLftXFIuEaWeE0f8V4K77YuTImNWju4,3281
+wtforms_htmx-0.1.0.dist-info/RECORD,,

wtforms_htmx-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.13.4
+Root-Is-Purelib: true
+Tag: py3-none-any

wtforms_htmx-0.1.0.dist-info/licenses/LICENSE.rst

@@ -0,0 +1,28 @@
+Copyright 2026 WTForms
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+1.  Redistributions of source code must retain the above copyright
+    notice, this list of conditions and the following disclaimer.
+
+2.  Redistributions in binary form must reproduce the above copyright
+    notice, this list of conditions and the following disclaimer in the
+    documentation and/or other materials provided with the distribution.
+
+3.  Neither the name of the copyright holder nor the names of its
+    contributors may be used to endorse or promote products derived from
+    this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.