flask-wtforms-htmx 0.1.0__tar.gz

flask_wtforms_htmx-0.1.0/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.

flask_wtforms_htmx-0.1.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: flask-wtforms-htmx
+Version: 0.1.0
+Summary: A drop-in FlaskForm that brings wtforms-htmx to Flask-WTF.
+Keywords: wtforms,htmx,forms,flask,validation
+License-Expression: BSD-3-Clause
+License-File: LICENSE.rst
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Flask
+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: flask>=3.0
+Requires-Dist: flask-wtf>=1.2
+Requires-Dist: wtforms-htmx>=0.1.0
+Maintainer: Éloi Rivard
+Maintainer-email: Éloi Rivard <eloi@yaal.coop>
+Requires-Python: >=3.11
+Project-URL: Documentation, https://flask-wtforms-htmx.readthedocs.io/
+Project-URL: Changes, https://flask-wtforms-htmx.readthedocs.io/changes/
+Project-URL: Source Code, https://github.com/yaal-coop/flask-wtforms-htmx
+Project-URL: Issue Tracker, https://github.com/yaal-coop/flask-wtforms-htmx/issues
+Description-Content-Type: text/markdown
+
+# flask-wtforms-htmx
+
+A drop-in `FlaskForm` that brings
+[wtforms-htmx](https://github.com/yaal-coop/wtforms-htmx) to
+[Flask-WTF](https://flask-wtf.readthedocs.io/).
+
+**Status: alpha, work in progress.**
+
+`HtmxFlaskForm` replaces Flask-WTF's `FlaskForm`. The usual
+`validate_on_submit()` view answers htmx requests, and a mutation click
+without JavaScript does not save the form. CSRF protection and file
+uploads work as with Flask-WTF.
+
+## Installation
+
+```sh
+pip install flask-wtforms-htmx
+```
+
+## Example
+
+```python
+from flask import redirect, render_template, url_for
+from wtforms import ButtonField, FieldList, StringField, SubmitField
+from wtforms_htmx.mutations import list_add
+
+from flask_wtforms_htmx import HtmxFlaskForm
+
+
+class TagsForm(HtmxFlaskForm):
+    tags = FieldList(StringField(), min_entries=1)
+    add_tag = ButtonField("+").triggers("tags", list_add)
+    save = SubmitField("Save")
+
+
+@app.route("/tags", methods=["GET", "POST"])
+def tags():
+    form = TagsForm()
+    if form.validate_on_submit():
+        save(form.data)
+        return redirect(url_for("tags"))
+
+    return render_template("tags.html", form=form)
+```
+
+With htmx, a click on `+` adds a row without reloading the page. Without
+JavaScript, it reloads the page with the new row, and the form is not
+saved.
+
+## Links
+
+- Documentation: <https://flask-wtforms-htmx.readthedocs.io/>
+- Source: <https://github.com/yaal-coop/flask-wtforms-htmx>
+- Issues: <https://github.com/yaal-coop/flask-wtforms-htmx/issues>
+
+## License
+
+BSD-3-Clause. See `LICENSE.rst`.

flask_wtforms_htmx-0.1.0/README.md

@@ -0,0 +1,58 @@
+# flask-wtforms-htmx
+
+A drop-in `FlaskForm` that brings
+[wtforms-htmx](https://github.com/yaal-coop/wtforms-htmx) to
+[Flask-WTF](https://flask-wtf.readthedocs.io/).
+
+**Status: alpha, work in progress.**
+
+`HtmxFlaskForm` replaces Flask-WTF's `FlaskForm`. The usual
+`validate_on_submit()` view answers htmx requests, and a mutation click
+without JavaScript does not save the form. CSRF protection and file
+uploads work as with Flask-WTF.
+
+## Installation
+
+```sh
+pip install flask-wtforms-htmx
+```
+
+## Example
+
+```python
+from flask import redirect, render_template, url_for
+from wtforms import ButtonField, FieldList, StringField, SubmitField
+from wtforms_htmx.mutations import list_add
+
+from flask_wtforms_htmx import HtmxFlaskForm
+
+
+class TagsForm(HtmxFlaskForm):
+    tags = FieldList(StringField(), min_entries=1)
+    add_tag = ButtonField("+").triggers("tags", list_add)
+    save = SubmitField("Save")
+
+
+@app.route("/tags", methods=["GET", "POST"])
+def tags():
+    form = TagsForm()
+    if form.validate_on_submit():
+        save(form.data)
+        return redirect(url_for("tags"))
+
+    return render_template("tags.html", form=form)
+```
+
+With htmx, a click on `+` adds a row without reloading the page. Without
+JavaScript, it reloads the page with the new row, and the form is not
+saved.
+
+## Links
+
+- Documentation: <https://flask-wtforms-htmx.readthedocs.io/>
+- Source: <https://github.com/yaal-coop/flask-wtforms-htmx>
+- Issues: <https://github.com/yaal-coop/flask-wtforms-htmx/issues>
+
+## License
+
+BSD-3-Clause. See `LICENSE.rst`.

flask_wtforms_htmx-0.1.0/pyproject.toml

@@ -0,0 +1,193 @@
+[project]
+name = "flask-wtforms-htmx"
+version = "0.1.0"
+description = "A drop-in FlaskForm that brings wtforms-htmx to Flask-WTF."
+readme = "README.md"
+license = "BSD-3-Clause"
+license-files = ["LICENSE.rst"]
+keywords = [
+    "wtforms",
+    "htmx",
+    "forms",
+    "flask",
+    "validation",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Web Environment",
+    "Framework :: Flask",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
+    "Topic :: Internet :: WWW/HTTP :: Dynamic Content",
+]
+requires-python = ">=3.11"
+dependencies = [
+    "flask>=3.0",
+    "flask-wtf>=1.2",
+    "wtforms-htmx>=0.1.0",
+]
+
+[[project.maintainers]]
+name = "Éloi Rivard"
+email = "eloi@yaal.coop"
+
+[project.urls]
+Documentation = "https://flask-wtforms-htmx.readthedocs.io/"
+Changes = "https://flask-wtforms-htmx.readthedocs.io/changes/"
+"Source Code" = "https://github.com/yaal-coop/flask-wtforms-htmx"
+"Issue Tracker" = "https://github.com/yaal-coop/flask-wtforms-htmx/issues"
+
+[build-system]
+requires = ["uv_build>=0.13.1,<0.14"]
+build-backend = "uv_build"
+
+[tool.uv]
+required-version = ">=0.13.1"
+
+[tool.pytest.ini_options]
+testpaths = ["tests/unit"]
+pythonpath = ["."]
+filterwarnings = ["error"]
+
+[tool.coverage.run]
+branch = true
+source = [
+    "flask_wtforms_htmx",
+    "tests",
+]
+
+[tool.coverage.paths]
+source = [
+    "src",
+    "*/site-packages",
+]
+
+[tool.coverage.report]
+fail_under = 100
+exclude_lines = [
+    "pragma: no cover",
+    "except ImportError",
+    "if TYPE_CHECKING:",
+]
+
+[tool.ruff]
+src = ["src"]
+fix = true
+show-fixes = true
+output-format = "full"
+
+[tool.ruff.lint]
+select = [
+    "B",
+    "C90",
+    "D",
+    "E",
+    "F",
+    "I",
+    "UP",
+    "W",
+    "SIM",
+    "RET",
+    "BLE",
+    "TRY",
+    "ERA",
+    "PIE",
+    "RUF",
+    "DTZ",
+    "PTH",
+]
+ignore = [
+    "E501",
+    "E722",
+    "D100",
+    "D101",
+    "D102",
+    "D103",
+    "D104",
+    "D105",
+    "D106",
+    "D107",
+    "D203",
+    "D213",
+    "RUF001",
+    "RUF002",
+    "RUF003",
+    "TRY003",
+]
+
+[tool.ruff.lint.isort]
+force-single-line = true
+order-by-type = false
+
+[tool.ruff.lint.mccabe]
+max-complexity = 10
+
+[tool.mypy]
+python_version = "3.11"
+packages = ["flask_wtforms_htmx"]
+mypy_path = "src"
+ignore_missing_imports = true
+
+[tool.tox]
+requires = [
+    "tox>=4.22",
+    "tox-uv>=1.16",
+]
+env_list = [
+    "py3.11",
+    "py3.12",
+    "py3.13",
+    "py3.14",
+    "py3.15",
+    "minversions",
+    "typing",
+]
+
+[tool.tox.env_run_base]
+runner = "uv-venv-lock-runner"
+dependency_groups = ["test"]
+commands = [[
+    "pytest",
+    { replace = "posargs", extend = true },
+]]
+
+[tool.tox.env.typing]
+runner = "uv-venv-lock-runner"
+dependency_groups = ["dev"]
+commands = [["mypy"]]
+
+[tool.tox.env.minversions]
+runner = "uv-venv-runner"
+base_python = ["py3.11"]
+uv_resolution = "lowest-direct"
+dependency_groups = ["test"]
+commands = [[
+    "pytest",
+    "tests/unit",
+    { replace = "posargs", extend = true },
+]]
+
+[dependency-groups]
+doc = [
+    "pallets-sphinx-themes>=2.5.0",
+    "sphinx>=8.1.0",
+    "sphinx-issues>=6.0.0",
+]
+test = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+]
+dev = [
+    { include-group = "test" },
+    "mypy>=1.11",
+    "prek>=0.3.9",
+    "pytest-xdist>=3.8.0",
+    "tox-uv>=1.35.1",
+]

flask_wtforms_htmx-0.1.0/pyproject.toml.orig

@@ -0,0 +1,163 @@
+[project]
+name = "flask-wtforms-htmx"
+version = "0.1.0"
+description = "A drop-in FlaskForm that brings wtforms-htmx to Flask-WTF."
+readme = "README.md"
+license = "BSD-3-Clause"
+license-files = ["LICENSE.rst"]
+maintainers = [
+    { name = "Éloi Rivard", email = "eloi@yaal.coop" },
+]
+keywords = ["wtforms", "htmx", "forms", "flask", "validation"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Web Environment",
+    "Framework :: Flask",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
+    "Topic :: Internet :: WWW/HTTP :: Dynamic Content",
+]
+requires-python = ">=3.11"
+dependencies = [
+    "flask>=3.0",
+    "flask-wtf>=1.2",
+    "wtforms-htmx>=0.1.0",
+]
+
+[project.urls]
+Documentation = "https://flask-wtforms-htmx.readthedocs.io/"
+Changes = "https://flask-wtforms-htmx.readthedocs.io/changes/"
+"Source Code" = "https://github.com/yaal-coop/flask-wtforms-htmx"
+"Issue Tracker" = "https://github.com/yaal-coop/flask-wtforms-htmx/issues"
+
+[build-system]
+requires = ["uv_build>=0.13.1,<0.14"]
+build-backend = "uv_build"
+
+[tool.uv]
+required-version = ">=0.13.1"
+
+[dependency-groups]
+doc = [
+    "pallets-sphinx-themes>=2.5.0",
+    "sphinx>=8.1.0",
+    "sphinx-issues>=6.0.0",
+]
+test = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+]
+dev = [
+    { include-group = "test" },
+    "mypy>=1.11",
+    "prek>=0.3.9",
+    "pytest-xdist>=3.8.0",
+    "tox-uv>=1.35.1",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests/unit"]
+pythonpath = ["."]
+filterwarnings = ["error"]
+
+[tool.coverage.run]
+branch = true
+source = ["flask_wtforms_htmx", "tests"]
+
+[tool.coverage.paths]
+source = ["src", "*/site-packages"]
+
+[tool.coverage.report]
+fail_under = 100
+exclude_lines = [
+    "pragma: no cover",
+    "except ImportError",
+    "if TYPE_CHECKING:",
+]
+
+[tool.ruff]
+src = ["src"]
+fix = true
+show-fixes = true
+output-format = "full"
+
+[tool.ruff.lint]
+select = [
+    "B",   # flake8-bugbear
+    "C90", # mccabe
+    "D",   # pydocstyle
+    "E",   # pycodestyle error
+    "F",   # pyflakes
+    "I",   # isort
+    "UP",  # pyupgrade
+    "W",   # pycodestyle warning
+    "SIM",
+    "RET",
+    "BLE",
+    "TRY",
+    "ERA",
+    "PIE",
+    "RUF",
+    "DTZ",
+    "PTH",
+]
+
+ignore = [
+    "E501", # line-too-long
+    "E722", # bare-except
+    "D100", # public module
+    "D101", # public class
+    "D102", # public method
+    "D103", # public function
+    "D104", # public package
+    "D105", # magic method
+    "D106", # nested class
+    "D107", # public init
+    "D203", # no-blank-line-before-class
+    "D213", # multi-line-summary-second-line
+    "RUF001",
+    "RUF002",
+    "RUF003",
+    "TRY003", # raise-vanilla-args — dedicated exception classes would be overkill here
+]
+
+[tool.ruff.lint.isort]
+force-single-line = true
+order-by-type = false
+
+[tool.ruff.lint.mccabe]
+max-complexity = 10
+
+[tool.mypy]
+python_version = "3.11"
+packages = ["flask_wtforms_htmx"]
+mypy_path = "src"
+ignore_missing_imports = true
+
+[tool.tox]
+requires = ["tox>=4.22", "tox-uv>=1.16"]
+env_list = ["py3.11", "py3.12", "py3.13", "py3.14", "py3.15", "minversions", "typing"]
+
+[tool.tox.env_run_base]
+runner = "uv-venv-lock-runner"
+dependency_groups = ["test"]
+commands = [["pytest", { replace = "posargs", extend = true }]]
+
+[tool.tox.env.typing]
+runner = "uv-venv-lock-runner"
+dependency_groups = ["dev"]
+commands = [["mypy"]]
+
+[tool.tox.env.minversions]
+runner = "uv-venv-runner"
+base_python = ["py3.11"]
+uv_resolution = "lowest-direct"
+dependency_groups = ["test"]
+commands = [["pytest", "tests/unit", { replace = "posargs", extend = true }]]

flask_wtforms_htmx-0.1.0/src/flask_wtforms_htmx/__init__.py

@@ -0,0 +1,119 @@
+"""A drop-in FlaskForm that brings wtforms-htmx to Flask-WTF."""
+
+from __future__ import annotations
+
+from typing import Any
+from typing import TYPE_CHECKING
+
+from flask import abort
+from flask import current_app
+from flask import has_request_context
+from flask import render_template
+from flask import request
+from flask import Response
+from flask_wtf import FlaskForm
+from flask_wtf.csrf import CSRFError
+from markupsafe import Markup
+from wtforms_htmx import HtmxFormMixin
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+
+class HtmxFlaskForm(HtmxFormMixin, FlaskForm):
+    """Drop-in replacement for :class:`~flask_wtf.FlaskForm` that answers htmx requests.
+
+    The form reads the request headers itself, so the view does not pass
+    ``headers=``.
+
+    With an invalid CSRF token, htmx requests and clicks on a button with
+    :meth:`.triggers() <wtforms.fields.core.UnboundField.triggers>` get a
+    400 response (:class:`~flask_wtf.csrf.CSRFError`), and no callback runs.
+    htmx leaves the page as it is. A plain submit shows the error in the
+    form, as with Flask-WTF.
+    """
+
+    def __init__(self, *args, headers=None, **kwargs):
+        if headers is None and has_request_context():
+            headers = request.headers
+
+        super().__init__(*args, headers=headers, **kwargs)
+
+    def mutate(self) -> None:
+        """Run the mutations, or abort with a 400 when the CSRF token blocks them."""
+        super().mutate()
+        if not self.meta.csrf:
+            return
+
+        errors = self[self.meta.csrf_field_name].errors
+        if not errors or not self._is_interaction():
+            return
+
+        # htmx 4 swaps 4xx responses by default: keep the page as it is.
+        response = Response(errors[0], status=400, headers={"HX-Reswap": "none"})
+        raise CSRFError(errors[0], response=response)
+
+    def _is_interaction(self) -> bool:
+        """Return True for an htmx request or a click on a button with triggers."""
+        if self.submitter is not None and self.htmx_submit_attrs(self.submitter):
+            return True
+
+        return "HX-Request" in request.headers and "HX-Boosted" not in request.headers
+
+    def validate_on_submit(
+        self, extra_validators=None, *, submitter: Any = None
+    ) -> bool:
+        """Validate the form when the user saves it.
+
+        On an htmx request with a partial response, :func:`flask.abort` sends
+        that response, so the rest of the view does not run.
+
+        Returns ``False`` when the form was not submitted, or when a button
+        with :meth:`.triggers() <wtforms.fields.core.UnboundField.triggers>`
+        submitted it without JavaScript. With ``submitter=form.save``, only
+        that button saves.
+        """
+        if result := self.partial():
+            abort(Response(result.body, headers=result.headers))
+
+        if not self.is_submitted():
+            return False
+
+        if submitter is not None and self.submitter is not submitter:
+            return False
+
+        if self.mutated:
+            return False
+
+        return self.validate(extra_validators)
+
+
+def jinja_renderer(template: str, macro: str | None = None) -> Callable:
+    """Build a field wrapper callable that renders a Jinja template or macro.
+
+    ``jinja_renderer("_field.html")`` renders the template with ``field`` and
+    ``render_kw`` in its context. ``jinja_renderer("_macros.html", "render_field")``
+    calls the macro with ``(field, render_kw)``::
+
+        class ProfileForm(HtmxFlaskForm):
+            class Meta:
+                field_wrapper = staticmethod(jinja_renderer("_field.html"))
+    """
+    if macro is None:
+
+        def render_template_fn(field, render_kw):
+            return render_template(template, field=field, render_kw=render_kw)
+
+        return render_template_fn
+
+    def render_macro_fn(field, render_kw):
+        module = current_app.jinja_env.get_template(template).module
+        return Markup(getattr(module, macro)(field, render_kw))
+
+    return render_macro_fn
+
+
+__all__ = [
+    "HtmxFlaskForm",
+    "jinja_renderer",
+]