Changes¶
Version 3.1.2¶
Released 2024-01-06
Fix
SelectMultipleFieldvalue coercion on validation. #822 #823
Version 3.1.1¶
Released 2023-11-01
Display
Flagsvalues in their repr. #808SelectFieldandSelectMultipleFieldchoicescan be None if validate_choice is False #809Unit tests improvements #813
Python 3.12 support #818
Restored support for 3-items tuple return value from iter_choices #816
Version 3.1.0¶
Released 2023-10-10
Documentation improvements #726 #733 #749 #767 #788 #789 #793
Implement
ColorField#755Delayed import of
email_validator. #727<option>attributes can be passed by theSelectFieldchoicesparameter #692 #739. ⚠️breaking change⚠️: iter_choices now returns a tuple of 4 itemsUse the standard datetime formats by default for
DateTimeLocalField#761Python 3.11 support #763
Added shorter format to
DateTimeLocalFielddefaults #761Stop support for python 3.7 #794
Added shorter format to
WeekFielddefaults #765Move to pyproject.toml #796
URL validator takes a
allow_ipparameter #800
Version 3.0.1¶
Released 2021-12-23
Fixed
DateTimeFieldand other similar fields can handle multiple formats. #720 #721Stop support for python 3.6 #722
Version 3.0.0¶
Released 2021-11-07
Fixed
RadioFieldvalidators. #477 #615Fixed
RadioFieldrender_kw rendering. #490 #628 #688Support for optgroups in
SelectFieldandSelectMultipleField. #656 #667Minor documentation fix. #701
DateTimeField,DateFieldandTimeFieldsupport time formats that removes leading zeros. #703Refactoring: split fields/core.py and fields/simple.py #710
Version 3.0.0a1¶
Released 2020-11-23
Drop support for Python < 3.6. #554
StringFieldsetsdatatoNonewhen form data is empty and an initial value was not provided. Although it previously set an empty string,Noneis consistent with the behavior of other fields. #355Specified version of Babel required for setup to avoid errors. #430
Replaced use of
getattr/setattrwith regular variable access. #482ValueErrorraised by a validator are handled like regular exceptions. Validators need to raiseValidationErrororStopValidationto make a validation fail. #445SelectField,SelectMultipleFieldandRadioFieldchoices parameter can be a callable. #608Filters can be inline.
form.BaseForm.process()takes a extra_filters parameter. #128 #592Fields can be passed the
nameargument to use a HTML name different than their Python name. #205, #601Render attribute names like
for_andclass_are normalized consistently so later values override those specified earlier. #449, #596Flags should now be stored in dicts and can take non-boolean values. A
DeprecationWarningis issued when tuples are used. #406 #467Fixed a bug when the
SelectFieldchoices are list of strings. #598Fixed SelectMultipleField validation when using choices list shortcut. #612 #661
Removed
form._get_translations(). UseMeta.get_translationsinstead.
Version 2.3.3¶
Released 2020-07-30
This release includes the translation files that were missing in the 2.3.2 release. #641
Version 2.3.2¶
Released 2020-07-29
Fixed a bug with
SelectFieldchoices shortcut at form submission. #598, #639
Version 2.3.1¶
Released 2020-04-22
All modules in
wtforms.extshow a deprecation warning on import. They will be removed in version 3.0.Fixed a bug when
SelectFieldchoices isNone. #572, #585Restored
HTMLStringandescape_htmlas aliases for MarkupSafe functions. Their use shows aDeprecationWarning. #581, #583Form.validatetakes anextra_validatorsparameter, mapping field names to lists of extra validator functions. This matchesBaseForm.validate. #584Update locale catalogs.
Version 2.3.0¶
Released 2020-04-21
Drop support for Python 2.6, 3.3, and 3.4.
SelectFielduseslist()to construct a new list of choices. #475Permitted underscores in
HostnameValidation. #463URLvalidator now allows query parameters in the URL. #523, #524Fixed broken format string in Arabic translation #471
Updated Ukrainian translation. #433
FieldListerror list keeps entries in order for easier identification of which fields had errors. #257, #407Lengthgives a more helpful error message whenminandmaxare the same value. #266SelectFieldno longer coercesNoneto"None"allowing use of"None"as an option. #289, #288The
TextAreawidget prepends a\r\nnewline when rendering to account for browsers stripping an initial line for display. This does not affect the value. #238, #395HTML5
IntegerFieldandRangeInputdon’t render thestep="1"attribute by default. #343aria_args are rendered the same way asdata_args, by converting underscores to hyphens.aria_describedby="name-help"becomesaria-describedby="name-help". #239, #389Added a
check_validatorsmethod toFieldwhich checks if the given validators are both callable, and not classes. #298, #410form.errorsis not cached and will update if an error is appended to a field after access. #568NumberRangecorrectly handle NaN values. #505, #548IntegerFieldchecks input type when processing data. #451Added a parameter to
SelectFieldto skip choice validation. #434, #493Choices which name and data are the same do not need to use tuples. #526
HTML is escaped using MarkupSafe instead of the previous internal implementation.
escape_html()is removed, replaced bymarkupsafe.escape().HTMLStringis removed, replaced bymarkupsafe.Markup. #400Fixed broken IPv6 validator, validation now uses the
ipaddresspackage. #385, #403Email validation is now handled by an optional library,
email_validator. #429
Version 2.2.1¶
Released 2018-06-07
StringFieldonly setsdata = ''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. #291, #401, #355
Version 2.2¶
Released 2018-06-02
Merged new and updated translations from the community.
Passing
data_args to render a field converts all the underscores to hyphens when rendering the HTML attribute, not just the first one.data_foo_barbecomesdata-foo-bar. #248The
UUIDvalidator uses theuuid.UUIDclass instead of a regex. #251SelectFieldcopies the list ofchoicespassed to it so modifying an instance’s choices will not modify the global form definition. #286Fields call
process_formdata()even if the raw data is empty. #280Added a
MultipleFileFieldto handle a multi-file input.FileFieldcontinues to handle only one value. The underlyingFileInputwidget gained amultipleargument. #281SelectFieldchoices can contain HTML (MarkupSafeMarkupobject or equivalent API) and will be rendered properly. #302fields.TimeFieldandhtml5.TimeFieldwere added. #254Improved
Email. Note that it is still unreasonable to validate all emails with a regex and you should prefer validating by actually sending an email. #294Widgets render the
requiredattribute when using a validator that provides the'required'flag, such asDataRequired. #361Fix a compatibility issue with SQLAlchemy 1.2 that caused
QuerySelectFieldto fail withValueError: too many values to unpack. #391
Version 2.1¶
Released 2015-12-15
Added
render_kwto allow default rendering time options.Updated / added a number of localizations.
Updated docs.
Allow widgets to set flags.
Version 2.0.2¶
Released 2015-01-18
Added more localizations and updated some.
Validators for email and URL can validate IDNA-encoded domain names and new TLDs.
Better
DeprecationWarnings.Support localization files in
/usr/share/localefor distro packaging.
Version 2.0.1¶
Released 2014-07-01
Update wheel install to conditionally install ordereddict for Python 2.6.
Doc improvements.
Version 2.0¶
Released 2014-05-20
Add new
class Metaparadigm for much more powerful customization of WTForms.Move i18n into core. Deprecate
wtforms.ext.i18n.Move CSRF into core. Deprecate
wtforms.ext.csrf.Fix issue rendering SelectFields with
value=True.Make
DecimalFieldable to use babel locale-based number formatting.Drop Python 3.2 support (Python3 support for 3.3+ only).
Passing
attr=Falseto WTForms widgets causes the value to be ignored.Uniquevalidator inwtforms.ext.sqlalchemyhas been removed.Deprecate
form._get_translations. UseMeta.get_translationsinstead.
Version 1.0.5¶
Released 2013-09-10
Fix a bug in validators which causes translations to happen once then clobber any future translations.
ext.sqlalchemyandext.appengineminor cleanups / deprecation.Allow blank string and the string
falseto be considered false values forBooleanField(configurable). This is technically a breaking change, but it is not likely to affect the majority of users adversely.ext.i18nform allows passingLANGUAGESto the constructor.
Version 1.0.4¶
Released 2013-04-28
Add widgets and field implementations for HTML5 specialty input types.
ext.appengineadd NDB support.Add translations for Korean, Traditional Chinese.
Version 1.0.3¶
Released 2013-01-24
Tests complete in python 3.2/3.3.
Localization for ru, fr.
Minor fixes in documentation for clarity.
FieldListnow can take validators on the entireFieldList.Fix issue with
ext.sqlalchemyQuerySelectField.Fix issue in
ext.sqlalchemyColumnDefaultconversion.ext.sqlalchemysupportsEnumtype.Field class now allows traversal in Django 1.4 templates.
Version 1.0.2¶
Released 2012-08-24
We now support Python 2.x and 3.x on the same codebase, thanks to a lot of hard work by Vinay Sajip.
Add in ability to convert relationships to
ext.sqlalchemymodel_form.Built-in localizations for more languages.
Distinguish
Requiredvalidator intoInputRequiredandDataRequired.Better IP address validation, including IPv6 support.
AnyOf/NoneOfnow work properly formatting other datatypes than strings.Optionalvalidator can optionally pass through whitespace.
Version 1.0.1¶
Released 2012-02-29
Fixed issues related to building for Python 3 and Python pre-releases.
Add
object_datato fields to get at the originally passed data.
Version 1.0¶
Released 2012-02-28
Output HTML5 compact syntax by default.
Substantial code reorg, cleanup, and test improvements.
Added
ext.csrffor a way to implement CSRF protection.ext.sqlalchemysupportsPGInet,MACADDR, andUUIDfield conversion.ext.sqlalchemysupports callable defaults.ext.appenginemodel_formnow supports generating forms with the same ordering as model.ext.appengineReferencePropertyFieldnow getsget_labellike the other ORM fields.Add localization support for WTForms built-in messages.
Python 3 support (via 2to3).
An empty label string can be specified on fields if desired.
Optionwidget can now take kwargs customization.Field subclasses can provide default validators as a class property.
DateTimeFieldcan take time in microseconds.Numeric fields all set
.datatoNoneon coercion error for consistency.
Version 0.6.3¶
Released 2011-04-24
Documentation: Substantial documentation improvements, including adding Crash Course as a Sphinx document.
ext.djangoQuerySetSelectFieldandModelSelectFieldnow acceptget_labelsimilar to sqlalchemy equivalents.ext.appenginemodel_formfixes forFloatField,TimeField, andDateTimeField.ext.appengineReferencePropertyFieldnow properly stores model object, not key.
Version 0.6.2¶
Released 2011-01-22
ext.appenginevarious field fixes.ext.appenginemodel_formchanges.Fix issue in
Optionalwith non-string input.Make numeric fields more consistent.
Improve test coverage substantially.
Version 0.6.1¶
Released 2010-09-17
ext.appengineReferencePropertyField.Dateutil fields render issue, and consistency issue.
Optionalvalidator failed whenraw_datawas absentDocumentation: docs now mention HTML escaping functionality.
Add preliminary support for providing a translations object that can translate built-in validation and coercion errors.
Version 0.6¶
Released 2010-04-25
HTML is now marked as safe (using
__html__) so that compatible templating engines will not auto-escape it.Field._defaultis nowField.default.All fields now have a
raw_dataproperty.Fields which are select fields (including those in
.ext) can be iterated to produce options, and have anoption_widgetkwarg.Minor bugfixes and cleanup in
FieldList,Select(Multiple)Field,QuerySelectFieldto address behavioral consistency.Added
FloatField, based onIntegerField.ext.appenginenow supportsFloatPropertyandGeoPtProperty.ext.sqlalchemyQueryMultipleSelectFieldchanged toQuerySelectMultipleField.
Version 0.5¶
Released 2010-02-13
Added a
BaseFormclass which provides the core processing and validation functionality ofFormwithout requiring declarative subclassing.Field labels now default to a humanized field name.
Fields now have a
short_nameproperty which is the un-prefixed name.DecimalFieldnow rounds values for display without float coercion. See docs for details on how to format decimals.ext.sqlalchemy.fieldsnow has an additionalQuerySelectMultipleField, and all fields can now support multiple-column primary keys.ext.sqlalchemy.ormcontains tools for making forms from ORM models.Added
ext.dateutilfor flexible date-time parsing.Added
ext.appenginecontributed by Rodrigo Moraes.Added
AnyOfandNoneOfvalidators.
Version 0.4¶
Released 2009-10-10
Fields have much greater control over input processing. Filters have been added to implement a simple way to transform input data.
Added fields that encapsulate advanced data structures such as dynamic lists or child forms for more powerful field composing.
Fields now use widgets for rendering.
All built-in validators have been converted to classes to clean up the code.
Form.auto_populateandField.populatewere renamed topopulate_objto clarify that they populate another object, not the Form or Field. This is an API breaking change.Dropped support for Python 2.3.
Version 0.3.1¶
Released 2009-01-24
Several fixes were made to the code and tests to make WTForms compatible with Python 2.3/2.4.
Form’s properties can now be accessed via dictionary-style access such as
form['author']. This also has the intended effect of making variable lookups in Django templates more reliable.Form and Field construction changes: Form now uses a metaclass to handle creating its
_unbound_fieldsproperty, and Field construction now gives an instance of the newUnboundFieldclass instead of using a partial function application. These are both internal changes and do not change the API.
Version 0.3¶
Released 2009-01-18
Fields are now responsible for their own validation, instead of mostly relying on
Form. There are also newpre_validateandpost_validatehooks 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 overrideField.validate. These will need to be updated to use the new hooks.process_datano longer accepts thehas_formdataparameter.At form instantiation time,
process_datawill 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.If any form data is sent,
process_formdatawill be called afterprocess_datafor each field. If no form data is available for the given field, it is called with an empty list.wtforms.ext.djangohas 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.The
checkerkeyword argument toSelectField,SelectMultipleField, andRadioFieldhas been renamed tocoerceto reflect the actual functionality of this callable.
Version 0.2¶
Released 2009-01-13
We have documentation and unit tests!
Fields now have a
flagsproperty 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.Changed the way fields take parameters, they are no longer quasi magic. This is a breaking change. Please see the documentation for the new syntax.
Added optional description argument to
Field, accessible on the field asdescription. This provides an easy way to define e.g. help text in the same place as the form.Added new semantics for validators which can stop the validation chain, with or without errors.
Added a regexp validator, and removed the
not_emptyvalidator in favour of two validators, optional and required. The new validators allow control over the validation chain in addition to checking emptiness.Renamed
wtforms.contribtowtforms.extand reorganisedwtforms.ext.django. This is a breaking change if you were using the Django extensions, but should only require changing your imports around a little.Better support for other frameworks such as Pylons.
Version 0.1¶
Released 2008-07-25
Initial release.