WTForms 3.3.0b3__tar.gz → 3.3.0b4__tar.gz

{wtforms-3.3.0b3 → wtforms-3.3.0b4}/CHANGES.rst

@@ -1,5 +1,33 @@
 .. currentmodule:: wtforms
 
+Version 3.3.0b4
+---------------
+
+Released 2026-10-23
+
+- Drop support for Python 3.10. Add support for Python 3.15.
+- :func:`fields.enum_choices` and :func:`~wtforms.datalist.enum_datalist`
+  label :class:`enum.IntEnum` members with their name on PyPy too, instead of
+  their value.
+- :class:`~datalist.DataList` ``choices`` accepts the shorthand
+  ``{value: label}`` dict syntax. :issue:`886`
+- Default ``invalid_value_message`` and ``invalid_choice_message`` are
+  translated when the error is raised, not when the field is built. Forms can
+  be built again outside of a translation context.
+- ``choices`` callables on :class:`~fields.SelectField` and
+  :class:`~datalist.DataList` run on the first read and their result is
+  cached. Calling :meth:`~form.BaseForm.post_process` again refreshes them.
+  This also applies to entries added with
+  :meth:`~fields.FieldList.append_entry` and
+  :meth:`~fields.FieldList.insert_entry`.
+- Passing a callable to ``SelectFieldBase._choices_from_input`` is
+  deprecated.
+- Numeric, date, time and select fields report a validation error instead of
+  raising a :class:`TypeError` when the input is not a string.
+- The labels of :class:`~fields.FieldList` entries point to the right field
+  after :meth:`~fields.FieldList.insert_entry` or
+  :meth:`~fields.FieldList.pop_entry` renumbers the entries.
+
 Version 3.3.0b3
 ---------------
 

{wtforms-3.3.0b3 → wtforms-3.3.0b4}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: WTForms
-Version: 3.3.0b3
+Version: 3.3.0b4
 Summary: Form validation and rendering for Python web development.
 Project-URL: Documentation, https://wtforms.readthedocs.io
 Project-URL: Changes, https://wtforms.readthedocs.io/changes
@@ -44,7 +44,7 @@ Classifier: License :: OSI Approved :: BSD License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python
 Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
-Requires-Python: >=3.10
+Requires-Python: >=3.11
 Requires-Dist: markupsafe>=1.1.1
 Provides-Extra: email
 Requires-Dist: email-validator>=2.0; extra == 'email'

{wtforms-3.3.0b3 → wtforms-3.3.0b4}/docs/fields.rst

@@ -67,6 +67,7 @@ The Field base class
     .. automethod:: process(formdata [, data])
     .. automethod:: process_data
     .. automethod:: process_formdata
+    .. automethod:: post_process
     .. attribute:: data
 
         Contains the resulting (sanitized) value of calling either of the
@@ -329,8 +330,8 @@ Choice Fields
                 SelectChoice('text', 'Plain Text'),
             ])
 
-    Note that the `choices` keyword is evaluated each time the form is
-    instantiated, so callables passed as `choices` are re-evaluated per instance.
+    A callable passed as `choices` is resolved separately for each form
+    instance, the first time its choices are read.
     For dynamic options, either pass a callable to `choices` or assign
     `field.choices` after instantiation. Any submitted choices which are not in
     the given choices list will cause validation on the field to fail. If this
@@ -361,17 +362,22 @@ Choice Fields
             user = User.query.get(id)
             form = UserDetails(request.POST, obj=user)
 
-    Note we passed a callable to `choices` rather than a static list; it is
-    invoked each time the form is instantiated, producing fresh options per
-    request. If the choices depend on data only available in the view, you can
-    instead assign `form.group_id.choices` after instantiation. The `coerce`
-    keyword arg to :class:`~wtforms.fields.SelectField` says that we use
-    :func:`int()` to coerce form data. The default coerce is :func:`str()`.
+    Note we passed a callable to `choices` rather than a static list; it
+    produces fresh options per request. Its result is cached. Calling
+    :meth:`~wtforms.form.BaseForm.post_process` again refreshes it.
+
+    If the choices depend on data only available in the view, you can instead
+    assign `form.group_id.choices` after instantiation. A list assigned this
+    way replaces the callable.
+
+    The `coerce` keyword arg to :class:`~wtforms.fields.SelectField` says
+    that we use :func:`int()` to coerce form data. The default coerce is
+    :func:`str()`.
 
     The callable may optionally accept ``(form, field)`` as positional
