CHANGES.rst
.. currentmodule:: wtforms
Released 2026-05-03
~validators.Disabled validation with provided formdata. :pr:880883Released 2024-10-21
~fields.SelectMultipleBase import. :issue:861 :pr:862Released 2024-10-20
Translations update: korean, chinese (traditional), portugese, russian, dutch, kazakh, swedish, turkish, slovak, ukranian, spanish, french.
Move the repository to the pallets-eco organization. :pr:854
Stop supporting Python 3.9 and start supporting Python 3.13 :pr:855
Removed required flag support from :class:~fields.HiddenWidget,
:class:~fields.RangeWidget and :class:~fields.SelectWidget to
conform to W3C :pr:810
:class:~wtforms.validators.NoneOf and :class:~wtforms.validators.AnyOf
can validate multiple valued fields like :class:~fields.SelectMultipleField
:pr:538 :pr:807
Use GHA and pre-commit workflows inspired from Flask. :pr:856 :pr:860
⚠️Breaking change⚠️: Some deprecated code was removed (:pr:859):
~wtforms.Flags can no longer be tuples. :issue:467iter_choices needs a tuple of 4 items :issue:816⚠️Breaking change⚠️: The key for form errors moved from :data:None to
empty string "". :issue:829 :pr:858
.. note::
If you need to keep the old behavior you can set the _form_error_key
parameter of your form to :data:None.
Released 2024-01-06
~fields.SelectMultipleField value coercion on validation.
:issue:822 :pr:823Released 2023-11-01
~wtforms.Flags values in their repr. :pr:808~fields.SelectField and :class:~fields.SelectMultipleField
choices can be None if validate_choice is False :pr:809812 :pr:815 :pr:817813818iter_choices
:pr:816Released 2023-10-10
726 :pr:733 :pr:749
:pr:767 :pr:788 :pr:789 :pr:793732 :pr:734 :pr:754~fields.ColorField :pr:755email_validator. :issue:727<option> attributes can be passed by the :class:~fields.SelectField
choices parameter :issue:692 :pr:739.
⚠️breaking change⚠️: iter_choices now returns a tuple of 4 items~fields.DateTimeLocalField :pr:761763~fields.DateTimeLocalField
defaults :pr:761794~fields.WeekField
defaults :pr:765796allow_ip parameter :pr:800~validators.ReadOnly and
:class:~validators.Disabled :pr:788`Released 2021-12-23
~fields.DateTimeField and other similar fields can
handle multiple formats. :issue:720 :pr:721722Released 2021-11-07
~fields.RadioField validators. :issue:477 :pr:615~fields.FormField.populate_obj always calls :func:setattr
:pr:675569 :pr:689~fields.RadioField render_kw rendering. :issue:490
:pr:628 :pr:688~fields.SelectField and
:class:~fields.SelectMultipleField. :issue:656 :pr:667701~fields.FieldList. :issue:681 :pr:694~fields.DateTimeField, :class:~fields.DateField and
:class:~fields.TimeField support time formats that removes leading
zeros. :pr:703fields/core.py and fields/simple.py :pr:710Released 2020-11-23
554~fields.StringField sets data to None when form
data is empty and an initial value was not provided. Although it
previously set an empty string, None is consistent with the
behavior of other fields. :pr:355430getattr/setattr with regular variable
access. :issue:482ValueError raised by a validator are handled like regular
exceptions. Validators need to raise
:class:~validators.ValidationError or
:class:~validators.StopValidation to make a validation fail.
:issue:445~fields.SelectField, :class:~fields.SelectMultipleField and
:class:~fields.RadioField choices parameter can be a callable.
:pr:608~fields.core.SelectMultipleField.
:issue:603 :pr:60555 :pr:595~wtforms.fields.core.MonthField. :pr:530 :pr:593form.BaseForm.process takes a
extra_filters parameter. :issue:128 :pr:592name argument to use a HTML name
different than their Python name. :issue:205, :pr:601for_ and class_ are normalized
consistently so later values override those specified earlier.
:issue:449, :pr:596DeprecationWarning is issued when tuples are used. :issue:406 :pr:467594 :pr:614~wtforms.fields.core.SelectField choices
are list of strings. :pr:598613 :pr:620 :pr:626 :pr:627~wtforms.fields.core.SelectMultipleField validate_choice
bugfix. :issue:606 :pr:642612 :pr:661form._get_translations. Use
:meth:Meta.get_translations <wtforms.meta.DefaultMeta.get_translations> instead.Released 2020-07-30
641Released 2020-07-29
~fields.SelectField choices shortcut at
form submission. :pr:598, 639Released 2020-04-22
wtforms.ext show a deprecation warning on import.
They will be removed in version 3.0.~fields.SelectField choices is None.
:issue:572, 585HTMLString and escape_html as aliases for
MarkupSafe functions. Their use shows a DeprecationWarning.
:issue:581, :pr:583Form.validate takes an extra_validators parameter, mapping
field names to lists of extra validator functions. This matches
BaseForm.validate. :pr:584Released 2020-04-21
~fields.SelectField uses list() to construct a new list
of choices. :pr:475HostnameValidation. :pr:463~validators.URL validator now allows query parameters in
the URL. :issue:523, :pr:524false_values param in BooleanField docs.
:issue:483, :pr:485471506, 514433FieldList error list keeps entries in order for easier
identification of which fields had errors. :issue:257, :pr:407~validators.Length gives a more helpful error message when
min and max are the same value. :pr:266~fields.SelectField no longer coerces None to
"None" allowing use of "None" as an option. :issue:289,
:pr:288~widgets.TextArea widget prepends a \r\n newline
when rendering to account for browsers stripping an initial line for
display. This does not affect the value. :issue:238, :pr:395~fields.html5.IntegerField and
:class:~fields.html5.RangeInput don't render the step="1"
attribute by default. :pr:343aria_ args are rendered the same way as data_ args, by
converting underscores to hyphens. aria_describedby="name-help"
becomes aria-describedby="name-help". :issue:239, :pr:389check_validators method to :class:~fields.Field which
checks if the given validators are both callable, and not classes.
:pr:298, 410form.errors is not cached and will update if an error is
appended to a field after access. :pr:568~wtforms.validators.NumberRange correctly handle NaN
values. :issue:505, :pr:548~fields.IntegerField checks input type when processing
data. :pr:451~fields.SelectField to skip choice
validation. :issue:434, :pr:493526326, 409~widgets.core.escape_html is removed,
replaced by :func:markupsafe.escape.
:class:~widgets.core.HTMLString is removed, replaced by
:class:markupsafe.Markup. :pr:400ipaddress
package. :issue:385, :pr:403~fields.core.Label text is escaped before rendering.
:issue:315, :pr:375email_validator. :pr:429Released 2018-06-07
~fields.StringField only sets data = '' when form data
is empty and an initial value was not provided. This fixes an issue
where the default value wasn't rendered with the initial form.
:issue:291, 401, :pr:355Released 2018-06-02
data_ args to render a field converts all the
underscores to hyphens when rendering the HTML attribute, not just
the first one. data_foo_bar becomes data-foo-bar. :pr:248~validators.UUID validator uses the :class:uuid.UUID
class instead of a regex. :pr:251~fields.SelectField copies the list of choices passed
to it so modifying an instance's choices will not modify the global
form definition. :pr:286~fields.Field.process_formdata even if the raw
data is empty. :pr:280~fields.MultipleFileField to handle a multi-file
input. :class:~fields.FileField continues to handle only one
value. The underlying :class:~widgets.FileInput widget gained a
multiple argument. :pr:281~fields.SelectField choices can contain HTML (MarkupSafe
Markup object or equivalent API) and will be rendered properly.
:pr:302fields.TimeField and html5.TimeField were added. :pr:254~validators.Email. Note that it is still
unreasonable to validate all emails with a regex and you should
prefer validating by actually sending an email. :pr:294required attribute when using a validator
that provides the 'required' flag, such as
:class:~validators.DataRequired. :pr:361~ext.sqlalchemy.fields.QuerySelectField to fail with
ValueError: too many values to unpack. :pr:391Released 2015-12-15
render_kw to allow default rendering time options.Released 2015-01-18
DeprecationWarnings./usr/share/locale for distro
packaging.Released 2014-07-01
Released 2014-05-20
class Meta paradigm for much more powerful customization
of WTForms.wtforms.ext.i18n.wtforms.ext.csrf.value=True.DecimalField able to use babel locale-based number
formatting.attr=False to WTForms widgets causes the value to be
ignored.Unique validator in wtforms.ext.sqlalchemy has been removed.form._get_translations. Use Meta.get_translations instead.Released 2013-09-10
ext.sqlalchemy and ext.appengine minor cleanups /
deprecation.false to be considered false
values for BooleanField (configurable). This is technically a
breaking change, but it is not likely to affect the majority of
users adversely.ext.i18n form allows passing LANGUAGES to the constructor.Released 2013-04-28
ext.appengine add NDB support.Released 2013-01-24
FieldList now can take validators on the entire FieldList.ext.sqlalchemy QuerySelectField.ext.sqlalchemy ColumnDefault conversion.ext.sqlalchemy supports Enum type.Released 2012-08-24
ext.sqlalchemy
model_form.Required validator into InputRequired and
DataRequired.AnyOf / NoneOf now work properly formatting other datatypes
than strings.Optional validator can optionally pass through whitespace.Released 2012-02-29
object_data to fields to get at the originally passed data.Released 2012-02-28
ext.csrf for a way to implement CSRF protection.ext.sqlalchemy supports PGInet, MACADDR, and UUID
field conversion.ext.sqlalchemy supports callable defaults.ext.appengine model_form now supports generating forms with
the same ordering as model.ext.appengine ReferencePropertyField now gets get_label
like the other ORM fields.Option widget can now take kwargs customization.DateTimeField can take time in microseconds..data to None on coercion error for
consistency.Released 2011-04-24
ext.django QuerySetSelectField and ModelSelectField now
accept get_label similar to sqlalchemy equivalents.ext.appengine model_form fixes for FloatField,
TimeField, and DateTimeField.ext.appengine ReferencePropertyField now properly stores
model object, not key.Released 2011-01-22
ext.appengine various field fixes.ext.appengine model_form changes.Optional with non-string input.Released 2010-09-17
ext.appengine ReferencePropertyField.Optional validator failed when raw_data was absentReleased 2010-04-25
__html__) so that compatible
templating engines will not auto-escape it.Field._default is now Field.default.raw_data property..ext) can be
iterated to produce options, and have an option_widget kwarg.FieldList,
Select(Multiple)Field, QuerySelectField to address
behavioral consistency.FloatField, based on IntegerField.ext.appengine now supports FloatProperty and
GeoPtProperty.ext.sqlalchemy QueryMultipleSelectField changed to
QuerySelectMultipleField.Released 2010-02-13
BaseForm class which provides the core processing and
validation functionality of Form without requiring declarative
subclassing.short_name property which is the un-prefixed
name.DecimalField now rounds values for display without float
coercion. See docs for details on how to format decimals.ext.sqlalchemy.fields now has an additional
QuerySelectMultipleField, and all fields can now support
multiple-column primary keys.ext.sqlalchemy.orm contains tools for making forms from ORM
models.ext.dateutil for flexible date-time parsing.ext.appengine contributed by Rodrigo Moraes.AnyOf and NoneOf validators.Released 2009-10-10
Form.auto_populate and Field.populate were renamed to
populate_obj to clarify that they populate another object, not
the Form or Field. This is an API breaking change.Released 2009-01-24
form['author']. This also has the intended effect of
making variable lookups in Django templates more reliable._unbound_fields property, and Field
construction now gives an instance of the new UnboundField class
instead of using a partial function application. These are both
internal changes and do not change the API.Released 2009-01-18
Form. There are also new pre_validate and
post_validate hooks on subfields, adding a great deal of
flexibility when dealing with field-level validation. Note that this
is an API breaking change if you have any subfields that override
Field.validate. These will need to be updated to use the new
hooks.process_data no longer accepts the has_formdata parameter.process_data will be called only
once for each field. If a model object is provided which contains
the property, then this value is used. Otherwise, a keyword argument
if specified is used. Failing that, the field's default value is
used.process_formdata will be called after
process_data for each field. If no form data is available for
the given field, it is called with an empty list.wtforms.ext.django has been overhauled, both to mirror features
and changes of the Django 1.0 release, and to add some useful fields
for working with Django ORM data in forms.checker keyword argument to SelectField,
SelectMultipleField, and RadioField has been renamed to
coerce to reflect the actual functionality of this callable.Released 2009-01-13
flags property which contain boolean flags
that are set either by the field itself or validators being
specified on a field. The flags can then be used in checks in
template or Python code.Field, accessible on the
field as description. This provides an easy way to define e.g.
help text in the same place as the form.not_empty validator in
favour of two validators, optional and required. The new validators
allow control over the validation chain in addition to checking
emptiness.wtforms.contrib to wtforms.ext and reorganised
wtforms.ext.django. This is a breaking change if you were using
the Django extensions, but should only require changing your imports
around a little.Released 2008-07-25