WTForms 3.3.0b2__tar.gz → 3.3.0b4__tar.gz

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

@@ -1,5 +1,44 @@
 .. 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
+---------------
+
+Released 2026-06-12
+
+- Add :func:`fields.enum_choices`, :func:`fields.enum_coerce` and
+  :func:`~wtforms.datalist.enum_datalist` for Enum-backed choices,
+  replacing ``SelectChoice.from_enum`` and friends. :issue:`922`
+- An Enum ``coerce`` is no longer wrapped, and options default to
+  ``member.value``. :issue:`922`
+
 Version 3.3.0b2
 ---------------
 

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: WTForms
-Version: 3.3.0b2
+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.0b2 → 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,17 +330,15 @@ 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
     option cannot be applied to your problem you may wish to skip choice
     validation (see below).
 
-    **Select fields with ``<optgroup>``**::
-
-        Use :class:`SelectChoice` to assign an option to an ``<optgroup>``.
+    **Select fields with optgroup**::
 
         class PastebinEntry(Form):
             language = SelectField('Programming Language', choices=[
@@ -349,6 +348,8 @@ Choice Fields
                 SelectChoice('text', 'Plain Text'),
             ])
 
+    Use :class:`SelectChoice` to assign an option to an ``<optgroup>``.
+
     **Select fields with dynamic choice values**::
 
         def available_groups():
@@ -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]
@@ -400,28 +406,44 @@ Choice Fields
     **Select fields backed by an Enum**::
 
         from enum import Enum
+        from wtforms.fields import enum_choices, enum_coerce
 
         class Color(Enum):
-            RED = 1
-            GREEN = 2
-            BLUE = 3
+            RED = "red"
+            GREEN = "green"
+            BLUE = "blue"
 
         class PaintForm(Form):
-            color = SelectField(choices=SelectChoice.from_enum(Color), coerce=Color)
+            color = SelectField(
+                choices=enum_choices(Color),
+                coerce=enum_coerce(Color),
+            )
+
+    :func:`~wtforms.fields.enum_choices` builds the option list from
+    the Enum members; by default the HTML ``value`` of each option is the
+    member's ``value`` (``"red"``, ``"green"``, ...).
+    :func:`~wtforms.fields.enum_coerce` returns the matching ``coerce``
+    callable that resolves the submitted string back into a member, so
+    ``form.color.data`` is a ``Color`` member after submit. Pre-selecting
+    works the usual way, with an Enum member: ``PaintForm(color=Color.RED)``.
 
-    :meth:`SelectChoice.from_enum` builds the option list from the Enum items;
-    the HTML ``value`` of each option is the item's ``name``. Passing the
-    Enum class itself as ``coerce`` installs the matching coercion, so
-    ``form.color.data`` is a ``Color`` item after submit. Pre-selecting
-    works the usual way, with an Enum item: ``PaintForm(color=Color.RED)``.
+    Use ``by="name"`` on **both** helpers when the Enum value is not a good
+    transport identifier — non-unique, non-serialisable, or when you simply
+    want ``member.name`` on the wire::
 
-    By default the option label is ``str(item)`` if the Enum defines its
+        class PaintForm(Form):
+            color = SelectField(
+                choices=enum_choices(Color, by="name"),
+                coerce=enum_coerce(Color, by="name"),
+            )
+
+    By default the option label is ``str(member)`` if the Enum defines its
     own ``__str__`` (also the case for :class:`enum.StrEnum`), otherwise
-    ``item.name``. To customise, pass a ``label`` callable taking an Enum
-    item and returning the label string::
+    ``member.name``. To customise, pass a ``label`` callable taking an Enum
+    member and returning the label string::
 
-        SelectChoice.from_enum(Color, label=lambda item: item.name.title())
-        # → [SelectChoice('RED', 'Red'), SelectChoice('GREEN', 'Green'), SelectChoice('BLUE', 'Blue')]
+        enum_choices(Color, label=lambda member: member.name.title())
+        # → [SelectChoice('red', 'Red'), SelectChoice('green', 'Green'), SelectChoice('blue', 'Blue')]
 
     **Skipping choice validation**::
 
