WTForms 3.2.1__tar.gz → 3.3.0b1__tar.gz

{wtforms-3.2.1 → wtforms-3.3.0b1}/.gitignore

@@ -15,3 +15,4 @@ __pycache__/
 /htmlcov/
 /docs/_build/
 /src/wtforms/locale/**/wtforms.mo
+uv.lock

wtforms-3.3.0b1/.hgignore

@@ -0,0 +1 @@
+.dotfiles/mercurial/.hgignore

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

@@ -1,5 +1,87 @@
 .. currentmodule:: wtforms
 
+Version 3.3.0b1
+---------------
+
+Released 2026-05-10
+
+- Add :class:`~validators.DateRange`. ``min`` and ``max`` may be callables
+  to compute dynamic bounds; :class:`~validators.NumberRange` accepts
+  callables on the same terms. :pr:`787`
+- Make :class:`~fields.FloatField` render as ``<input type="number">`` with
+  ``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`
+- 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`
+- Clarify that :class:`~fields.SelectField` ``choices`` is re-evaluated at
+  every form instantiation, including callables, in the documentation. :issue:`875`
+- Render ``False`` as ``value="False"`` in :class:`~fields.SelectField` options
+  instead of omitting the attribute. :issue:`878`
+- 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`
+- Let render-time ``checked`` kwargs take precedence over the field's value
+  in :class:`~widgets.CheckboxInput` and :class:`~widgets.RadioInput`.
+  :issue:`706`
+- Add a ``tz`` parameter to :class:`~fields.DateTimeLocalField` to associate a
+  timezone with the input. :issue:`833`
+- 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`
+- Add :class:`~fields.ButtonField` to render ``<button type="submit">``
+  controls with string values. :issue:`784`
+- :class:`~fields.SelectField` refactor. Choices tuples and dicts are
+  deprecated in favor of :class:`~fields.Choice`. :pr:`739`
+- ``<option>`` HTML attributes can be passed using
+  :class:`~fields.Choice`. :issue:`692` :pr:`739`
+- 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`
+- Defer to ``email_validator``'s module-level defaults for the
+  :class:`~validators.Email` ``test_environment``, ``allow_smtputf8`` and
+  ``allow_empty_local`` options. :issue:`915`
+- 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`
+- :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.
+- 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`
+- Add an ``html_pattern`` keyword argument to :class:`~validators.Regexp`
+  to control the HTML ``pattern`` attribute emitted on supporting widgets.
+  :issue:`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`
+
+Version 3.2.2
+-------------
+
+Released 2026-05-03
+
+- Fix :class:`~validators.Disabled` validation with provided formdata. :pr:`880`
+- End support for Python 3.9, start support for Python 3.14. :pr:`883`
+- Add Tamil and Serbian translations.
+
 Version 3.2.1
 -------------
 
@@ -35,7 +117,6 @@ Released 2024-10-20
    If you need to keep the old behavior you can set the ``_form_error_key``
    parameter of your form to :data:`None`.
 
-
 Version 3.1.2
 -------------
 

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: WTForms
-Version: 3.2.1
+Version: 3.3.0b1
 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,10 +44,10 @@ 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.9
-Requires-Dist: markupsafe
+Requires-Python: >=3.10
+Requires-Dist: markupsafe>=1.1.1
 Provides-Extra: email
-Requires-Dist: email-validator; extra == 'email'
+Requires-Dist: email-validator>=2.0; extra == 'email'
 Description-Content-Type: text/x-rst
 
 WTForms
@@ -86,11 +86,6 @@ with frameworks even better.
     validators.
 -   `WTForms-SQLAlchemy`_ provides ORM-backed fields and form generation
     from SQLAlchemy models.
--   `WTForms-AppEngine`_ provides ORM-backed fields and form generation
-    from AppEnding db/ndb schema
--   `WTForms-Django`_ provides ORM-backed fields and form generation
-    from Django models, as well as integration with Django's I18N
-    support.
 -   `WTForms-Bootstrap5`_ provides Bootstrap 5 favor renderer with
     great customizability.
 -   `Starlette-WTF`_ integrates with Starlette and the FastAPI
@@ -101,8 +96,6 @@ with frameworks even better.
 .. _Flask-WTF: https://flask-wtf.readthedocs.io/
 .. _WTForms-Alchemy: https://wtforms-alchemy.readthedocs.io/
 .. _WTForms-SQLAlchemy: https://github.com/pallets-eco/wtforms-sqlalchemy
-.. _WTForms-AppEngine: https://github.com/pallets-eco/wtforms-appengine
-.. _WTForms-Django: https://github.com/pallets-eco/wtforms-django
 .. _WTForms-Bootstrap5: https://github.com/LaunchPlatform/wtforms-bootstrap5
 .. _Starlette-WTF: https://github.com/muicss/starlette-wtf
 .. _Bootstrap-Flask: https://github.com/helloflask/bootstrap-flask

{wtforms-3.2.1 → wtforms-3.3.0b1}/README.rst

@@ -34,11 +34,6 @@ with frameworks even better.
     validators.
 -   `WTForms-SQLAlchemy`_ provides ORM-backed fields and form generation
     from SQLAlchemy models.
--   `WTForms-AppEngine`_ provides ORM-backed fields and form generation
-    from AppEnding db/ndb schema
--   `WTForms-Django`_ provides ORM-backed fields and form generation
-    from Django models, as well as integration with Django's I18N
-    support.
 -   `WTForms-Bootstrap5`_ provides Bootstrap 5 favor renderer with
     great customizability.
 -   `Starlette-WTF`_ integrates with Starlette and the FastAPI
@@ -49,8 +44,6 @@ with frameworks even better.
 .. _Flask-WTF: https://flask-wtf.readthedocs.io/
 .. _WTForms-Alchemy: https://wtforms-alchemy.readthedocs.io/
 .. _WTForms-SQLAlchemy: https://github.com/pallets-eco/wtforms-sqlalchemy
-.. _WTForms-AppEngine: https://github.com/pallets-eco/wtforms-appengine
-.. _WTForms-Django: https://github.com/pallets-eco/wtforms-django
 .. _WTForms-Bootstrap5: https://github.com/LaunchPlatform/wtforms-bootstrap5
 .. _Starlette-WTF: https://github.com/muicss/starlette-wtf
 .. _Bootstrap-Flask: https://github.com/helloflask/bootstrap-flask

{wtforms-3.2.1 → wtforms-3.3.0b1}/docs/conf.py

@@ -13,6 +13,7 @@ release, version = get_version("WTForms")
 master_doc = "index"
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinx.ext.extlinks",
     "sphinx.ext.intersphinx",
     "sphinx.ext.viewcode",
     "pallets_sphinx_themes",
@@ -22,6 +23,20 @@ extensions = [
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3/", None),
 }
+extlinks = {
+    "mdn-tag": (
+        "https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/%s",
+        "<%s>",
+    ),
+    "mdn-attr": (
+        "https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/%s",
+        "%s",
+    ),
+    "mdn-input": (
+        "https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input/%s",
+        '<input type="%s">',
+    ),
+}
 issues_github_path = "pallets-eco/wtforms"
 
 # HTML -----------------------------------------------------------------

{wtforms-3.2.1 → wtforms-3.3.0b1}/docs/crash_course.rst

@@ -133,6 +133,22 @@ providing with data. Typically, you will want to assign the values manually, but
 for this simple case it's perfect. It can also be useful for CRUD and admin
 forms.
 
+The same pattern extends to a collection of objects: a
+:class:`~wtforms.fields.FormField` describes one item, a
+:class:`~wtforms.fields.FieldList` holds the list, and ``obj`` /
+``populate_obj`` thread through both ends::
+
+    class ItemForm(Form):
+        name     = StringField()
+        quantity = IntegerField()
+
+    class CartForm(Form):
+        items = FieldList(FormField(ItemForm))
+
+    form = CartForm(request.form, obj=cart)  # cart.items == [item1, item2, ...]
+    if form.validate():
+        form.populate_obj(cart)
+
 
 Exploring in the console
 ^^^^^^^^^^^^^^^^^^^^^^^^

{wtforms-3.2.1 → wtforms-3.3.0b1}/docs/faq.rst

@@ -57,7 +57,7 @@ you should have no unicode issues.
 What versions of Python are supported?
 --------------------------------------
 
-WTForms supports Python 3.9+
+WTForms supports Python 3.10+
 
 
 How can I contribute to WTForms?

{wtforms-3.2.1 → wtforms-3.3.0b1}/docs/fields.rst

@@ -42,6 +42,9 @@ The Field base class
 
     .. automethod:: __init__
 
+    Built-in field processing messages can be customized per field with
+    ``invalid_value_message=``.
+
     **Validation**
 
     To validate the field, call its `validate` method, providing a form and any
@@ -135,7 +138,7 @@ The Field base class
     .. attribute:: label
 
         This is a :class:`Label` instance which when evaluated as a string
-        returns an HTML ``<label for="id">`` construct.
+        returns an HTML :mdn-tag:`label` construct.
 
     .. attribute:: default
 
@@ -220,6 +223,13 @@ refer to a single input from the form.
 
 .. autoclass:: DateTimeField(default field arguments, format='%Y-%m-%d %H:%M:%S')
 
+    .. warning::
+        :class:`DateTimeField` renders ``<input type="datetime">``, which is
+        obsolete in HTML and not broadly supported by browsers. Use
+        :class:`DateTimeLocalField` instead.
+
+        :class:`DateTimeField` is deprecated and will be removed in WTForms 3.4.
+
 .. autoclass:: DateTimeLocalField(default field arguments, format='%Y-%m-%d %H:%M:%S')
 
 .. autoclass:: DecimalField(default field arguments, places=2, rounding=None, use_locale=False, number_format=None)
@@ -233,7 +243,7 @@ refer to a single input from the form.
     Example usage::
 
         class UploadForm(Form):
-            image        = FileField('Image File', [validators.regexp('^[^/\\]\.jpg$')])
+            image        = FileField('Image File', [validators.regexp(r'^[^/\\]\.jpg$', matcher=re.fullmatch)])
             description  = TextAreaField('Image Description')
 
             def validate_image(form, field):
@@ -260,7 +270,28 @@ refer to a single input from the form.
 
 .. autoclass:: MonthField(default field arguments, format='%Y-%m')
 
-.. autoclass:: RadioField(default field arguments, choices=[], coerce=str)
+.. autoclass:: SearchField(default field arguments)
+
+.. autoclass:: StringField(default field arguments)
+
+   .. code-block:: jinja
+
+        {{ form.username(size=30, maxlength=50) }}
+
+.. autoclass:: TelField(default field arguments)
+
+.. autoclass:: TimeField(default field arguments, format='%H:%M')
+
+.. autoclass:: URLField(default field arguments)
+
+Choice Fields
+-------------
+
+.. autoclass:: Choice
+
+.. autoclass:: SelectChoice
+
+.. autoclass:: RadioField(default field arguments, choices=None, coerce=str)
 
     .. code-block:: jinja
 
@@ -272,49 +303,70 @@ refer to a single input from the form.
         {% endfor %}
 
     Simply outputting the field without iterating its subfields will result in
-    a ``<ul>`` list of radio choices.
+    a :mdn-tag:`ul` list of radio choices.
+
 
-.. class:: SelectField(default field arguments, choices=[], coerce=str, option_widget=None, validate_choice=True)
+.. class:: SelectField(default field arguments, choices=None, coerce=str, option_widget=None, validate_choice=True, invalid_value_message=None, invalid_choice_message=None)
 
     Select fields take a ``choices`` parameter which is either:
 
-    * a list of ``(value, label)`` or ``(value, label, render_kw)`` tuples.
+    * a list of :class:`Choice`.
       It can also be a list of only values, in which case the value is used
-      as the label. If set, the ``render_kw`` dictionnary will be rendered as
-      HTML ``<option>`` parameters. The value can be of any
+      as the label. The :class:`Choice` ``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 dictionary of ``{label: list}`` pairs defining groupings of options.
-    * a function taking no argument, and returning either a list or a dictionary.
+    * a function taking no argument, and returning a list of :class:`Choice`.
 
 
     **Select fields with static choice values**::
 
         class PastebinEntry(Form):
-            language = SelectField('Programming Language', choices=[('cpp', 'C++'), ('py', 'Python'), ('text', 'Plain Text')])
+            language = SelectField('Programming Language', choices=[
+                Choice('cpp', 'C++'),
+                Choice('py', 'Python'),
+                Choice('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.
+    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>``**::
 
-    Note that the `choices` keyword is only evaluated once, so if you want to make
-    a dynamic drop-down list, you'll want to assign the choices list to the field
-    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).
+        Use :class:`SelectChoice` to assign an option to an ``<optgroup>``.
+
+        class PastebinEntry(Form):
+            language = SelectField('Programming Language', choices=[
+                SelectChoice('cpp', 'C++', optgroup='Compiled'),
+                SelectChoice('rs', 'Rust', optgroup='Compiled'),
+                SelectChoice('py', 'Python', optgroup='Interpreted'),
+                SelectChoice('text', 'Plain Text'),
+            ])
 
     **Select fields with dynamic choice values**::
 
+        def available_groups():
+            return [Choice(g.id, g.name) for g in Group.query.order_by('name')]
+
         class UserDetails(Form):
-            group_id = SelectField('Group', coerce=int)
+            group_id = SelectField('Group', coerce=int, choices=available_groups)
 
         def edit_user(request, id):
             user = User.query.get(id)
             form = UserDetails(request.POST, obj=user)
-            form.group_id.choices = [(g.id, g.name) for g in Group.query.order_by('name')]
 
-    Note we didn't pass a `choices` to the :class:`~wtforms.fields.SelectField`
-    constructor, but rather created the list in the view function. Also, 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 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()`.
 
     **Coerce function example**::
 
