refactor: introduce Choice and SelectChoice dataclasses

Choices can now be passed as Choice/SelectChoice instances, which
provides stronger typing, more explicit arguments and simpler code.

- passing choices as tuples is deprecated
- passing optgroups as a dict is deprecated
- <option> HTML attributes can be set via Choice.render_kw
- empty <optgroup> elements are no longer rendered

Author: azmeuk

CHANGES.rst

@@ -7,6 +7,10 @@ Unreleased
 
 - Fix :class:`~validators.Disabled` validation with provided formdata. :pr:`880`
 - End support for Python 3.9, start support for Python 3.14. :pr:`883`
+- :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`
 
 Version 3.2.1
 -------------

docs/fields.rst

@@ -260,7 +260,30 @@ 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:: SubmitField(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
 
@@ -274,47 +297,55 @@ refer to a single input from the form.
     Simply outputting the field without iterating its subfields will result in
     a ``<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)
 
     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 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 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).
+    **Select fields with ``<optgroup>``**::
+
+        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 that 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,7 +355,11 @@ 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.
@@ -349,29 +384,13 @@ 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)
-
-.. autoclass:: SelectMultipleField(default field arguments, choices=[], coerce=str, option_widget=None)
+.. autoclass:: SelectMultipleField(default field arguments, choices=None, coerce=str, option_widget=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)
-
-.. autoclass:: TimeField(default field arguments, format='%H:%M')
-
-.. autoclass:: URLField(default field arguments)
-
 
 Convenience Fields
 ------------------
@@ -461,7 +480,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):

docs/widgets.rst

@@ -90,13 +90,13 @@ class.  For example, here is a widget that renders a
         kwargs.setdefault('type', 'checkbox')
         field_id = kwargs.pop('id', field.id)
         html = ['<ul %s>' % html_params(id=field_id, class_=ul_class)]
-        for value, label, checked, render_kw in field.iter_choices():
-            choice_id = '%s-%s' % (field_id, value)
-            options = dict(kwargs, name=field.name, value=value, id=choice_id)
-            if checked:
+        for choice in field.iter_choices():
+            choice_id = '%s-%s' % (field_id, choice.value)
+            options = dict(kwargs, name=field.name, value=choice.value, id=choice_id)
+            if choice._selected:
                 options['checked'] = 'checked'
             html.append('<li><input %s /> ' % html_params(**options))
-            html.append('<label for="%s">%s</label></li>' % (choice_id, label))
+            html.append('<label for="%s">%s</label></li>' % (choice_id, choice.label))
         html.append('</ul>')
         return ''.join(html)
 

src/wtforms/__init__.py

@@ -1,6 +1,8 @@
 from wtforms import validators
 from wtforms import widgets
+from wtforms.fields.choices import Choice
 from wtforms.fields.choices import RadioField
+from wtforms.fields.choices import SelectChoice
 from wtforms.fields.choices import SelectField
 from wtforms.fields.choices import SelectFieldBase
 from wtforms.fields.choices import SelectMultipleField
@@ -76,4 +78,6 @@
     "URLField",
     "EmailField",
     "ColorField",
+    "Choice",
+    "SelectChoice",
 ]

src/wtforms/fields/__init__.py

@@ -1,4 +1,6 @@
+from wtforms.fields.choices import Choice
 from wtforms.fields.choices import RadioField
+from wtforms.fields.choices import SelectChoice
 from wtforms.fields.choices import SelectField
 from wtforms.fields.choices import SelectFieldBase
 from wtforms.fields.choices import SelectMultipleField
@@ -37,6 +39,8 @@
     "Field",
     "Flags",
     "Label",
+    "Choice",
+    "SelectChoice",
     "SelectField",
     "SelectMultipleField",
     "SelectFieldBase",