WTForms 3.2.2__tar.gz → 3.3.0__tar.gz

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

@@ -1,5 +1,116 @@
 .. currentmodule:: wtforms
 
+Version 3.3.0
+-------------
+
+Released 2026-10-23
+
+- Drop support for Python 3.10. Add support for Python 3.15.
+- Add native :class:`DataList` support. Options are declared with
+  :class:`DataListChoice`, or with the shorthand ``{value: label}``
+  dict syntax. :issue:`653` :issue:`886` :pr:`921`
+- Add :class:`~fields.ButtonField` to render ``<button type="submit">``
+  controls with string values. :issue:`784` :pr:`892`
+- 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`
+- Add :class:`~fields.FieldList` ``insert_entry`` and indexed ``pop_entry``.
+  The following entries are renumbered, with their ids and labels.
+  :issue:`256` :pr:`901` :pr:`912`
+- :class:`~fields.SelectField` refactor. Options are declared with
+  :class:`~fields.SelectChoice`, which takes HTML attributes in
+  ``render_kw`` and an ``optgroup``. ``iter_choices``
+  and ``iter_groups`` yield
+  :class:`~fields.Choice` objects. ``choices`` also accepts the shorthand
+  dict syntax: ``{value: label}`` for flat options and
+  ``{label: {value: label}}`` for optgroups. :issue:`692` :issue:`886`
+  :issue:`922` :pr:`739` :pr:`889`
+- ``choices`` callables on :class:`~fields.SelectField` and
+  :class:`DataList` may accept ``(form, field)``. They run on the
+  first read and their result is cached. Calling
+  :meth:`~form.BaseForm.post_process` again refreshes them, also for the
+  entries added with :meth:`~fields.FieldList.append_entry` and
+  :meth:`~fields.FieldList.insert_entry`. :issue:`922`
+- Add :func:`fields.enum_choices`, :func:`fields.enum_coerce` and
+  :func:`~datalist.enum_datalist` for Enum-backed choices. :issue:`338`
+  :issue:`922` :pr:`916`
+- 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. :class:`~fields.FieldList` entries
+  and :class:`~fields.SelectField` option subfields no longer get
+  ``form=None``. :issue:`922`
+- Add ``invalid_value_message`` and ``invalid_choice_message`` keyword
+  arguments for customizing built-in field error messages. On
+  :class:`~fields.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`` 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`
+- Numeric, date, time and select fields report a validation error instead of
+  raising a :class:`TypeError` when the input is not a string. :pr:`936`
+- Each bound field gets its own copy of ``render_kw``, and so does its
+  :class:`DataList`. Changing one of them on a form instance no
+  longer changes it on the other ones. :issue:`942`
+- Make :class:`~fields.FloatField` render as ``<input type="number">`` with
+  ``step="any"``. :issue:`677` :pr:`679`
+- Add a ``tz`` parameter to :class:`~fields.DateTimeLocalField` to associate a
+  timezone with the input. :issue:`833` :pr:`905`
+- Let :class:`~widgets.RangeInput` accept ``min`` and ``max`` at construction
+  time. :issue:`693` :pr:`898`
+- ``FieldList._add_entry`` routes through
+  :meth:`~meta.DefaultMeta.bind_field`, like the top-level fields. Custom
+  ``Meta.bind_field`` overrides were silently bypassed for
+  :class:`~fields.FieldList` entries. :pr:`891`
+- Reset :class:`~fields.FieldList` index state when reprocessing entries.
+  :issue:`874` :pr:`895`
+- Do not render a ``for`` attribute on the main label of
+  :class:`~fields.RadioField`. :issue:`775` :pr:`900`
+- Render ``False`` as ``value="False"`` in :class:`~fields.SelectField`
+  options instead of omitting the attribute. :issue:`878` :pr:`908`
+- Let render-time ``checked`` kwargs take precedence over the field's value
+  in :class:`~widgets.CheckboxInput` and :class:`~widgets.RadioInput`.
+  :issue:`706` :pr:`910`
+- Escape double quotes in ``Markup`` attribute values
+  passed to :func:`~widgets.html_params`, and return a
+  ``Markup``. :issue:`801` :pr:`906` :pr:`907`
+- Add ``test_environment`` support to :class:`~validators.Email`, and defer
+  to ``email_validator``'s module-level defaults for its
+  ``test_environment``, ``allow_smtputf8`` and ``allow_empty_local``
+  options. :issue:`869` :issue:`915` :pr:`894` :pr:`917`
+- Add ``matcher`` and ``html_pattern`` keyword arguments to
+  :class:`~validators.Regexp`. ``matcher`` overrides the matching function,
+  :func:`re.match` by default: pass :func:`re.search` or :func:`re.fullmatch`
+  to change the anchoring. ``html_pattern`` controls the HTML ``pattern``
+  attribute emitted on supporting widgets. :issue:`867` :pr:`759` :pr:`918`
+- :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`
+- 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`
+- Clarify the documentation of filters, and of :class:`~fields.SelectField`
+  ``choices``. :issue:`859` :issue:`875` :pr:`896` :pr:`909`
+- Update the Dutch and Serbian translations.
+- Deprecate :class:`~fields.DateTimeField`, which will be removed in WTForms
+  3.4. :issue:`831` :pr:`897`
+- Passing :class:`~fields.SelectField` ``choices`` as tuples, or as a dict
+  that is not the shorthand syntax, is deprecated and will be removed in
+  WTForms 3.4. Use :class:`~fields.SelectChoice` instead. :issue:`922`
+- Passing a callable to ``SelectFieldBase._choices_from_input`` is
+  deprecated and will be removed in WTForms 3.4.
+- For :class:`~fields.SelectField` subclasses, yielding raw tuples from
+  ``iter_choices`` or
+  ``iter_groups``, and overriding
+  ``Select.render_option`` with the pre-3.3 signature, are
+  deprecated and will be removed in WTForms 4.0. :issue:`922`
+
 Version 3.2.2
 -------------
 
@@ -44,7 +155,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.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: WTForms
-Version: 3.2.2
+Version: 3.3.0
 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,7 +44,7 @@ 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.10
+Requires-Python: >=3.11
 Requires-Dist: markupsafe>=1.1.1
 Provides-Extra: email
 Requires-Dist: email-validator>=2.0; extra == 'email'

{wtforms-3.2.2 → wtforms-3.3.0}/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.0}/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.0}/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
@@ -64,6 +67,7 @@ The Field base class
     .. automethod:: process(formdata [, data])
     .. automethod:: process_data
     .. automethod:: process_formdata
+    .. automethod:: post_process
     .. attribute:: data
 
         Contains the resulting (sanitized) value of calling either of the
@@ -135,7 +139,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 +224,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 +244,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 +271,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,50 +304,88 @@ 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'),
+            ])
+
+    A callable passed as `choices` is resolved separately for each form
+    instance, the first time its choices are read.
+    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).
+        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'),
+            ])
+
+    Use :class:`SelectChoice` to assign an option to an ``<optgroup>``.
 
     **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
+    Note we passed a callable to `choices` rather than a static list; it
+    produces fresh options per request. Its result is cached. Calling
+    :meth:`~wtforms.form.BaseForm.post_process` again refreshes it.
+
+    If the choices depend on data only available in the view, you can instead
+    assign `form.group_id.choices` after instantiation. A list assigned this
+    way replaces the callable.
+
+    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. The callable is invoked when the choices are read, normally
+    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):
@@ -324,11 +394,57 @@ 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
+        from wtforms.fields import enum_choices, enum_coerce
+
+        class Color(Enum):
+            RED = "red"
+            GREEN = "green"
+            BLUE = "blue"
+
+        class PaintForm(Form):
+            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::
+
+        class PaintForm(Form):
+            color = SelectField(
+                choices=enum_choices(Color, by="name"),
+                coerce=enum_coerce(Color, by="name"),
+            )
+
+    By default the option label is ``str(member)`` if the Enum defines its
+    own ``__str__`` (also the case for :class:`enum.StrEnum`), otherwise
+    ``member.name``. To customise, pass a ``label`` callable taking an Enum
+    member and returning the label string::
+
+        enum_choices(Color, label=lambda member: member.name.title())
+        # → [SelectChoice('red', 'Red'), SelectChoice('green', 'Green'), SelectChoice('blue', 'Blue')]
+
     **Skipping choice validation**::
 
         class DynamicSelectForm(Form):
@@ -349,33 +465,35 @@ 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
+.. autofunction:: wtforms.fields.enum_choices
 
-        {{ form.username(size=30, maxlength=50) }}
+.. autofunction:: wtforms.fields.enum_coerce
 
-.. 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 +554,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 +579,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 +592,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 +601,96 @@ 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.DataListChoice`
+    (or plain strings, in which case the string is used as both value
+    and label), a shorthand ``{value: label}`` dict, or a callable. The
+    callable runs when the datalist is rendered, after the whole form has been
+    processed. Its result is cached until the next
+    :meth:`~wtforms.form.BaseForm.post_process`. The callable may
+    take no argument (``fn()``) for a static list, or ``(form, field)``
+    to adapt the suggestions to the form data, for example the current
+    field value. This is convenient for server-side filtering::
+
+        DataList(lambda form, 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 form, 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.
+
+.. autoclass:: DataListChoice
+
+.. autofunction:: wtforms.datalist.enum_datalist
+
+.. currentmodule:: wtforms.fields
+
 Custom Fields
 -------------
 
@@ -583,8 +804,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.0}/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:
 
@@ -294,6 +294,8 @@ fields.
         this to provide form data to the enclosed fields. Accessing the field's
         data before calling process is not recommended.
 
+    .. automethod:: post_process
+
     .. automethod:: validate
 
     .. automethod:: __iter__