@@ -324,11 +376,41 @@ refer to a single input from the form.
             return value
 
         class NonePossible(Form):
-            my_select_field = SelectField('Select an option', choices=[('1', 'Option 1'), ('2', 'Option 2'), ('None', 'No option')], coerce=coerce_none)
+            my_select_field = SelectField('Select an option', choices=[
+                Choice('1', 'Option 1'),
+                Choice('2', 'Option 2'),
+                Choice('None', 'No option'),
+            ], coerce=coerce_none)
 
     Note when the option None is selected a 'None' str will be passed. By using a coerce
     function the 'None' str will be converted to None.
 
+    **Select fields backed by an Enum**::
+
+        from enum import Enum
+
+        class Color(Enum):
+            RED = 1
+            GREEN = 2
+            BLUE = 3
+
+        class PaintForm(Form):
+            color = SelectField(choices=Choice.from_enum(Color), coerce=Color)
+
+    :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)``.
+
+    By default the option label is ``str(item)`` 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::
+
+        Choice.from_enum(Color, label=lambda item: item.name.title())
+        # → [Choice('RED', 'Red'), Choice('GREEN', 'Green'), Choice('BLUE', 'Blue')]
+
     **Skipping choice validation**::
 
         class DynamicSelectForm(Form):
@@ -349,33 +431,31 @@ refer to a single input from the form.
     a list of fields each representing an option. The rendering of this can be
     further controlled by specifying `option_widget=`.
 
