Developer Interface

Forms and Fields

class flask_wtf.FlaskForm(*args, **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
property csrf

bool(x) -> bool

Returns True when the argument x is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

property csrf_field_name

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

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.

Changelog

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(*args, **kwargs)
class flask_wtf.Recaptcha(message=None)

Validates a ReCaptcha.

class flask_wtf.RecaptchaWidget
class flask_wtf.file.FileField(*args, **kwargs)

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

Parameters

  • description (Optional[str]) –

  • response (Optional[Response]) –

Return type

None

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 comparison. 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 comparison. Default is WTF_CSRF_FIELD_NAME or 'csrf_token'.

Raises

ValidationError – Contains the reason that validation failed.

Changelog

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