@@ -454,6 +476,10 @@ Choice Fields
    which are not in the given choices list will cause validation on the field
    to fail.
 
+.. autofunction:: wtforms.fields.enum_choices
+
+.. autofunction:: wtforms.fields.enum_coerce
+
 Submit fields
 -------------
 
@@ -580,8 +606,6 @@ Data Lists
 
 .. currentmodule:: wtforms
 
-.. autoclass:: DataListChoice
-
 .. class:: DataList(choices=None, *, render_kw=None, widget=None)
 
     A :mdn-tag:`datalist` of suggestions. Unlike
@@ -592,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**
 
@@ -624,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,
             )
@@ -658,6 +685,9 @@ Data Lists
     :class:`~wtforms.fields.TextAreaField` is silently ignored by the
     browser.
 
+.. autoclass:: DataListChoice
+
+.. autofunction:: wtforms.datalist.enum_datalist
 
 .. currentmodule:: wtforms.fields
 

{wtforms-3.3.0b2 → 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.0b2 → 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.0b2 → wtforms-3.3.0b4}/src/wtforms/__init__.py

@@ -2,6 +2,7 @@ from wtforms import validators
 from wtforms import widgets
 from wtforms.datalist import DataList
 from wtforms.datalist import DataListChoice
+from wtforms.datalist import enum_datalist
 from wtforms.fields.choices import Choice
 from wtforms.fields.choices import RadioField
 from wtforms.fields.choices import SelectChoice
@@ -41,7 +42,7 @@ from wtforms.fields.simple import URLField
 from wtforms.form import Form
 from wtforms.validators import ValidationError
 
-__version__ = "3.3.0b2"
+__version__ = "3.3.0b4"
 
 __all__ = [
     "validators",
@@ -86,4 +87,5 @@ __all__ = [
     "Choice",
     "SelectChoice",
     "DataListChoice",
+    "enum_datalist",
 ]

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

@@ -3,10 +3,11 @@ 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")
+__all__ = ("DataList", "DataListChoice", "enum_datalist")
 
 
 @dataclass
@@ -35,16 +36,6 @@ class DataListChoice:
     def __iter__(self):
         return iter((self.value, self.label, self.render_kw))
 
-    @classmethod
-    def from_enum(cls, enum_cls, *, label=None):
-        """Build a list of choices from an :class:`enum.Enum` class.
-
-        See :meth:`SelectChoice.from_enum` for details.
-        """
-        if label is None:
-            label = str if "__str__" in enum_cls.__dict__ else lambda m: m.name
-        return [cls(value=m.name, label=label(m)) for m in enum_cls]
-
     @classmethod
     def from_input(cls, input):
         """Coerce a value passed by the user into a :class:`DataListChoice`."""
@@ -73,6 +64,21 @@ class DataListChoice:
             return cls(*input)
 
 
+def enum_datalist(enum_cls, *, by="value", label=None):
+    """Build a list of :class:`DataListChoice` from an :class:`enum.Enum` class.
+
+    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__`` 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.
+    """
+    return _enum_options(enum_cls, by, label, DataListChoice)
+
+
 class DataList:
     """A ``<datalist>`` of suggestions attached to a single field.
 
@@ -86,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
@@ -95,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.0b2 → wtforms-3.3.0b4}/src/wtforms/fields/__init__.py

@@ -1,4 +1,6 @@
 from wtforms.fields.choices import Choice
+from wtforms.fields.choices import enum_choices
+from wtforms.fields.choices import enum_coerce
 from wtforms.fields.choices import RadioField
 from wtforms.fields.choices import SelectChoice
 from wtforms.fields.choices import SelectField
@@ -46,6 +48,8 @@ __all__ = [
     "SelectMultipleField",
     "SelectFieldBase",
     "RadioField",
+    "enum_choices",
+    "enum_coerce",
     "DateTimeField",
     "DateField",
     "TimeField",