-.. autoclass:: SearchField(default field arguments)
+    Use ``invalid_value_message=`` to customize errors raised when submitted
+    data cannot be coerced, and ``invalid_choice_message=`` to customize errors
+    raised when the value is not present in ``choices``.
 
-.. autoclass:: SelectMultipleField(default field arguments, choices=[], coerce=str, option_widget=None)
+.. autoclass:: SelectMultipleField(default field arguments, choices=None, coerce=str, option_widget=None, invalid_value_message=None, invalid_choice_message=None)
 
    The data on the SelectMultipleField is stored as a list of objects, each of
    which is checked and coerced from the form input.  Any submitted choices
    which are not in the given choices list will cause validation on the field
    to fail.
 
-.. autoclass:: SubmitField(default field arguments)
-
-.. autoclass:: StringField(default field arguments)
-
-   .. code-block:: jinja
-
-        {{ form.username(size=30, maxlength=50) }}
+Submit fields
+-------------
 
-.. autoclass:: TelField(default field arguments)
+WTForms provides boolean and string-based submit controls.
 
-.. autoclass:: TimeField(default field arguments, format='%H:%M')
-
-.. autoclass:: URLField(default field arguments)
+.. autoclass:: ButtonField(default field arguments)
 
+.. autoclass:: SubmitField(default field arguments)
 
 Convenience Fields
 ------------------
 
