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)¶

Creates and returns a dynamic wtforms.Form class for a given db.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=u'')¶

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.

class wtforms.ext.appengine.fields.StringListPropertyField(default field arguments)¶

A field for db.StringListProperty. The list items are rendered in a textarea.

class wtforms.ext.appengine.fields.GeoPtPropertyField(default field arguments)¶

Templatetags¶

Django templates does not allow arbitrarily calling functions with parameters, making it impossible to use the html attribute rendering feature of WTForms. To alleviate this, we provide a templatetag.

Adding wtforms.ext.django to your INSTALLED_APPS will make the wtforms template library available to your application. With this you can pass extra attributes to form fields similar to the usage in jinja:

{% load wtforms %}

{% form_field form.username class="big_text" onclick="do_something()" %}

Note By default, using the {{ form.field }} syntax in django models will be auto-escaped. To avoid this happening, use Django’s {% autoescape off %} block tag or use WTForms’ form_field template tag.

Model forms¶

wtforms.ext.django.orm.model_form(model, base_class=Form, only=None, exclude=None, field_args=None, converter=None)¶

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 a TextField with the email() validator on it. if the blank property is set on a model field, the resulting form field will have the optional() validator set.

Just like any other Form, forms created by ModelForm 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'')¶

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    = TextField()
    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.

class wtforms.ext.django.fields.ModelSelectField(default field args, model=None, get_label='', allow_blank=False, blank_text=u'')¶

Like a QuerySetSelectField, except takes a model class instead of a queryset and lists everything in it.

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    = TextField()
    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 = ArticleEdit(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'')¶

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, allow_blank=False, blank_text=u'')¶

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.

Creating your own CSRF implementation¶

Here we will sketch out a simple theoretical CSRF implementation which generates a hash token based on the user’s IP.

Note This is a simplistic example meant to illustrate creating a CSRF implementation. This isn’t recommended to be used in production because the token is deterministic and non-changing per-IP, which means this isn’t the most secure implementation of CSRF.

First, let’s create our SecureForm base class:

from wtforms.ext.csrf import SecureForm
from hashlib import md5

SECRET_KEY = '1234567890'

class IPSecureForm(SecureForm):
    """
    Generate a CSRF token based on the user's IP. I am probably not very
    secure, so don't use me.
    """

    def generate_csrf_token(self, csrf_context):
        # csrf_context is passed transparently from the form constructor,
        # in this case it's the IP address of the user
        token = md5(SECRET_KEY + csrf_context).hexdigest()
        return token

    def validate_csrf_token(self, field):
        if field.data != field.current_token:
            raise ValueError('Invalid CSRF')

Now that we have this taken care of, let’s write a simple form and view which would implement this:

class RegistrationForm(IPSecureForm):
    name = TextField('Your Name')
    email = TextField('Email', [validators.email()])

def register(request):
    form = RegistrationForm(request.POST, csrf_context=request.ip)

    if request.method == 'POST' and form.validate():
        pass # We're all good, create a user or whatever it is you do
    elif form.csrf_token.errors:
        pass # If we're here we suspect the user of cross-site request forgery
    else:
        pass # Any other errors

    return render('register.html', form=form)

And finally, a simple template:

<form action="register" method="POST">
    {{ form.csrf_token }}
    <p>{{ form.name.label }}: {{ form.name }}</p>
    <p>{{ form.email.label }}: {{ form.email }}</p>
    <input type="submit" value="Register">
</form>

Please note that implementing CSRF detection is not fool-proof, and even with the best CSRF protection implementation, it’s possible for requests to be forged by expert attackers. However, a good CSRF protection would make it infeasible for someone from an external site to hijack a form submission from another user and perform actions as them without additional a priori knowledge.

In addition, it’s important to understand that very often, the more strict the CSRF protection, the higher the chance of false positives occurring (ie, legitimate users getting blocked by your CSRF protection) and choosing a CSRF implementation is actually a matter of compromise. We will attempt to provide a handful of usable reference algorithms built in to this library in the future, to allow that choice to be easy.

Some tips on criteria people often examine when evaluating CSRF implementations:

• Reproducability If a token is based on attributes about the user, it gains the advantage that one does not need secondary storage in which to store the value between requests. However, if the same attributes can be reproduced by an attacker, then the attacker can potentially forge this information.
• Reusability. It might be desired to make a completely different token every use, and disallow users from re-using past tokens. This is an extremely powerful protection, but can have consequences on if the user uses the back button (or in some cases runs forms simultaneously in multiple browser tabs) and submits an old token, or otherwise. A possible compromise is to allow reusability in a time window (more on that later).
• Time Ranges Many CSRF approaches use time-based expiry to make sure that a token cannot be (re)used beyond a certain point. Care must be taken in choosing the time criteria for this to not lock out legitimate users. For example, if a user might walk away while filling out a long-ish form, or to go look for their credit card, the time for expiry should take that into consideration to provide a balance between security and limiting user inconvenience.
• Requirements Some CSRF-prevention methods require the use of browser cookies, and some even require client-side scripting support. The webmaster implementing the CSRF needs to consider that such requirements (though effective) may lock certain legitimate users out, and make this determination whether it is a good idea to use. For example, for a site already using cookies for login, adding another for CSRF isn’t as big of a deal, but for other sites it may not be feasible.

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 = TextField()

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)¶

A provided CSRF implementation which puts CSRF data in a session. Must be subclassed to be used.

Class Attributes .. attribute:: 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 to timedelta(minutes=30)