WTForms 3.3.0b1__tar.gz → 3.3.0b3__tar.gz

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

@@ -1,5 +1,48 @@
 .. 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
+---------------
+
+Released 2026-05-24
+
+- :class:`~fields.SelectField` ``choices`` accepts a shorthand dict
+  syntax: ``{value: label}`` for flat options and
+  ``{label: {value: label}}`` for optgroups. :issue:`886`
+- Split choice types by role: :class:`~fields.SelectChoice` and
+  :class:`~fields.DataListChoice` to declare options via ``choices=``,
+  :class:`~fields.Choice` for what ``iter_choices`` / ``iter_groups``
+  yield. :issue:`922`
+- ``choices`` callables on :class:`~fields.SelectField` and
+  :class:`~datalist.DataList` may accept ``(form, field)``. Resolved
+  once per processing cycle. :issue:`922`
+- Add :meth:`fields.Field.post_process` and
+  :meth:`form.BaseForm.post_process` hooks, propagated through
+  :class:`~fields.FormField` and :class:`~fields.FieldList` for
+  cross-field finalization. :issue:`922`
+- Add ``Field._form`` and ``BaseForm._parent_form`` so fields and nested
+  forms can reach their enclosing form. Fix :class:`~fields.FieldList`
+  entries and :class:`~fields.SelectField` option subfields which
+  previously got ``form=None``. :issue:`922`
+- Restore 3.2 compatibility for :class:`~fields.SelectField` subclasses:
+  tuple yields from :meth:`~fields.SelectFieldBase.iter_choices` /
+  :meth:`~fields.SelectFieldBase.iter_groups`,
+  3-positional :meth:`widgets.Select.render_option` overrides,
+  :meth:`~fields.SelectFieldBase.has_groups` /
+  :meth:`~fields.SelectFieldBase.iter_groups`, and ``self.choices``
+  keeping the user-supplied shape. Each emits a ``DeprecationWarning``;
+  will be removed in WTForms 4.0. :issue:`922`
+
 Version 3.3.0b1
 ---------------
 
@@ -12,66 +55,64 @@ Released 2026-05-10
   ``step="any"``. :issue:`677` :pr:`679`
 - :meth:`~fields.FieldList._add_entry` now routes through :meth:`~meta.DefaultMeta.bind_field`,
   consistent with how the form constructor binds top-level fields. Custom ``Meta.bind_field``
-  overrides were silently bypassed for all ``FieldList`` entries.
-- Add `test_environment` support to :class:`~validators.Email`. :issue:`869`
-- Reset :class:`~fields.FieldList` index state when reprocessing entries. :issue:`874`
-- Let :class:`~widgets.RangeInput` accept `min` and `max` at construction time. :issue:`693`
+  overrides were silently bypassed for all ``FieldList`` entries. :pr:`891`
+- Add `test_environment` support to :class:`~validators.Email`. :issue:`869` :pr:`894`
+- Reset :class:`~fields.FieldList` index state when reprocessing entries. :issue:`874` :pr:`895`
+- Let :class:`~widgets.RangeInput` accept `min` and `max` at construction time. :issue:`693` :pr:`898`
 - Do not render a ``for`` attribute on the main label of :class:`~fields.RadioField`.
-  :issue:`775`
-- Deprecate :class:`~fields.DateTimeField`, which will be removed in WTForms 3.4. :issue:`831`
+  :issue:`775` :pr:`900`
+- Deprecate :class:`~fields.DateTimeField`, which will be removed in WTForms 3.4. :issue:`831` :pr:`897`
 - Clarify that :class:`~fields.SelectField` ``choices`` is re-evaluated at
-  every form instantiation, including callables, in the documentation. :issue:`875`
+  every form instantiation, including callables, in the documentation. :issue:`875` :pr:`909`
 - Render ``False`` as ``value="False"`` in :class:`~fields.SelectField` options
-  instead of omitting the attribute. :issue:`878`
+  instead of omitting the attribute. :issue:`878` :pr:`908`
 - Accept :class:`uuid.UUID` instances in the :class:`~validators.UUID` validator,
   and translate unexpected types into :class:`~validators.ValidationError`
   instead of letting :class:`TypeError` escape. :issue:`549` :pr:`769`
 - Escape double quotes in :class:`~markupsafe.Markup` attribute values
   passed to :func:`~widgets.html_params`, and return a
