WTForms 3.3.0b2__tar.gz → 3.3.0b3__tar.gz

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

@@ -1,5 +1,16 @@
 .. currentmodule:: wtforms
 
+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.0b3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: WTForms
-Version: 3.3.0b2
+Version: 3.3.0b3
 Summary: Form validation and rendering for Python web development.
 Project-URL: Documentation, https://wtforms.readthedocs.io
 Project-URL: Changes, https://wtforms.readthedocs.io/changes

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

@@ -337,9 +337,7 @@ Choice Fields
     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 +347,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():
@@ -400,28 +400,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::
+
+        class PaintForm(Form):
+            color = SelectField(
+                choices=enum_choices(Color, by="name"),
+                coerce=enum_coerce(Color, by="name"),
+            )
 
-    By default the option label is ``str(item)`` if the Enum defines its
+    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 +470,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 +600,6 @@ Data Lists
 
 .. currentmodule:: wtforms
 
-.. autoclass:: DataListChoice
-
 .. class:: DataList(choices=None, *, render_kw=None, widget=None)
 
     A :mdn-tag:`datalist` of suggestions. Unlike
@@ -658,6 +676,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.0b3}/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.0b3"
 
 __all__ = [
     "validators",
@@ -86,4 +87,5 @@ __all__ = [
     "Choice",
     "SelectChoice",
     "DataListChoice",
+    "enum_datalist",
 ]

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

@@ -4,9 +4,10 @@ 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 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,20 @@ 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__``, 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.
 

{wtforms-3.3.0b2 → wtforms-3.3.0b3}/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",

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

@@ -2,7 +2,6 @@ import warnings
 from dataclasses import dataclass
 from dataclasses import field
 from dataclasses import replace
-from enum import Enum
 from itertools import groupby
 from operator import attrgetter
 from typing import NamedTuple
@@ -21,18 +20,6 @@ __all__ = (
 )
 
 
-def _enum_coerce(enum_cls):
-    def coerce(v):
-        if isinstance(v, enum_cls):
-            return v
-        try:
-            return enum_cls[v]
-        except KeyError as e:
-            raise ValueError(str(e)) from e
-
-    return coerce
-
-
 class Choice(NamedTuple):
     """
     A rendered option yielded by
@@ -90,19 +77,6 @@ class SelectChoice:
     def __iter__(self):
         return iter((self.value, self.label, self.render_kw, self.optgroup))
 
-    @classmethod
-    def from_enum(cls, enum_cls, *, label=None):
-        """Build a list of choices from an :class:`enum.Enum` class.
-
-        The HTML value of each option is the item ``name``. The label
-        defaults to ``str(item)`` when the Enum defines its own
-        ``__str__``, otherwise to ``item.name``. Pass ``label=`` (a
-        callable taking an item) to override.
-        """
-        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, optgroup=None):
         """Coerce a value passed by the user via ``choices=...`` into a
@@ -141,6 +115,60 @@ class SelectChoice:
             return cls(*input, optgroup=optgroup)
 
 
+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
+    return [factory(value=getattr(m, by), label=label(m)) for m in enum_cls]
+
+
+def enum_choices(enum_cls, *, by="value", label=None):
+    """Build a list of :class:`SelectChoice` from an :class:`enum.Enum` class.
+
+    ``by`` selects which member attribute becomes the HTML ``value=``:
+    ``"value"`` (the default) emits ``member.value``, ``"name"`` emits
+    ``member.name``. Use ``"name"`` for enums whose values are not good
+    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.
+
+    Pair with :func:`enum_coerce` using the same ``by`` to round-trip the
+    submitted string back into a member.
+    """
+    return _enum_options(enum_cls, by, label, SelectChoice)
+
+
+def enum_coerce(enum_cls, *, by="value"):
+    """Return a ``coerce`` callable mapping a submitted string back to an
+    :class:`enum.Enum` member.
+
+    ``by`` must match the one passed to :func:`enum_choices`: ``"value"``
+    (the default) resolves ``str(member.value)`` — so ``IntEnum`` values
+    round-trip too — and ``"name"`` resolves ``member.name``. Already-coerced
+    members pass through unchanged.
+    """
+    if by not in ("value", "name"):
+        raise ValueError(f"by must be 'value' or 'name', got {by!r}")
+
+    def coerce(v):
+        if isinstance(v, enum_cls):
+            return v
+
+        try:
+            if by == "value":
+                by_value = {str(m.value): m for m in enum_cls}
+                return by_value[str(v)]
+            else:
+                return enum_cls[v]
+        except KeyError as e:
+            raise ValueError(str(e)) from e
+
+    return coerce
+
+
 def _normalize_iter_choice(choice):
     """Coerce a value yielded by :meth:`SelectFieldBase.iter_choices` or
     :meth:`SelectFieldBase.iter_groups` into a :class:`Choice`.
@@ -334,8 +362,6 @@ class SelectField(SelectFieldBase):
         **kwargs,
     ):
         super().__init__(label, validators, **kwargs)
-        if isinstance(coerce, type) and issubclass(coerce, Enum):
-            coerce = _enum_coerce(coerce)
         self.coerce = coerce
         if callable(choices):
             self._choices_callable = choices
@@ -389,8 +415,8 @@ class SelectField(SelectFieldBase):
                 ],
             )
 
-    def post_process(self):
-        super().post_process()
+    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)
 

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

@@ -350,13 +350,16 @@ class Field:
         except ValueError as e:
             self.process_errors.append(e.args[0])
 
-    def post_process(self):
+    def post_process(self, formdata=None):
         """Hook called after every field in the enclosing form has been processed.
 
         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`
         attached to the field.
+
+        :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)

{wtforms-3.3.0b2 → wtforms-3.3.0b3}/src/wtforms/fields/form.py

@@ -70,8 +70,8 @@ class FormField(Field):
                 meta={"_parent_form": self._form},
             )
 
-    def post_process(self):
-        self.form.post_process()
+    def post_process(self, formdata=None):
+        self.form.post_process(formdata)
 
     def validate(self, form, extra_validators=()):
         if extra_validators:

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

@@ -114,9 +114,9 @@ class FieldList(Field):
                 if k.isdigit():
                     yield int(k)
 
-    def post_process(self):
+    def post_process(self, formdata=None):
         for entry in self.entries:
-            entry.post_process()
+            entry.post_process(formdata)
 
     def validate(self, form, extra_validators=()):
         """

{wtforms-3.3.0b2 → wtforms-3.3.0b3}/src/wtforms/form.py

@@ -131,15 +131,20 @@ class BaseForm:
             field.process(formdata, data, extra_filters=field_extra_filters)
 
         if self._parent_form is None:
-            self.post_process()
+            self.post_process(formdata)
 
-    def post_process(self):
+    def post_process(self, formdata=None):
         """Hook called at the end of :meth:`process` on the root form.
 
         Runs the :meth:`~fields.Field.post_process` hook on every field, after
         all fields have been processed. Override this on a form subclass to add
-        cross-field finalization logic; call ``super().post_process()`` to keep
-        per-field hooks running.
+        cross-field finalization logic; call ``super().post_process(formdata)``
+        to keep per-field hooks running.
+
+        :param formdata: The resolved formdata the form was bound with
+            (already passed through :meth:`~meta.DefaultMeta.wrap_formdata`),
+            or ``None`` for non-formdata cycles. Forwarded to every nested
+            ``post_process``.
 
         ``post_process`` is only triggered automatically on the root form. Forms
         nested inside a :class:`~fields.FormField` (or via :class:`~fields.FieldList`
@@ -148,7 +153,7 @@ class BaseForm:
         ``post_process`` runs exactly once per processing cycle.
         """
         for field in self._fields.values():
-            field.post_process()
+            field.post_process(formdata)
 
     def validate(self, extra_validators=None):
         """

{wtforms-3.3.0b2 → wtforms-3.3.0b3}/tests/fields/test_form.py

@@ -118,15 +118,15 @@ def test_post_process_propagates_through_form_field():
     class Inner(Form):
         x = StringField()
 
-        def post_process(self):
-            super().post_process()
+        def post_process(self, formdata=None):
+            super().post_process(formdata)
             captured.append(("inner", self.x.data))
 
     class Outer(Form):
         block = FormField(Inner)
 
-        def post_process(self):
-            super().post_process()
+        def post_process(self, formdata=None):
+            super().post_process(formdata)
             captured.append(("outer", self.block.form.x.data))
 
     Outer(DummyPostData({"block-x": "v"}))
@@ -182,9 +182,9 @@ def test_post_process_mutation_propagates_top_down():
         tenant = StringField()
         block = FormField(Inner)
 
-        def post_process(self):
+        def post_process(self, formdata=None):
             self.tenant.data = (self.tenant.data or "").upper()
-            super().post_process()
+            super().post_process(formdata)
 
     Outer(DummyPostData({"tenant": "acme", "block-item": "a"}))
     assert captured == ["ACME"]