-    arguments. When this signature is used, the callable is invoked after the
-    whole form has been processed, so it can read ``field.data`` and the data
-    of any other field on the form::
+    arguments. The callable is invoked when the choices are read, normally
+    after the whole form has been processed, so it can read ``field.data`` and
+    the data of any other field on the form::
 
         def available_groups(form, field):
             return [SelectChoice(g.id, g.name) for g in form.tenant.data.groups]
@@ -610,12 +616,15 @@ Data Lists
 
     ``choices`` is either a list of :class:`~wtforms.DataListChoice`
     (or plain strings, in which case the string is used as both value
-    and label), or a callable invoked at render time. The callable
-    may take no argument (``fn()``) for a static list, or ``(field)``
-    to adapt the suggestions to the current field value at each
-    render — convenient for server-side filtering::
+    and label), a shorthand ``{value: label}`` dict, or a callable. The
+    callable runs when the datalist is rendered, after the whole form has been
+    processed. Its result is cached until the next
+    :meth:`~wtforms.form.BaseForm.post_process`. The callable may
+    take no argument (``fn()``) for a static list, or ``(form, field)``
+    to adapt the suggestions to the form data, for example the current
+    field value. This is convenient for server-side filtering::
 
-        DataList(lambda field: search(field.data))
+        DataList(lambda form, field: search(field.data))
 
     **Inline DataList owned by a field**
 
@@ -642,7 +651,7 @@ Data Lists
         class F(Form):
             items = FieldList(
                 StringField(
-                    datalist=DataList(lambda field: suggest(field.data))
+                    datalist=DataList(lambda form, field: suggest(field.data))
                 ),
                 min_entries=3,
             )

{wtforms-3.3.0b3 → wtforms-3.3.0b4}/docs/forms.rst

@@ -294,6 +294,8 @@ fields.
         this to provide form data to the enclosed fields. Accessing the field's
         data before calling process is not recommended.
 
+    .. automethod:: post_process
+
     .. automethod:: validate
 
     .. automethod:: __iter__

{wtforms-3.3.0b3 → wtforms-3.3.0b4}/pyproject.toml

@@ -13,7 +13,7 @@ classifiers = [
     "Programming Language :: Python",
     "Topic :: Internet :: WWW/HTTP :: Dynamic Content",
 ]
-requires-python = ">=3.10"
+requires-python = ">=3.11"
 dependencies = [
     "MarkupSafe>=1.1.1",
 ]
