Developer Interface

This part of the documentation covers all interfaces of Flask-WTF.

Forms and Fields

class flask_wtf.Form(formdata=<class flask_wtf.form._Auto>, obj=None, prefix='', csrf_context=None, secret_key=None, csrf_enabled=None, *args, **kwargs)

Flask-specific subclass of WTForms SecureForm class.

If formdata is not specified, this will use flask.request.form. Explicitly pass formdata = None to prevent this.

Parameters:
  • csrf_context – a session or dict-like object to use when making CSRF tokens. Default: flask.session.
  • secret_key –

    a secret key for building CSRF tokens. If this isn’t specified, the form will take the first of these that is defined:

    • SECRET_KEY attribute on this class
    • WTF_CSRF_SECRET_KEY config of flask app
    • SECRET_KEY config of flask app
    • session secret key
  • csrf_enabled – whether to use CSRF protection. If False, all csrf behavior is suppressed. Default: WTF_CSRF_ENABLED config value
hidden_tag(*fields)

Wraps hidden fields in a hidden DIV tag, in order to keep XHTML compliance.

New in version 0.3.

Parameters:fields – list of hidden field names. If not provided will render all hidden fields, including the CSRF field.
is_submitted()

Checks if form has been submitted. The default case is if the HTTP method is PUT or POST.

validate_csrf_data(data)

Check if the csrf data is valid.

Parameters:data – the csrf string to be validated.
validate_on_submit()

Checks if form has been submitted and if so runs validate. This is a shortcut, equivalent to form.is_submitted() and form.validate()

class flask_wtf.RecaptchaField(label='', validators=None, **kwargs)
class flask_wtf.Recaptcha(message=None)

Validates a ReCaptcha.

class flask_wtf.RecaptchaWidget
class flask_wtf.file.FileField(label=None, validators=None, filters=(), description=u'', id=None, default=None, widget=None, render_kw=None, _form=None, _name=None, _prefix=u'', _translations=None, _meta=None)

Werkzeug-aware subclass of wtforms.FileField

Provides a has_file() method to check if its data is a FileStorage instance with an actual file.

has_file()

Return True iff self.data is a FileStorage with file data

class flask_wtf.file.FileAllowed(upload_set, message=None)

Validates that the uploaded file is allowed by the given Flask-Uploads UploadSet.

Parameters:
  • upload_set – A list/tuple of extention names or an instance of flask.ext.uploads.UploadSet
  • message – error message

You can also use the synonym file_allowed.

class flask_wtf.file.FileRequired(message=None)

Validates that field has a file.

Parameters:message – error message

You can also use the synonym file_required.

class flask_wtf.html5.SearchInput(input_type=None)

Renders an input with type “search”.

class flask_wtf.html5.SearchField(label=None, validators=None, filters=(), description=u'', id=None, default=None, widget=None, render_kw=None, _form=None, _name=None, _prefix=u'', _translations=None, _meta=None)

Represents an <input type="search">.

class flask_wtf.html5.URLInput(input_type=None)

Renders an input with type “url”.

class flask_wtf.html5.URLField(label=None, validators=None, filters=(), description=u'', id=None, default=None, widget=None, render_kw=None, _form=None, _name=None, _prefix=u'', _translations=None, _meta=None)

Represents an <input type="url">.

class flask_wtf.html5.EmailInput(input_type=None)

Renders an input with type “email”.

class flask_wtf.html5.EmailField(label=None, validators=None, filters=(), description=u'', id=None, default=None, widget=None, render_kw=None, _form=None, _name=None, _prefix=u'', _translations=None, _meta=None)

Represents an <input type="email">.

class flask_wtf.html5.TelInput(input_type=None)

Renders an input with type “tel”.

class flask_wtf.html5.TelField(label=None, validators=None, filters=(), description=u'', id=None, default=None, widget=None, render_kw=None, _form=None, _name=None, _prefix=u'', _translations=None, _meta=None)

Represents an <input type="tel">.

class flask_wtf.html5.NumberInput(step=None, min=None, max=None)

Renders an input with type “number”.

class flask_wtf.html5.IntegerField(label=None, validators=None, **kwargs)

Represents an <input type="number">.

class flask_wtf.html5.DecimalField(label=None, validators=None, places=<unset value>, rounding=None, **kwargs)

Represents an <input type="number">.

class flask_wtf.html5.RangeInput(step=None)

Renders an input with type “range”.

class flask_wtf.html5.IntegerRangeField(label=None, validators=None, **kwargs)

Represents an <input type="range">.

class flask_wtf.html5.DecimalRangeField(label=None, validators=None, places=<unset value>, rounding=None, **kwargs)

Represents an <input type="range">.

CSRF Protection

class flask_wtf.csrf.CsrfProtect(app=None)

Enable csrf protect for Flask.

Register it with:

app = Flask(__name__)
CsrfProtect(app)

And in the templates, add the token input:

<input type="hidden" name="csrf_token" value="{{ csrf_token() }}"/>

If you need to send the token via AJAX, and there is no form:

<meta name="csrf_token" content="{{ csrf_token() }}" />

You can grab the csrf token with JavaScript, and send the token together.

error_handler(view)

A decorator that set the error response handler.

It accepts one parameter reason:

@csrf.error_handler
def csrf_error(reason):
    return render_template('error.html', reason=reason)

By default, it will return a 400 response.

exempt(view)

A decorator that can exclude a view from csrf protection.

Remember to put the decorator above the route:

csrf = CsrfProtect(app)

@csrf.exempt
@app.route('/some-view', methods=['POST'])
def some_view():
    return
flask_wtf.csrf.generate_csrf(secret_key=None, time_limit=None)

Generate csrf token code.

Parameters:
  • secret_key – A secret key for mixing in the token, default is Flask.secret_key.
  • time_limit – Token valid in the time limit, default is 3600s.
flask_wtf.csrf.validate_csrf(data, secret_key=None, time_limit=None)

Check if the given data is a valid csrf token.

Parameters:
  • data – The csrf token value to be checked.
  • secret_key – A secret key for mixing in the token, default is Flask.secret_key.
  • time_limit – Check if the csrf token is expired. default is True.