Developer Interface — Flask-WTF Documentation (1.2.x)

# 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

      Returns True when the argument 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 ‘utf-8’. errors defaults to ‘strict’.

    property csrf_secret

      The type of the None singleton.

    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(extra_validators=None)

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

class flask_wtf.Form(...)

  Declarative Form base class. Extends BaseForm’s core behaviour allowing fields to be defined on Form subclasses as class attributes.

  In addition, form and instance input data are taken at construction time and passed to process().

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`.

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

  Validates that the uploaded file(s) 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 uploaded files(s) 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.

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

    - response (SansIOResponse | 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`.