-  :class:`~markupsafe.Markup`. :issue:`801`
-- Clarify documentation about filters. :issue:`859`
+  :class:`~markupsafe.Markup`. :issue:`801` :pr:`906` :pr:`907`
+- Clarify documentation about filters. :issue:`859` :pr:`896`
 - Let render-time ``checked`` kwargs take precedence over the field's value
   in :class:`~widgets.CheckboxInput` and :class:`~widgets.RadioInput`.
-  :issue:`706`
+  :issue:`706` :pr:`910`
 - Add a ``tz`` parameter to :class:`~fields.DateTimeLocalField` to associate a
-  timezone with the input. :issue:`833`
+  timezone with the input. :issue:`833` :pr:`905`
 - Add :class:`~fields.FieldList` ``insert_entry`` and indexed ``pop_entry``.
-  :issue:`256`
-- :class:`~fields.FieldList` builds entries in the order keys appear in
-  ``formdata``, instead of sorting them by numeric index. :issue:`256`
+  :issue:`256` :pr:`901` :pr:`912`
 - Add :class:`~fields.ButtonField` to render ``<button type="submit">``
-  controls with string values. :issue:`784`
+  controls with string values. :issue:`784` :pr:`892`
 - :class:`~fields.SelectField` refactor. Choices tuples and dicts are
-  deprecated in favor of :class:`~fields.Choice`. :pr:`739`
+  deprecated in favor of :class:`~fields.Choice`. :pr:`739` :pr:`889`
 - ``<option>`` HTML attributes can be passed using
-  :class:`~fields.Choice`. :issue:`692` :pr:`739`
+  :class:`~fields.Choice`. :issue:`692` :pr:`739` :pr:`889`
 - Add :meth:`fields.Choice.from_enum` to build choices from an
   :class:`enum.Enum` class, and let :class:`~fields.SelectField` accept an
-  Enum class as ``coerce``. :issue:`338`
+  Enum class as ``coerce``. :issue:`338` :pr:`916`
 - Defer to ``email_validator``'s module-level defaults for the
   :class:`~validators.Email` ``test_environment``, ``allow_smtputf8`` and
-  ``allow_empty_local`` options. :issue:`915`
+  ``allow_empty_local`` options. :issue:`915` :pr:`917`
 - Add ``invalid_value_message`` and ``invalid_choice_message`` keyword
   arguments for customizing built-in field error messages. On
   ``SelectMultipleField``, ``invalid_choice_message`` may also be a callable
-  for custom pluralization. :issue:`39` :issue:`832`
+  for custom pluralization. :issue:`39` :issue:`832` :pr:`902`
 - :class:`~fields.SelectField` and :class:`~fields.SelectMultipleField`
   ``pre_validate`` now short-circuits when ``process_formdata`` already
   produced an error, so a single coercion failure no longer surfaces as both
-  an "invalid value" and an "invalid choice" error.
+  an "invalid value" and an "invalid choice" error. :pr:`902`
 - Add a ``matcher`` keyword argument to :class:`~validators.Regexp` to
   override the matching function. Defaults to :func:`re.match`; pass
   :func:`re.search` or :func:`re.fullmatch` to change the anchoring
-  behaviour. :issue:`867`
+  behaviour. :issue:`867` :pr:`918`
 - Add an ``html_pattern`` keyword argument to :class:`~validators.Regexp`
   to control the HTML ``pattern`` attribute emitted on supporting widgets.
-  :issue:`759`
+  :pr:`759`
 - :class:`~validators.URL` validator is based on ``urllib.parse.urlparse``
   instead of a regex. New keyword arguments: ``allow_userinfo`` for
   accepting ``user:password@host`` URLs; ``schemes``
   (default ``("http", "https")``) is the allowlist of accepted schemes
   :pr:`847`
-- Add native :class:`DataList` support. :issue:`653`
+- Add native :class:`DataList` support. :issue:`653` :pr:`921`
 
 Version 3.2.2
 -------------

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: WTForms
-Version: 3.3.0b1
+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.0b1 → wtforms-3.3.0b3}/docs/fields.rst

@@ -287,10 +287,10 @@ refer to a single input from the form.
 Choice Fields
 -------------
 
-.. autoclass:: Choice
-
 .. autoclass:: SelectChoice
 
