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 at 0x1067d4f58>, 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=u'Invalid word. Please try again.')

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, _form=None, _name=None, _prefix=u'', _translations=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.

file

Deprecated :synonym for data

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, _form=None, _name=None, _prefix=u'', _translations=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, _form=None, _name=None, _prefix=u'', _translations=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, _form=None, _name=None, _prefix=u'', _translations=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, _form=None, _name=None, _prefix=u'', _translations=None)

Represents an <input type="tel">.

class flask_wtf.html5.NumberInput(input_type=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=2, rounding=None, **kwargs)

Represents an <input type="number">.

class flask_wtf.html5.RangeInput(input_type=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=2, 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.