WTForms 3.2.2__tar.gz → 3.3.0b2__tar.gz

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

@@ -1,5 +1,108 @@
 .. 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
+---------------
+
+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. :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` :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` :pr:`909`
+- Render ``False`` as ``value="False"`` in :class:`~fields.SelectField` options
+  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` :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` :pr:`910`
+- Add a ``tz`` parameter to :class:`~fields.DateTimeLocalField` to associate a
+  timezone with the input. :issue:`833` :pr:`905`
+- Add :class:`~fields.FieldList` ``insert_entry`` and indexed ``pop_entry``.
+  :issue:`256` :pr:`901` :pr:`912`
+- Add :class:`~fields.ButtonField` to render ``<button type="submit">``
+  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` :pr:`889`
+- ``<option>`` HTML attributes can be passed using
+  :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` :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` :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` :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. :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` :pr:`918`
+- Add an ``html_pattern`` keyword argument to :class:`~validators.Regexp`
+  to control the HTML ``pattern`` attribute emitted on supporting widgets.
+  :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` :pr:`921`
+
 Version 3.2.2
 -------------
 
@@ -44,7 +147,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.2 → wtforms-3.3.0b2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: WTForms
-Version: 3.2.2
+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.2.2 → wtforms-3.3.0b2}/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.2 → wtforms-3.3.0b2}/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.2 → wtforms-3.3.0b2}/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:: SelectChoice
+
+.. autoclass:: Choice
+
+.. autoclass:: RadioField(default field arguments, choices=None, coerce=str)
 
     .. code-block:: jinja
 
@@ -272,49 +303,82 @@ 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:`SelectChoice`.
       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:`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 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:`SelectChoice`.
 
 
     **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=[
+                SelectChoice('cpp', 'C++'),
+                SelectChoice('py', 'Python'),
+                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.
+    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>``.
 
-    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).
+        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 [SelectChoice(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()`.
+
+    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**::
 
@@ -324,11 +388,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=[
+                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
     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=SelectChoice.from_enum(Color), coerce=Color)
+
+    :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)``.
+
+    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::
+
+        SelectChoice.from_enum(Color, label=lambda item: item.name.title())
+        # → [SelectChoice('RED', 'Red'), SelectChoice('GREEN', 'Green'), SelectChoice('BLUE', 'Blue')]
+
     **Skipping choice validation**::
 
         class DynamicSelectForm(Form):
@@ -349,33 +443,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) }}
-
-.. autoclass:: TelField(default field arguments)
+Submit fields
+-------------
 
-.. autoclass:: TimeField(default field arguments, format='%H:%M')
+WTForms provides boolean and string-based submit controls.
 
-.. 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 +528,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 +553,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 +566,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=[SelectChoice('aim', 'AIM'), SelectChoice('msn', 'MSN')])
             username = StringField()
 
         class ContactForm(Form):
@@ -470,6 +575,92 @@ complex data structures such as lists and nested objects can be represented.
             im_accounts = FieldList(FormField(IMForm))
 
 
+Data Lists
+----------
+
+.. currentmodule:: wtforms
+
+.. autoclass:: DataListChoice
+
+.. 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.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::
+
+        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 +774,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.2 → wtforms-3.3.0b2}/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.2 → wtforms-3.3.0b2}/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.

{wtforms-3.2.2 → wtforms-3.3.0b2}/docs/validators.rst

@@ -15,15 +15,15 @@ Built-in validators
 
 .. autoclass:: wtforms.validators.DataRequired
 
-   This also sets the ``required`` :attr:`flag <wtforms.fields.Field.flags>` on
-   fields it is used on. This flag causes the ``required`` attribute to be
+   This also sets the :mdn-attr:`required` :attr:`flag <wtforms.fields.Field.flags>` on
+   fields it is used on. This flag causes the :mdn-attr:`required` attribute to be
    rendered in the tag, which prevents a request/response cycle for validation.
    This behavior can be overridden in the following ways:
 
    -   Specifying ``required=False`` when rendering in the template.
    -   Making a custom a widget that doesn't set it.
-   -   Rendering the ``novalidate`` attribute" on the ``form`` tag, or the
-       ``formnovalidate`` attribute on a submit button.
+   -   Rendering the :mdn-attr:`novalidate` attribute on the :mdn-tag:`form`
+       tag, or the :mdn-attr:`formnovalidate` attribute on a submit button.
 
    The ``required`` flag behavior also applies to the :class:`InputRequired` class.
 
@@ -57,6 +57,9 @@ Built-in validators
 
 .. autoclass:: wtforms.validators.NumberRange
 
+.. autoclass:: wtforms.validators.DateRange
+
+
 .. autoclass:: wtforms.validators.Optional
 
    This also sets the ``optional`` :attr:`flag <wtforms.fields.Field.flags>` on