+.. currentmodule:: wtforms.fields
+
 .. autoclass:: HiddenField(default field arguments)
 
     HiddenField is useful for providing data from a model or the application to
@@ -436,11 +516,24 @@ complex data structures such as lists and nested objects can be represented.
 .. autoclass:: FieldList(unbound_field, default field arguments, min_entries=0, max_entries=None, separator='-')
 
     **Note**: Due to a limitation in how HTML sends values, FieldList cannot enclose
-    :class:`BooleanField` or :class:`SubmitField` instances.
+    :class:`BooleanField`, :class:`ButtonField`, or :class:`SubmitField`
+    instances.
 
     .. automethod:: append_entry([data])
+    .. automethod:: insert_entry(index[, data])
     .. automethod:: pop_entry
 
+    ``append_entry`` and ``insert_entry`` accept Python object data for the new
+    entry, not submitted formdata. For simple enclosed fields this is usually a
+    scalar value. For ``FieldList(FormField(...))``, this may be a dict or an
+    object that the enclosed form can process, similar to passing ``data`` or
+    ``obj`` when constructing that form.
+
+    Entries are kept with consecutive indices: ``insert_entry``,
+    ``pop_entry`` and rebuilds from formdata renumber entries so that each
+    entry's ``index``, ``name`` and ``id`` reflect its position in
+    :attr:`entries`.
+
     .. attribute:: entries
 
         Each entry in a FieldList is actually an instance of the field you
