Extensions¶
Warning
Deprecated since version 2.0: Everything in wtforms.ext
is deprecated and will be removed
in WTForms 3.0.
WTForms ships with a number of extensions that make it easier to work with other frameworks and libraries, such as Django.
Appengine¶
Warning
Deprecated since version 2.0: wtforms.ext.appengine
is deprecated and will be removed in
WTForms 3.0. Use WTForms-Appengine instead.
WTForms includes support for AppEngine fields as well as auto-form generation from models.
Model Forms¶
See the module docstring for examples on how to use model_form()
.
-
wtforms.ext.appengine.db.
model_form
(model, base_class=Form, only=None, exclude=None, field_args=None, converter=None)[source]¶ Creates and returns a dynamic
wtforms.Form
class for a givendb.Model
class. The form class can be used as it is or serve as a base for extended form classes, which can then mix non-model related fields, subforms with other model forms, among other possibilities.- Parameters:
model – The
db.Model
class to generate a form for.base_class – Base form class to extend from. Must be a
wtforms.Form
subclass.only – An optional iterable with the property names that should be included in the form. Only these properties will have fields.
exclude – An optional iterable with the property names that should be excluded from the form. All other properties will have fields.
field_args – An optional dictionary of field names mapping to keyword arguments used to construct each field object.
converter – A converter to generate the fields based on the model properties. If not set,
ModelConverter
is used.
Datastore-backed Fields¶
-
class
wtforms.ext.appengine.fields.
ReferencePropertyField
(default field arguments, reference_class=None, get_label=None, allow_blank=False, blank_text='')[source]¶ A field for
db.ReferenceProperty
. The list items are rendered in a select.- Parameters:
reference_class – A db.Model class which will be used to generate the default query to make the list of items. If this is not specified, The query property must be overridden before validation.
get_label – If a string, use this attribute on the model class as the label associated with each option. If a one-argument callable, this callable will be passed model instance and expected to return the label text. Otherwise, the model object’s __str__ or __unicode__ will be used.
allow_blank – If set to true, a blank choice will be added to the top of the list to allow None to be chosen.
blank_text – Use this to override the default blank option’s label.
NDB¶
WTForms includes support for NDB models and can support mapping the relationship fields as well as generating forms from models.
-
class
wtforms.ext.appengine.fields.
KeyPropertyField
(default field arguments, reference_class=None, get_label=None, allow_blank=False, blank_text='')[source]¶ A field for
ndb.KeyProperty
. The list items are rendered in a select.- Parameters:
reference_class – A db.Model class which will be used to generate the default query to make the list of items. If this is not specified, The query property must be overridden before validation.
get_label – If a string, use this attribute on the model class as the label associated with each option. If a one-argument callable, this callable will be passed model instance and expected to return the label text. Otherwise, the model object’s __str__ or __unicode__ will be used.
allow_blank – If set to true, a blank choice will be added to the top of the list to allow None to be chosen.
blank_text – Use this to override the default blank option’s label.
-
wtforms.ext.appengine.ndb.
model_form
(model, base_class=Form, only=None, exclude=None, field_args=None, converter=None)[source]¶ Creates and returns a dynamic
wtforms.Form
class for a givenndb.Model
class. The form class can be used as it is or serve as a base for extended form classes, which can then mix non-model related fields, subforms with other model forms, among other possibilities.- Parameters:
model – The
ndb.Model
class to generate a form for.base_class – Base form class to extend from. Must be a
wtforms.Form
subclass.only – An optional iterable with the property names that should be included in the form. Only these properties will have fields.
exclude – An optional iterable with the property names that should be excluded from the form. All other properties will have fields.
field_args – An optional dictionary of field names mapping to keyword arguments used to construct each field object.
converter – A converter to generate the fields based on the model properties. If not set,
ModelConverter
is used.
Dateutil¶
Warning
Deprecated since version 2.0: wtforms.ext.dateutil
is deprecated and will be removed in
WTForms 3.0.
For better date-time parsing using the python-dateutil package,
wtforms.ext.dateutil
provides a set of fields to use to accept a wider
range of date input.
-
class
wtforms.ext.dateutil.fields.
DateTimeField
(default field arguments, parse_kwargs=None, display_format='%Y-%m-%d %H:%M')[source]¶ DateTimeField represented by a text input, accepts all input text formats that dateutil.parser.parse will.
- Parameters:
parse_kwargs – A dictionary of keyword args to pass to the dateutil parse() function. See dateutil docs for available keywords.
display_format – A format string to pass to strftime() to format dates for display.
-
class
wtforms.ext.dateutil.fields.
DateField
(default field arguments, parse_kwargs=None, display_format='%Y-%m-%d')[source]¶ Same as the DateTimeField, but stores only the date portion.
Django¶
Warning
Deprecated since version 2.0: wtforms.ext.django
is deprecated and will be removed in
WTForms 3.0. Use WTForms-Django instead.
This extension provides templatetags to make it easier to work with Django templates and WTForms’ html attribute rendering. It also provides a generator for automatically creating forms based on Django ORM models.
Model forms¶
-
wtforms.ext.django.orm.
model_form
(model, base_class=Form, only=None, exclude=None, field_args=None, converter=None)[source]¶ Create a wtforms Form for a given Django model class:
from wtforms.ext.django.orm import model_form from myproject.myapp.models import User UserForm = model_form(User)
- Parameters:
model – A Django ORM model class
base_class – Base form class to extend from. Must be a
wtforms.Form
subclass.only – An optional iterable with the property names that should be included in the form. Only these properties will have fields.
exclude – An optional iterable with the property names that should be excluded from the form. All other properties will have fields.
field_args – An optional dictionary of field names mapping to keyword arguments used to construct each field object.
converter – A converter to generate the fields based on the model properties. If not set,
ModelConverter
is used.
model_form()
attempts to glean as much metadata as possible from inspecting the model’s fields, and will even attempt to guess at what validation might be wanted based on the field type. For example, converting an EmailField will result in aStringField
with theEmail
validator on it. if the blank property is set on a model field, the resulting form field will have theOptional
validator set.Just like any other Form, forms created by model_form can be extended via inheritance:
UserFormBase = model_form(User) class UserForm(UserFormBase): new_pass = PasswordField('', [validators.optional(), validators.equal_to('confirm_pass')]) confirm_pass = PasswordField()
When combined with
form iteration
, model_form is a handy way to generate dynamic CRUD forms which update with added fields to the model. One must be careful though, as it’s possible the generated form fields won’t be as strict with validation as a hand-written form might be.
ORM-backed fields¶
While linking data to most fields is fairly easy, making drop-down select lists using django ORM data can be quite repetitive. To this end, we have added some helpful tools to use the django ORM along with wtforms.
-
class
wtforms.ext.django.fields.
QuerySetSelectField
(default field args, queryset=None, get_label=None, allow_blank=False, blank_text=u'')[source]¶ Given a QuerySet either at initialization or inside a view, will display a select drop-down field of choices. The data property actually will store/keep an ORM model instance, not the ID. Submitting a choice which is not in the queryset will result in a validation error.
Specify get_label to customize the label associated with each option. If a string, this is the name of an attribute on the model object to use as the label text. If a one-argument callable, this callable will be passed model instance and expected to return the label text. Otherwise, the model object’s __str__ or __unicode__ will be used.
If allow_blank is set to True, then a blank choice will be added to the top of the list. Selecting this choice will result in the data property being None. The label for the blank choice can be set by specifying the blank_text parameter.
class ArticleEdit(Form): title = StringField() column = QuerySetSelectField(get_label='title', allow_blank=True) category = QuerySetSelectField(queryset=Category.objects.all()) def edit_article(request, id): article = Article.objects.get(pk=id) form = ArticleEdit(obj=article) form.column.queryset = Column.objects.filter(author=request.user)
As shown in the above example, the queryset can be set dynamically in the view if needed instead of at form construction time, allowing the select field to consist of choices only relevant to the user.
SQLAlchemy¶
Warning
Deprecated since version 2.0: wtforms.ext.sqlalchemy
is deprecated and will be removed in
WTForms 3.0. Use WTForms-SQLAlchemy instead.
This extension provides SelectField integration with SQLAlchemy ORM models, similar to those in the Django extension.
ORM-backed fields¶
These fields are provided to make it easier to use data from ORM objects in your forms.
def enabled_categories():
return Category.query.filter_by(enabled=True)
class BlogPostEdit(Form):
title = StringField()
blog = QuerySelectField(get_label='title')
category = QuerySelectField(query_factory=enabled_categories, allow_blank=True)
def edit_blog_post(request, id):
post = Post.query.get(id)
form = BlogPostEdit(obj=post)
# Since we didn't provide a query_factory for the 'blog' field, we need
# to set a dynamic one in the view.
form.blog.query = Blog.query.filter(Blog.author == request.user).order_by(Blog.name)
-
class
wtforms.ext.sqlalchemy.fields.
QuerySelectField
(default field args, query_factory=None, get_pk=None, get_label=None, allow_blank=False, blank_text=u'')[source]¶ Will display a select drop-down field to choose between ORM results in a sqlalchemy Query. The data property actually will store/keep an ORM model instance, not the ID. Submitting a choice which is not in the query will result in a validation error.
This field only works for queries on models whose primary key column(s) have a consistent string representation. This means it mostly only works for those composed of string, unicode, and integer types. For the most part, the primary keys will be auto-detected from the model, alternately pass a one-argument callable to get_pk which can return a unique comparable key.
The query property on the field can be set from within a view to assign a query per-instance to the field. If the property is not set, the query_factory callable passed to the field constructor will be called to obtain a query.
Specify get_label to customize the label associated with each option. If a string, this is the name of an attribute on the model object to use as the label text. If a one-argument callable, this callable will be passed model instance and expected to return the label text. Otherwise, the model object’s __str__ or __unicode__ will be used.
If allow_blank is set to True, then a blank choice will be added to the top of the list. Selecting this choice will result in the data property being None. The label for this blank choice can be set by specifying the blank_text parameter.
-
class
wtforms.ext.sqlalchemy.fields.
QuerySelectMultipleField
(default field args, query_factory=None, get_pk=None, get_label=None)[source]¶ Very similar to QuerySelectField with the difference that this will display a multiple select. The data property will hold a list with ORM model instances and will be an empty list when no value is selected.
If any of the items in the data list or submitted form data cannot be found in the query, this will result in a validation error.
Model forms¶
It is possible to generate forms from SQLAlchemy models similarly to how it can be done for Django ORM models.
-
wtforms.ext.sqlalchemy.orm.
model_form
(model, db_session=None, base_class=<class 'wtforms.form.Form'>, only=None, exclude=None, field_args=None, converter=None, exclude_pk=True, exclude_fk=True, type_name=None)[source]¶ Create a wtforms Form for a given SQLAlchemy model class:
from wtforms.ext.sqlalchemy.orm import model_form from myapp.models import User UserForm = model_form(User)
- Parameters:
model – A SQLAlchemy mapped model class.
db_session – An optional SQLAlchemy Session.
base_class – Base form class to extend from. Must be a
wtforms.Form
subclass.only – An optional iterable with the property names that should be included in the form. Only these properties will have fields.
exclude – An optional iterable with the property names that should be excluded from the form. All other properties will have fields.
field_args – An optional dictionary of field names mapping to keyword arguments used to construct each field object.
converter – A converter to generate the fields based on the model properties. If not set,
ModelConverter
is used.exclude_pk – An optional boolean to force primary key exclusion.
exclude_fk – An optional boolean to force foreign keys exclusion.
type_name – An optional string to set returned type name.
CSRF¶
Warning
Deprecated since version 2.0: wtforms.ext.csrf
is deprecated and will be removed in
WTForms 3.0. CSRF protection is now built-in. See CSRF Protection.
The CSRF package includes tools that help you implement checking against cross-site request forgery (“csrf”). Due to the large number of variations on approaches people take to CSRF (and the fact that many make compromises) the base implementation allows you to plug in a number of CSRF validation approaches.
CSRF implementations are made by subclassing
SecureForm
. For utility, we have provided one
possible CSRF implementation in the package that can be used with many
frameworks for session-based hash secure keying,
SessionSecureForm
.
All CSRF implementations hinge around creating a special token, which is put in a hidden field on the form named ‘csrf_token’, which must be rendered in your template to be passed from the browser back to your view. There are many different methods of generating this token, but they are usually the result of a cryptographic hash function against some data which would be hard to forge.
-
class
wtforms.ext.csrf.form.
SecureForm
(formdata=None, obj=None, prefix='', csrf_context=None, **kwargs)[source]¶ Form that enables CSRF processing via subclassing hooks.
-
generate_csrf_token
(csrf_context)[source]¶ Implementations must override this to provide a method with which one can get a CSRF token for this form.
A CSRF token should be a string which can be generated deterministically so that on the form POST, the generated string is (usually) the same assuming the user is using the site normally.
- Parameters:
csrf_context – A transparent object which can be used as contextual info for generating the token.
-
Session-based CSRF implementation¶
A provided CSRF implementation which puts CSRF data in a session.
This can be used fairly comfortably with many request.session type objects, including the Werkzeug/Flask session store, Django sessions, and potentially other similar objects which use a dict-like API for storing session keys.
The basic concept is a randomly generated value is stored in the user’s session, and an hmac-sha1 of it (along with an optional expiration time, for extra security) is used as the value of the csrf_token. If this token validates with the hmac of the random value + expiration time, and the expiration time is not passed, the CSRF validation will pass.
Usage
First, create a SessionSecureForm subclass that you can use as your base class for any forms you want CSRF support for:
from wtforms.ext.csrf.session import SessionSecureForm
class MyBaseForm(SessionSecureForm):
SECRET_KEY = 'EPj00jpfj8Gx1SjnyLxwBBSQfnQ9DJYe0Ym'
TIME_LIMIT = timedelta(minutes=20)
Now incorporate it into any form/view by further subclassing:
class Registration(MyBaseForm):
name = StringField()
def view(request):
form = Registration(request.POST, csrf_context=request.session)
# rest of view here
Note that request.session is passed as the csrf_context=
parameter, this is
so that the CSRF token can be stored in your session for comparison on a later
request.
-
class
wtforms.ext.csrf.session.
SessionSecureForm
(formdata=None, obj=None, prefix='', csrf_context=None, **kwargs)[source]¶ A provided CSRF implementation which puts CSRF data in a session. Must be subclassed to be used.
Class Attributes
-
SECRET_KEY
¶ Must be set by subclasses to a random byte string that will be used to generate HMAC digests.
-
TIME_LIMIT
¶ If None, CSRF tokens never expire. If set to a
datetime.timedelta
, this is how long til a generated token expires. Defaults totimedelta(minutes=30)
-
I18n¶
Warning
Deprecated since version 2.0: wtforms.ext.i18n
is deprecated and will be removed in
WTForms 3.0. I18N support is now built-in. See Internationalization (i18n).
-
class
wtforms.ext.i18n.form.
Form
(*args, **kwargs)[source]¶ Base form for a simple localized WTForms form.
NOTE this class is now un-necessary as the i18n features have been moved into the core of WTForms, and will be removed in WTForms 3.0.
This will use the stdlib gettext library to retrieve an appropriate translations object for the language, by default using the locale information from the environment.
If the LANGUAGES class variable is overridden and set to a sequence of strings, this will be a list of languages by priority to use instead, e.g:
LANGUAGES = ['en_GB', 'en']
One can also provide the languages by passing LANGUAGES= to the constructor of the form.
Translations objects are cached to prevent having to get a new one for the same languages every instantiation.