@@ -49,12 +49,12 @@ dev = [
 env_list = [
     "style",
     "minversions",
+    "py315",
     "py314",
     "py313",
     "py312",
     "py311",
-    "py310",
-    "pypy310",
+    "pypy311",
     "docs",
 ]
 skip_missing_interpreters = true
@@ -86,7 +86,7 @@ dependency_groups = ["docs"]
 commands = [["sphinx-build", "-W", "-b", "html", "-d", "{envtmpdir}/doctrees", "docs", "{envtmpdir}/html"]]
 
 [tool.tox.env.minversions]
-base_python = ["py3.10"]
+base_python = ["py3.11"]
 uv_resolution = "lowest-direct"
 dependency_groups = ["dev"]
 commands = [

{wtforms-3.3.0b3 → wtforms-3.3.0b4}/src/wtforms/__init__.py

@@ -42,7 +42,7 @@ from wtforms.fields.simple import URLField
 from wtforms.form import Form
 from wtforms.validators import ValidationError
 
-__version__ = "3.3.0b3"
+__version__ = "3.3.0b4"
 
 __all__ = [
     "validators",

{wtforms-3.3.0b3 → wtforms-3.3.0b4}/src/wtforms/datalist.py

@@ -3,8 +3,8 @@ from dataclasses import dataclass
 from dataclasses import field
 
 from wtforms import widgets
-from wtforms._compat import get_signature
 from wtforms.fields.choices import _enum_options
+from wtforms.fields.choices import _invoke_choices_callable
 from wtforms.fields.choices import Choice
 
 __all__ = ("DataList", "DataListChoice", "enum_datalist")
@@ -70,7 +70,8 @@ def enum_datalist(enum_cls, *, by="value", label=None):
     Same semantics as :func:`~wtforms.fields.enum_choices`: ``by`` selects
     which member attribute becomes the ``<option>`` value (``"value"`` by
     default, ``"name"`` otherwise) and ``label`` defaults to ``str(member)``
-    when the Enum defines its own ``__str__``, else ``member.name``.
+    when the Enum defines its own ``__str__`` or is a :class:`enum.StrEnum`,
+    else ``member.name``.
 
     A ``<datalist>`` only suggests values for a free-text field, so there is
     no coercion counterpart — the field stores whatever string is submitted.
@@ -91,6 +92,7 @@ class DataList:
     def __init__(self, choices=None, *, render_kw=None, widget=None):
         self._raw_choices = choices
         self._choices = None if callable(choices) else choices
+        self._field = None
         self.render_kw = render_kw or {}
         if widget is not None:
             self.widget = widget
@@ -100,27 +102,30 @@ class DataList:
         clone = DataList.__new__(DataList)
         clone._raw_choices = self._raw_choices
         clone._choices = None if callable(self._raw_choices) else self._raw_choices
+        clone._field = None
         clone.render_kw = self.render_kw
         clone.widget = self.widget
         clone.id = id
         return clone
 
-    def _resolve(self, field):
-        raw = self._raw_choices
-        if not callable(raw):
-            return
-        try:
-            sig = get_signature(raw)
-            sig.bind(field._form, field)
-        except TypeError:
-            self._choices = raw()
-            return
-        self._choices = raw(field._form, field)
+    def _invalidate(self, field):
+        """Mark the choices for a lazy refresh on the next :meth:`iter_choices`."""
+        if callable(self._raw_choices):
+            self._field = field
 
     def iter_choices(self, field=None):
+        if (bound := self._field) is not None:
+            self._field = None
+            self._choices = _invoke_choices_callable(
+                self._raw_choices, bound._form, bound
+            )
         raw = self._choices
         if raw is None:
             return []
+        if isinstance(raw, dict):
+            return [
+                DataListChoice(value=value, label=label) for value, label in raw.items()
+            ]
         return [DataListChoice.from_input(item) for item in raw]
 
     def __call__(self, field=None, **kwargs):

{wtforms-3.3.0b3 → wtforms-3.3.0b4}/src/wtforms/fields/choices.py

@@ -2,6 +2,7 @@ import warnings
 from dataclasses import dataclass
 from dataclasses import field
 from dataclasses import replace
+from enum import StrEnum
 from itertools import groupby
 from operator import attrgetter
 from typing import NamedTuple
@@ -115,11 +116,35 @@ class SelectChoice:
             return cls(*input, optgroup=optgroup)
 
 
+def _has_custom_str(enum_cls):
+    """Tell whether the enum or one of its user bases defines ``__str__``."""
+    stdlib = [
+        cls.__str__
+        for cls in enum_cls.__mro__
+        if cls.__module__ in ("enum", "builtins")
+    ]
+    return enum_cls.__str__ not in stdlib
+
+
+def _invoke_choices_callable(cb, form, field):
+    """Call a ``choices`` callable with ``(form, field)``, or with no argument."""
+    try:
+        sig = get_signature(cb)
+    except (ValueError, TypeError):
+        return cb()
+    try:
+        sig.bind(form, field)
+    except TypeError:
+        return cb()
+    return cb(form, field)
+
+
 def _enum_options(enum_cls, by, label, factory):
     if by not in ("value", "name"):
         raise ValueError(f"by must be 'value' or 'name', got {by!r}")
     if label is None:
-        label = str if "__str__" in enum_cls.__dict__ else lambda m: m.name
+        use_str = issubclass(enum_cls, StrEnum) or _has_custom_str(enum_cls)
+        label = str if use_str else lambda m: m.name
     return [factory(value=getattr(m, by), label=label(m)) for m in enum_cls]
 
 
@@ -132,8 +157,8 @@ def enum_choices(enum_cls, *, by="value", label=None):
     transport identifiers (non-string, non-unique or non-serialisable).
 
     The label defaults to ``str(member)`` when the Enum defines its own
-    ``__str__``, otherwise to ``member.name``. Pass ``label=`` (a callable
-    taking a member) to override.
+    ``__str__`` or is a :class:`enum.StrEnum`, otherwise to ``member.name``.
+    Pass ``label=`` (a callable taking a member) to override.
 
     Pair with :func:`enum_coerce` using the same ``by`` to round-trip the
     submitted string back into a member.
@@ -264,6 +289,13 @@ class SelectFieldBase(Field):
     def _choices_from_input(self, choices):
         """Parse the user-supplied ``choices`` into a list of :class:`SelectChoice`."""
         if callable(choices):
+            warnings.warn(
+                "Passing a callable to _choices_from_input() is deprecated; "
+                "resolve the callable before the call. Will be removed in "
+                "WTForms 3.4.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
             choices = self._invoke_choices_callback(choices)
 
         if choices is None:
@@ -332,15 +364,7 @@ class SelectFieldBase(Field):
                 return
 
     def _invoke_choices_callback(self, cb):
-        try:
-            sig = get_signature(cb)
-        except (ValueError, TypeError):
-            return cb()
-        try:
-            sig.bind(self._form, self)
-        except TypeError:
-            return cb()
-        return cb(self._form, self)
+        return _invoke_choices_callable(cb, self._form, self)
 
     class _Option(Field):
         def _value(self):
@@ -365,23 +389,40 @@ class SelectField(SelectFieldBase):
         self.coerce = coerce
         if callable(choices):
             self._choices_callable = choices
-            self.choices = None
+            self._choices_stale = True
+            self._choices = None
         else:
             self._choices_callable = None
+            self._choices_stale = False
             if choices is None:
-                self.choices = None
+                self._choices = None
             else:
                 self._warn_legacy_choices(choices)
-                self.choices = (
+                self._choices = (
                     dict(choices) if isinstance(choices, dict) else list(choices)
                 )
         self.validate_choice = validate_choice
-        self.invalid_value_message = invalid_value_message or self.gettext(
-            "Invalid Choice: could not coerce."
-        )
-        self.invalid_choice_message = invalid_choice_message or self.gettext(
-            "Not a valid choice."
-        )
+        self.invalid_value_message = invalid_value_message
+        self.invalid_choice_message = invalid_choice_message
+
+    @property
+    def choices(self):
+        """The field's choices, resolved from the callable on first read."""
+        if self._choices_stale:
+            self._choices_stale = False
+            self._choices = self._invoke_choices_callback(self._choices_callable)
+        return self._choices
+
+    @choices.setter
+    def choices(self, value):
+        if callable(value):
+            self._choices_callable = value
+            self._choices_stale = True
+            self._choices = None
+        else:
+            self._choices_callable = None
+            self._choices_stale = False
+            self._choices = value
 
     def iter_choices(self):
         choices = self._choices_from_input(self.choices) or []
@@ -418,7 +459,7 @@ class SelectField(SelectFieldBase):
     def post_process(self, formdata=None):
         super().post_process(formdata)
         if self._choices_callable is not None:
-            self.choices = self._invoke_choices_callback(self._choices_callable)
+            self._choices_stale = True
 
     def process_data(self, value):
         try:
@@ -433,8 +474,11 @@ class SelectField(SelectFieldBase):
 
         try:
             self.data = self.coerce(valuelist[0])
-        except ValueError as exc:
-            raise ValueError(self.invalid_value_message) from exc
+        except (ValueError, TypeError) as exc:
+            raise ValueError(
+                self.invalid_value_message
+                or self.gettext("Invalid Choice: could not coerce.")
+            ) from exc
 
     def pre_validate(self, form):
         if self.process_errors:
@@ -447,7 +491,9 @@ class SelectField(SelectFieldBase):
             raise TypeError(self.gettext("Choices cannot be None."))
 
         if not any(choice.selected for choice in self._iter_choices_normalized()):
-            raise ValidationError(self.invalid_choice_message)
+            raise ValidationError(
+                self.invalid_choice_message or self.gettext("Not a valid choice.")
+            )
 
 
 class SelectMultipleField(SelectField):
@@ -483,9 +529,7 @@ class SelectMultipleField(SelectField):
             validate_choice=validate_choice,
             **kwargs,
         )
-        self.invalid_value_message = invalid_value_message or self.gettext(
-            "Invalid choice(s): one or more data inputs could not be coerced."
-        )
+        self.invalid_value_message = invalid_value_message
         self.invalid_choice_message = invalid_choice_message
 
     def iter_choices(self):
@@ -527,8 +571,13 @@ class SelectMultipleField(SelectField):
     def process_formdata(self, valuelist):
         try:
             self.data = list(self.coerce(x) for x in valuelist)
-        except ValueError as exc:
-            raise ValueError(self.invalid_value_message) from exc
+        except (ValueError, TypeError) as exc:
+            raise ValueError(
+                self.invalid_value_message
+                or self.gettext(
+                    "Invalid choice(s): one or more data inputs could not be coerced."
+                )
+            ) from exc
 
     def pre_validate(self, form):
         if self.process_errors:

{wtforms-3.3.0b3 → wtforms-3.3.0b4}/src/wtforms/fields/core.py

@@ -355,14 +355,17 @@ class Field:
 
         Override this when a field needs to read other fields' processed data,
         for example to resolve dynamic choices that depend on the form state.
-        The base implementation resolves any inline :class:`~wtforms.DataList`
+        The base implementation refreshes any inline :class:`~wtforms.DataList`
         attached to the field.
 
+        It may run again after the form data changed. See
+        :meth:`~wtforms.form.BaseForm.post_process`.
+
         :param formdata: The resolved formdata the enclosing form was bound
             with, or ``None`` for non-formdata cycles.
         """
         if self._datalist is not None and not isinstance(self._datalist, str):
-            self._datalist._resolve(self)
+            self._datalist._invalidate(self)
 
     def process_data(self, value):
         """

{wtforms-3.3.0b3 → wtforms-3.3.0b4}/src/wtforms/fields/datetime.py

@@ -23,7 +23,7 @@ class DateTimeField(Field):
     format will be accepted, and the first format in the list will be used
     to produce HTML values.
 
-    .. deprecated:: 3.2.3
+    .. deprecated:: 3.3.0
        ``DateTimeField`` renders ``<input type="datetime">``, which is
        obsolete. Use :class:`DateTimeLocalField` instead. ``DateTimeField``
        will be removed in WTForms 3.4.
@@ -50,9 +50,7 @@ class DateTimeField(Field):
             )
         self.format = format if isinstance(format, list) else [format]
         self.strptime_format = clean_datetime_format_for_strptime(self.format)
-        self.invalid_value_message = invalid_value_message or self.gettext(
-            "Not a valid datetime value."
-        )
+        self.invalid_value_message = invalid_value_message
 
     def _value(self):
         if self.raw_data:
@@ -64,15 +62,17 @@ class DateTimeField(Field):
         if not valuelist:
             return
 
-        date_str = " ".join(valuelist)
         for format in self.strptime_format:
             try:
+                date_str = " ".join(valuelist)
                 self.data = datetime.datetime.strptime(date_str, format)
                 return
-            except ValueError:
+            except (ValueError, TypeError):
                 self.data = None
 
-        raise ValueError(self.invalid_value_message)
+        raise ValueError(
+            self.invalid_value_message or self.gettext("Not a valid datetime value.")
+        )
 
 
 class DateField(DateTimeField):
@@ -98,23 +98,22 @@ class DateField(DateTimeField):
             invalid_value_message=invalid_value_message,
             **kwargs,
         )
-        self.invalid_value_message = invalid_value_message or self.gettext(
-            "Not a valid date value."
-        )
 
     def process_formdata(self, valuelist):
         if not valuelist:
             return
 
-        date_str = " ".join(valuelist)
         for format in self.strptime_format:
             try:
+                date_str = " ".join(valuelist)
                 self.data = datetime.datetime.strptime(date_str, format).date()
                 return
-            except ValueError:
+            except (ValueError, TypeError):
                 self.data = None
 
-        raise ValueError(self.invalid_value_message)
+        raise ValueError(
+            self.invalid_value_message or self.gettext("Not a valid date value.")
+        )
 
 
 class TimeField(DateTimeField):
@@ -140,23 +139,22 @@ class TimeField(DateTimeField):
             invalid_value_message=invalid_value_message,
             **kwargs,
         )
-        self.invalid_value_message = invalid_value_message or self.gettext(
-            "Not a valid time value."
-        )
 
     def process_formdata(self, valuelist):
         if not valuelist:
             return
 
-        time_str = " ".join(valuelist)
         for format in self.strptime_format:
             try:
+                time_str = " ".join(valuelist)
                 self.data = datetime.datetime.strptime(time_str, format).time()
                 return
-            except ValueError:
+            except (ValueError, TypeError):
                 self.data = None
 
-        raise ValueError(self.invalid_value_message)
+        raise ValueError(
+            self.invalid_value_message or self.gettext("Not a valid time value.")
+        )
 
 
 class MonthField(DateField):
@@ -196,17 +194,14 @@ class WeekField(DateField):
             invalid_value_message=invalid_value_message,
             **kwargs,
         )
