WTForms 3.3.0b1__tar.gz → 3.3.0b2__tar.gz

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: WTForms
-Version: 3.3.0b1
+Version: 3.3.0b2
 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.0b2}/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
@@ -352,7 +352,7 @@ Choice Fields
     **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
@@ -395,9 +407,9 @@ Choice Fields
             BLUE = 3
 
         class PaintForm(Form):
-            color = SelectField(choices=Choice.from_enum(Color), coerce=Color)
+            color = SelectField(choices=SelectChoice.from_enum(Color), coerce=Color)
 
-    :meth:`Choice.from_enum` builds the option list from the Enum items;
+    :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
@@ -408,8 +420,8 @@ Choice Fields
     ``item.name``. To customise, pass a ``label`` callable taking an Enum
     item and returning the label string::
 
-        Choice.from_enum(Color, label=lambda item: item.name.title())
-        # → [Choice('RED', 'Red'), Choice('GREEN', 'Green'), Choice('BLUE', 'Blue')]
+        SelectChoice.from_enum(Color, label=lambda item: item.name.title())
+        # → [SelectChoice('RED', 'Red'), SelectChoice('GREEN', 'Green'), SelectChoice('BLUE', 'Blue')]
 
     **Skipping choice validation**::
 
@@ -554,7 +566,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):
@@ -568,6 +580,8 @@ Data Lists
 
 .. currentmodule:: wtforms
 
+.. autoclass:: DataListChoice
+
 .. class:: DataList(choices=None, *, render_kw=None, widget=None)
 
     A :mdn-tag:`datalist` of suggestions. Unlike
@@ -576,7 +590,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)``

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

@@ -1,6 +1,7 @@
 from wtforms import validators
 from wtforms import widgets
 from wtforms.datalist import DataList
+from wtforms.datalist import DataListChoice
 from wtforms.fields.choices import Choice
 from wtforms.fields.choices import RadioField
 from wtforms.fields.choices import SelectChoice
@@ -40,7 +41,7 @@ from wtforms.fields.simple import URLField
 from wtforms.form import Form
 from wtforms.validators import ValidationError
 
-__version__ = "3.3.0b1"
+__version__ = "3.3.0b2"
 
 __all__ = [
     "validators",
@@ -84,4 +85,5 @@ __all__ = [
     "ColorField",
     "Choice",
     "SelectChoice",
+    "DataListChoice",
 ]

wtforms-3.3.0b2/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.0b2/src/wtforms/datalist.py

@@ -0,0 +1,122 @@
+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 Choice
+
+__all__ = ("DataList", "DataListChoice")
+
+
+@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_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`."""
+        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)
+
+
+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)