Developer Interface

Forms and Fields

class flask_wtf.FlaskForm(formdata=<object object>, **kwargs)

Flask-specific subclass of WTForms Form.

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

class Meta
get_translations(form)

Override in subclasses to provide alternate translations factory. See the i18n documentation for more.

Parameters:form -- The form.
Returns:An object that provides gettext() and ngettext() methods.
wrap_formdata(form, formdata)

wrap_formdata allows doing custom wrappers of WTForms formdata.

The default implementation detects webob-style multidicts and wraps them, otherwise passes formdata back un-changed.

Parameters:
  • form -- The form.
  • formdata -- Form data.
Returns:

A form-input wrapper compatible with WTForms.
hidden_tag(*fields)

Render the form's hidden fields in one call.

A field is considered hidden if it uses the HiddenInput widget.

If fields are given, only render the given fields that are hidden. If a string is passed, render the field with that name if it exists.

Changed in version 0.13: No longer wraps inputs in hidden div. This is valid HTML 5.

Changed in version 0.13: Skip passed fields that aren't hidden. Skip passed names that don't exist.

is_submitted()

Consider the form submitted if there is an active request and the method is POST, PUT, PATCH, or DELETE.

validate_on_submit()

Call validate() only if the form is submitted. This is a shortcut for form.is_submitted() and form.validate().

class flask_wtf.Form(...)

Deprecated since version 0.13: Renamed to FlaskForm.

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='', id=None, default=None, widget=None, render_kw=None, _form=None, _name=None, _prefix='', _translations=None, _meta=None)

Werkzeug-aware subclass of wtforms.fields.FileField.

has_file()

Return True if self.data is a FileStorage object.

Deprecated since version 0.14.1: data is no longer set if the input is not a non-empty FileStorage. Check form.data is not None instead.

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

Validates that the uploaded file is allowed by a given list of extensions or a Flask-Uploads UploadSet.

Parameters:
  • upload_set -- A list of extensions or an UploadSet
  • message -- error message

You can also use the synonym file_allowed.

class flask_wtf.file.FileRequired(message=None)

Validates that the data is a Werkzeug FileStorage object.

Parameters:message -- error message

You can also use the synonym file_required.

CSRF Protection

class flask_wtf.csrf.CSRFProtect(app=None)

Enable CSRF protection globally for a Flask app.

app = Flask(__name__)
csrf = CSRFProtect(app)

Checks the csrf_token field sent with forms, or the X-CSRFToken header sent with JavaScript requests. Render the token in templates using {{ csrf_token() }}.

See the CSRF Protection documentation.

error_handler(view)

Register a function that will generate the response for CSRF errors.

Deprecated since version 0.14: Use the standard Flask error system with @app.errorhandler(CSRFError) instead. This will be removed in version 1.0.

The function will be passed one argument, reason. By default it will raise a CSRFError.

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

Due to historical reasons, the function may either return a response or raise an exception with flask.abort().

exempt(view)

Mark a view or blueprint to be excluded from CSRF protection.

@app.route('/some-view', methods=['POST'])
@csrf.exempt
def some_view():
    ...

bp = Blueprint(...)
csrf.exempt(bp)
class flask_wtf.csrf.CsrfProtect(...)

Deprecated since version 0.14: Renamed to CSRFProtect.

class flask_wtf.csrf.CSRFError(description=None, response=None)

Raise if the client sends invalid CSRF data with the request.

Generates a 400 Bad Request response with the failure reason by default. Customize the response by registering a handler with flask.Flask.errorhandler().

flask_wtf.csrf.generate_csrf(secret_key=None, token_key=None)

Generate a CSRF token. The token is cached for a request, so multiple calls to this function will generate the same token.

During testing, it might be useful to access the signed token in g.csrf_token and the raw token in session['csrf_token'].

Parameters:
  • secret_key -- Used to securely sign the token. Default is WTF_CSRF_SECRET_KEY or SECRET_KEY.
  • token_key -- Key where token is stored in session for comparision. Default is WTF_CSRF_FIELD_NAME or 'csrf_token'.
flask_wtf.csrf.validate_csrf(data, secret_key=None, time_limit=None, token_key=None)

Check if the given data is a valid CSRF token. This compares the given signed token to the one stored in the session.

Parameters:
  • data -- The signed CSRF token to be checked.
  • secret_key -- Used to securely sign the token. Default is WTF_CSRF_SECRET_KEY or SECRET_KEY.
  • time_limit -- Number of seconds that the token is valid. Default is WTF_CSRF_TIME_LIMIT or 3600 seconds (60 minutes).
  • token_key -- Key where token is stored in session for comparision. Default is WTF_CSRF_FIELD_NAME or 'csrf_token'.
Raises:

ValidationError -- Contains the reason that validation failed.

Changed in version 0.14: Raises ValidationError with a specific error message rather than returning True or False.