-        self.invalid_value_message = invalid_value_message or self.gettext(
-            "Not a valid week value."
-        )
 
     def process_formdata(self, valuelist):
         if not valuelist:
             return
 
-        time_str = " ".join(valuelist)
         for format in self.strptime_format:
             try:
+                time_str = " ".join(valuelist)
                 if "%w" not in format:
                     # The '%w' week starting day is needed. This defaults it to monday
                     # like ISO 8601 indicates.
@@ -216,10 +211,12 @@ class WeekField(DateField):
                 else:
                     self.data = datetime.datetime.strptime(time_str, format).date()
                 return
-            except ValueError:
+            except (ValueError, TypeError):
                 self.data = None
 
-        raise ValueError(self.invalid_value_message)
+        raise ValueError(
+            self.invalid_value_message or self.gettext("Not a valid week value.")
+        )
 
 
 class DateTimeLocalField(DateTimeField):

{wtforms-3.3.0b3 → wtforms-3.3.0b4}/src/wtforms/fields/list.py

@@ -205,12 +205,21 @@ class FieldList(Field):
         entry.name = new_name
         entry.short_name = str(new_index)
         entry.id = new_id
+        self._sync_label(entry, old_id)
 
         for descendant in self._iter_descendants(entry):
             if descendant.name and descendant.name.startswith(old_name):
                 descendant.name = new_name + descendant.name[len(old_name) :]
             if descendant.id and descendant.id.startswith(old_id):
+                old_descendant_id = descendant.id
                 descendant.id = new_id + descendant.id[len(old_id) :]
+                self._sync_label(descendant, old_descendant_id)
+
+    @staticmethod
+    def _sync_label(field, old_id):
+        label = getattr(field, "label", None)
+        if label is not None and label.field_id == old_id:
+            label.field_id = field.id
 
     def _iter_descendants(self, field):
         """Yield all fields below ``field`` recursively (form sub-fields and
@@ -231,7 +240,9 @@ class FieldList(Field):
         Entries added in this way will *not* receive formdata however, and can
         only receive object data.
         """
-        return self._add_entry(data=data)
+        field = self._add_entry(data=data)
+        field.post_process()
+        return field
 
     def insert_entry(self, index, data=unset_value):
         """
@@ -247,6 +258,7 @@ class FieldList(Field):
         field = self._add_entry(data=data)
         self.entries.insert(index, self.entries.pop())
         self._compact_indices()
+        field.post_process()
         return field
 
     def pop_entry(self, index=-1):