@@ -448,8 +541,8 @@ complex data structures such as lists and nested objects can be represented.
         FieldList works as expected, and proxies to the enclosed entries list.
 
         **Do not** resize the entries list directly, this will result in
-        undefined behavior. See `append_entry` and `pop_entry` for ways you can
-        manipulate the list.
+        undefined behavior. See `append_entry`, `insert_entry`, and `pop_entry`
+        for ways you can manipulate the list.
 
     .. automethod:: __iter__
     .. automethod:: __len__
@@ -461,7 +554,7 @@ complex data structures such as lists and nested objects can be represented.
     FormField::
 
         class IMForm(Form):
-            protocol = SelectField(choices=[('aim', 'AIM'), ('msn', 'MSN')])
+            protocol = SelectField(choices=[Choice('aim', 'AIM'), Choice('msn', 'MSN')])
             username = StringField()
 
         class ContactForm(Form):
@@ -470,6 +563,90 @@ complex data structures such as lists and nested objects can be represented.
             im_accounts = FieldList(FormField(IMForm))
 
 
+Data Lists
+----------
+
+.. currentmodule:: wtforms
+
+.. class:: DataList(choices=None, *, render_kw=None, widget=None)
+
+    A :mdn-tag:`datalist` of suggestions. Unlike
+    :class:`~wtforms.fields.SelectField`, the
+    input stays a free-form text input: the browser displays the
+    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`
+    (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::
+
+        DataList(lambda field: search(field.data))
+
+    **Inline DataList owned by a field**
+
+    Pass a :class:`DataList` instance directly as ``datalist=`` to get
+    a field-owned datalist with a unique id derived from the field's
+    id::
+
+        class F(Form):
+            country = StringField(datalist=DataList(["FR", "US"]))
+
+        {{ form.country() }}
+        {{ form.country.datalist() }}
+
+    ``{{ form.country() }}`` emits the ``<input list="...">`` and
+    ``{{ form.country.datalist() }}`` emits the matching
+    :mdn-tag:`datalist` element. Both calls are explicit, like
+    :attr:`Field.errors` or :attr:`Field.label` — you decide where each
+    piece appears in the DOM.
+
+    Inside a :class:`~wtforms.fields.FieldList`, each entry binds its
+    own clone of the inline :class:`DataList`, so a callable
+    ``choices`` sees each entry's own value::
+
+        class F(Form):
+            items = FieldList(
+                StringField(
+                    datalist=DataList(lambda field: suggest(field.data))
+                ),
+                min_entries=3,
+            )
+
+        {% for entry in form.items %}
+            {{ entry() }}
+            {{ entry.datalist() }}
+        {% endfor %}
+
+    **String references**
+
+    A field may also reference an existing datalist id directly by
+    string::
+
+        class F(Form):
+            field = StringField(datalist="external")
+
+    The ``list="external"`` attribute is emitted as-is — the user is
+    expected to render the :mdn-tag:`datalist` element themselves (in
+    a shared layout, a static template, or another form on the same
+    page). ``field.datalist()`` returns empty markup in this case, so
+    calling it unconditionally in templates is safe.
+
+    **Compatible fields**
+
+    Any field accepts a ``datalist=`` parameter, but only text-based
+    HTML inputs (``text``, ``search``, ``email``, ``tel``, ``url``,
+    ``number``, ``range``, ``color``, date/time inputs) honor the
+    ``list=`` attribute. Passing ``datalist=`` to a
+    :class:`~wtforms.fields.SelectField` or
+    :class:`~wtforms.fields.TextAreaField` is silently ignored by the
+    browser.
+
+
+.. currentmodule:: wtforms.fields
+
 Custom Fields
 -------------
 
@@ -583,8 +760,7 @@ Additional Helper Classes
 .. class:: Label
 
     On all fields, the `label` property is an instance of this class.
-    Labels can be printed to yield a
-    ``<label for="field_id">Label Text</label>``
+    Labels can be printed to yield a :mdn-tag:`label`
     HTML tag enclosure. Similar to fields, you can also call the label with
     additional html params.
 

{wtforms-3.2.1 → wtforms-3.3.0b1}/docs/forms.rst

@@ -151,11 +151,11 @@ The same principle applies for filters with the convention `filter_fieldname`::
     class SignupForm(Form):
         name = StringField('name')
 
-        def filter_name(form, field):
-            return field.strip()
+        def filter_name(form, value):
+            return value.strip() if value is not None else value
 
 Note that filters are applied after processing the default and incoming data,
-but before validation.
+but before validation. Filters should handle empty values such as `None`.
 
 .. _using-forms:
 

{wtforms-3.2.1 → wtforms-3.3.0b1}/docs/specific_problems.rst

@@ -124,10 +124,10 @@ Alternatively, you can create a field which does this by subclassing::
     class HiddenInteger(IntegerField):
         widget = HiddenInput()
 
-Some fields support even more sophisticated customization.For example, what if
-a multiple-select was desired where instead of using a multi-row ``<select>``,
-a series of checkboxes was used? By using widgets, one can get that behavior
-very easily::
+Some fields support even more sophisticated customization. For example, what if
+a multiple-select was desired where instead of using a multi-row
+:mdn-tag:`select`, a series of :mdn-input:`checkbox` controls was used? By
+using widgets, one can get that behavior very easily::
 
     class MultiCheckboxField(SelectMultipleField):
         """
@@ -140,4 +140,4 @@ very easily::
         option_widget = widgets.CheckboxInput()
 
 By overriding `option_widget`, our new multiple-select when iterated will now
-produce fields that render as checkboxes.
+produce fields that render as :mdn-input:`checkbox` controls.