WTForms 3.0

https://github.com/wtforms/wtforms/milestones/3.0

WTForms 3.0

WTForms for a while has required a redesign to reflect the way things are going in how people actually use forms. WTforms 2.0 was a bridge version, a way to make a major version that hints at the upcoming changes but have it be compatible with the majority of people's existing code and form classes,while also letting people be aware of pending deprecation.

Overview

• Proper support for input data in other forms than just form input. (ahem, JSON) #198
• Make it clearer the distinction between fields, data type coercion, and widgets in a way that doesn't give users headaches, and enables easy use.
  • Distinguish fields that only use one value, use zero or one value, or use multiple values, and allow compatibility to be had based on some of these facets.
  • Simplify the general use case for the vast majority of field implementations
  • Decouple the way fields access form values from the way that coercion happens, to allow easy implementation for third-party libraries
  • Decouple widgets (describing the nature of a widget) from rendering (HTML, XHTML, HTML5, etc) #234 (#180 ... others)
• Better and easier to use form composition tools, and multi-value fields.

Major Features

• Input instead of coming as a disparate collection of parameters, is now put into a specialty data class FormInput
  • FormInput holds and gates access to multiple input data types, including "models", defaults, JSON/dictionary input, and form data.
  • An API of clearly defined methods allows fields to get input data without caring as much about how this data comes and implementation details behind it
  • Having this clear API contract allows this object to be replaced with anything else satisfying the contract (better support for many other frameworks) and also behaviors such as defining the priority of what to do with missing data on a global level.
  • For maximum compatibilty, the old formdata, obj, **kwargs type data can still be supplied, but a FormInput will be created with these.
• Kill off SelectField, or make it less sucky #185
  • In wtforms 1&2, the biggest problem encountered was that, for example, handling multiple Decimal values with coerce=Decimal was not symmetric to all the capabilities provided by DecimalField
  • (Potential) If we could allow multiple choices for any field type, then it more strongly reinforces the idea of a field-per-datatype e.g. DecimalField(choices=[...]) and so on.
• Make field enclosures less of a headache to use
  • FormField and FieldList are very capable, but there has to be a better way, especially in the fringe cases.
• De-couple attribute names from field names #205
  • Allow users to have fields with names containing "special" characters while still allowing the field to function, just like SQLAlchemy with attribute vs column names.
  • Default case (when attribute name unspecified) is still using attribute name munging for maximum compatibility

Cleanups

• Required validator behaviour #255

Start with the WTForms 3.0 milestone and review the referenced issues #198, #234, #180, #185, #205, and #255. Before coding, narrow the roadmap to one agreed feature; done means that feature's scope, compatibility impact, and acceptance criteria are defined and implemented.