+.. autoclass:: Choice
+
 .. autoclass:: RadioField(default field arguments, choices=None, coerce=str)
 
     .. code-block:: jinja
@@ -310,23 +310,23 @@ Choice Fields
 
     Select fields take a ``choices`` parameter which is either:
 
-    * a list of :class:`Choice`.
+    * a list of :class:`SelectChoice`.
       It can also be a list of only values, in which case the value is used
-      as the label. The :class:`Choice` ``render_kw`` mapping is rendered as
+      as the label. The :class:`SelectChoice` ``render_kw`` mapping is rendered as
       HTML :mdn-tag:`option` parameters. The value can be of any
       type, but because form data is sent to the browser as strings, you
       will need to provide a ``coerce`` function that converts a string
       back to the expected type.
-    * a function taking no argument, and returning a list of :class:`Choice`.
+    * a function taking no argument, and returning a list of :class:`SelectChoice`.
 
 
     **Select fields with static choice values**::
 
         class PastebinEntry(Form):
             language = SelectField('Programming Language', choices=[
-                Choice('cpp', 'C++'),
-                Choice('py', 'Python'),
-                Choice('text', 'Plain Text'),
+                SelectChoice('cpp', 'C++'),
+                SelectChoice('py', 'Python'),
+                SelectChoice('text', 'Plain Text'),
             ])
 
     Note that the `choices` keyword is evaluated each time the form is
@@ -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,10 +347,12 @@ 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():
-            return [Choice(g.id, g.name) for g in Group.query.order_by('name')]
+            return [SelectChoice(g.id, g.name) for g in Group.query.order_by('name')]
 
         class UserDetails(Form):
             group_id = SelectField('Group', coerce=int, choices=available_groups)
@@ -368,6 +368,18 @@ Choice Fields
     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::
+
+        def available_groups(form, field):
+            return [SelectChoice(g.id, g.name) for g in form.tenant.data.groups]
+
+        class UserDetails(Form):
+            tenant = QuerySelectField('Tenant', ...)
+            group_id = SelectField('Group', coerce=int, choices=available_groups)
+
     **Coerce function example**::
 
         def coerce_none(value):
@@ -377,9 +389,9 @@ Choice Fields
 
         class NonePossible(Form):
             my_select_field = SelectField('Select an option', choices=[
-                Choice('1', 'Option 1'),
-                Choice('2', 'Option 2'),
-                Choice('None', 'No option'),
+                SelectChoice('1', 'Option 1'),
+                SelectChoice('2', 'Option 2'),
+                SelectChoice('None', 'No option'),
             ], coerce=coerce_none)
 
     Note when the option None is selected a 'None' str will be passed. By using a coerce
@@ -388,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=Choice.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)``.
+
+    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::
 
-    :meth:`Choice.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)``.
+        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::
 
-        Choice.from_enum(Color, label=lambda item: item.name.title())
-        # → [Choice('RED', 'Red'), Choice('GREEN', 'Green'), Choice('BLUE', 'Blue')]
+        enum_choices(Color, label=lambda member: member.name.title())
+        # → [SelectChoice('red', 'Red'), SelectChoice('green', 'Green'), SelectChoice('blue', 'Blue')]
 
     **Skipping choice validation**::
 
@@ -442,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
 -------------
 
@@ -554,7 +586,7 @@ complex data structures such as lists and nested objects can be represented.
     FormField::
 
         class IMForm(Form):
-            protocol = SelectField(choices=[Choice('aim', 'AIM'), Choice('msn', 'MSN')])
+            protocol = SelectField(choices=[SelectChoice('aim', 'AIM'), SelectChoice('msn', 'MSN')])
             username = StringField()
 
         class ContactForm(Form):
@@ -576,7 +608,7 @@ Data Lists
     suggestions but the user may type any value. Combine with
     :class:`~wtforms.validators.AnyOf` if you need a closed set.
 
-    ``choices`` is either a list of :class:`~wtforms.fields.Choice`
+    ``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)``
@@ -644,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.0b1 → wtforms-3.3.0b3}/docs/widgets.rst

@@ -85,9 +85,8 @@ Inside the widget, the following ``field`` attributes are commonly used:
 - ``field._value()`` — the string representation of the current value, used
   for the ``value=`` attribute of inputs.
 - ``field.iter_choices()`` — for :class:`~wtforms.fields.SelectField` and
-  similar; yields :class:`~wtforms.fields.SelectChoice` objects with
-  ``value``, ``label``, ``render_kw`` and a ``_selected`` flag reflecting the
-  current selection.
+  similar; yields :class:`~wtforms.fields.Choice` objects with
+  ``value``, ``label``, ``selected`` and ``render_kw``.
 
 To assemble the HTML, use :func:`~wtforms.widgets.html_params` for attribute
 strings, :class:`markupsafe.Markup` to mark the result as safe, and

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

@@ -1,6 +1,8 @@
 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
@@ -40,7 +42,7 @@ from wtforms.fields.simple import URLField
 from wtforms.form import Form
 from wtforms.validators import ValidationError
 
-__version__ = "3.3.0b1"
+__version__ = "3.3.0b3"
 
 __all__ = [
     "validators",
@@ -84,4 +86,6 @@ __all__ = [
     "ColorField",
     "Choice",
     "SelectChoice",
+    "DataListChoice",
+    "enum_datalist",
 ]

wtforms-3.3.0b3/src/wtforms/_compat.py

@@ -0,0 +1,15 @@
+"""Compatibility helpers for different Python versions."""
+
+import inspect
+import sys
+
+if sys.version_info >= (3, 14):
+    from annotationlib import Format
+
+    def get_signature(callable):
+        return inspect.signature(callable, annotation_format=Format.FORWARDREF)
+
+else:
+
+    def get_signature(callable):
+        return inspect.signature(callable)

wtforms-3.3.0b3/src/wtforms/datalist.py

@@ -0,0 +1,127 @@
+import warnings
+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 Choice
+
+__all__ = ("DataList", "DataListChoice", "enum_datalist")
+
+
+@dataclass
+class DataListChoice:
+    """
+    An option declared via :class:`~wtforms.DataList`'s ``choices=``
+    parameter.
+
+    :param value:
+        The value rendered as the ``<option>``'s ``value`` attribute.
+    :param label:
+        The label of the option. Defaults to ``value`` when omitted.
+    :param render_kw:
+        A dict containing HTML attributes that will be rendered
+        with the option. Defaults to an empty dict when omitted.
+    """
+
+    value: str
+    label: str | None = None
+    render_kw: dict = field(default_factory=dict)
+
+    def __post_init__(self):
+        if self.label is None:
+            self.label = self.value
+
+    def __iter__(self):
+        return iter((self.value, self.label, self.render_kw))
+
+    @classmethod
+    def from_input(cls, input):
+        """Coerce a value passed by the user into a :class:`DataListChoice`."""
+        if isinstance(input, DataListChoice):
+            return input
+
+        if isinstance(input, Choice):
+            warnings.warn(
+                "Passing Choice to a DataList is deprecated; Choice is the "
+                "output type returned by iter_choices(). Use DataListChoice "
+                "instead. Support for Choice as input will be removed in "
+                "WTForms 4.0.",
+                DeprecationWarning,
+                stacklevel=4,
+            )
+            return cls(
+                value=input.value,
+                label=input.label,
+                render_kw=input.render_kw,
+            )
+
+        if isinstance(input, str):
+            return cls(value=input)
+
+        if isinstance(input, tuple):
+            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.
+
+    Passed to a :class:`~wtforms.Field` via its ``datalist=`` parameter
+    to add an autocomplete-style list of choices. See the WTForms
+    fields documentation for usage.
+    """
+
+    widget = widgets.DataListWidget()
+
+    def __init__(self, choices=None, *, render_kw=None, widget=None):
+        self._raw_choices = choices
+        self._choices = None if callable(choices) else choices
+        self.render_kw = render_kw or {}
+        if widget is not None:
+            self.widget = widget
+        self.id = None
+
+    def _clone(self, id):
+        clone = DataList.__new__(DataList)
+        clone._raw_choices = self._raw_choices
+        clone._choices = None if callable(self._raw_choices) else self._raw_choices
+        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 iter_choices(self, field=None):
+        raw = self._choices
+        if raw is None:
+            return []
+        return [DataListChoice.from_input(item) for item in raw]
+
+    def __call__(self, field=None, **kwargs):
+        return self.widget(self, field=field, **kwargs)

{wtforms-3.3.0b1 → 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",