switch to Form.Meta from deprecated SecureForm, close #216

* deprecate `csrf_enabled` in `Form.__init__`
* remove `SecureForm` attributes and methods
* add `WTF_CSRFF_FIELD_NAME` config
* rename `CsrfError` to `CSRFError`
* `validate_csrf` raises `ValidationError` with specific error message,
  ref #239

docs/api.rst

@@ -34,7 +34,7 @@ CSRF Protection
 .. autoclass:: CsrfProtect
    :members:
 
-.. autoclass:: CsrfError
+.. autoclass:: CSRFError
    :members:
 
 .. autofunction:: generate_csrf

docs/changelog.rst

@@ -20,16 +20,33 @@ In development
 - The same CSRF token is generated for the lifetime of a request. It is exposed
   as ``request.csrf_token`` for use during testing. (`#227`_, `#264`_)
 - ``CsrfProtect.error_handler`` is deprecated. (`#264`_)
+
     - Handlers that return a response work in addition to those that raise an
       error. The behavior was not clear in previous docs.
     - (`#200`_, `#209`_, `#243`_, `#252`_)
 
+- Use ``Form.Meta`` instead of deprecated ``SecureForm`` for CSRF (and
+  everything else). (`#216`_, `#271`_)
+
+    - ``csrf_enabled`` parameter is still recognized but deprecated. All other
+      attributes and methods from ``SecureForm`` are removed. (`#271`_)
+
+- Provide ``WTF_CSRF_FIELD_NAME`` to configure the name of the CSRF token.
+  (`#271`_)
+- ``CsrfError`` is renamed to ``CSRFError``. (`#271`_)
+- ``validate_csrf`` raises ``wtforms.ValidationError`` with specifc messages
+  instead of returning ``True`` or ``False``. This breaks anything that was
+  calling the method directly. (`#239`_, `#271`_)
+
 .. _`#200`: https://github.com/lepture/flask-wtf/issues/200
 .. _`#209`: https://github.com/lepture/flask-wtf/pull/209
+.. _`#216`: https://github.com/lepture/flask-wtf/issues/216
 .. _`#227`: https://github.com/lepture/flask-wtf/issues/227
+.. _`#239`: https://github.com/lepture/flask-wtf/issues/239
 .. _`#243`: https://github.com/lepture/flask-wtf/pull/243
 .. _`#252`: https://github.com/lepture/flask-wtf/pull/252
 .. _`#264`: https://github.com/lepture/flask-wtf/pull/264
+.. _`#271`: https://github.com/lepture/flask-wtf/pull/271
 
 Version 0.13.1
 --------------

docs/config.rst

@@ -1,47 +1,37 @@
 Configuration
 =============
 
-Here is the full table of all configurations.
-
-Forms and CSRF
---------------
-
-The full list of configuration for Flask-WTF. Usually, you don't need
-to configure any of them. It just works.
-
-======================= ==============================================
-WTF_CSRF_ENABLED        Disable/enable CSRF protection for forms.
-                        Default is True.
-WTF_CSRF_CHECK_DEFAULT  Enable CSRF checks for all views by default.
-                        Default is True.
-WTF_I18N_ENABLED        Disable/enable I18N support. This should work
-                        together with Flask-Babel. Default is True.
-WTF_CSRF_HEADERS        CSRF token HTTP headers checked. Default is
-                        **['X-CSRFToken', 'X-CSRF-Token']**
-WTF_CSRF_SECRET_KEY     A random string for generating CSRF token.
-                        Default is the same as SECRET_KEY.
-WTF_CSRF_TIME_LIMIT     CSRF token expiring time. Default is **3600**
-                        seconds. If set to ``None``, the CSRF token
-                        is then bound to the life-time of the session.
-WTF_CSRF_SSL_STRICT     Strictly protection on SSL. This will check
-                        the referrer, validate if it is from the same
-                        origin. Default is True.
-WTF_CSRF_METHODS        CSRF protection on these request methods.
-                        Default is **['POST', 'PUT', 'PATCH']**
-======================= ==============================================
-
+========================== =====================================================
+``WTF_CSRF_ENABLED``       Set to ``False`` to disable all CSRF protection.
+``WTF_CSRF_CHECK_DEFAULT`` When using the CSRF protection extension, this
+                           controls whether every view is protected by default.
+                           Default is ``True``.
+``WTF_CSRF_SECRET_KEY``    Random data for generating secure tokens. If this is
+                           not set then ``SECRET_KEY`` is used.
+``WTF_CSRF_METHODS``       HTTP methods to protect from CSRF. Default is
+                           ``{'POST', 'PUT', 'PATCH', 'DELETE'}``.
+``WTF_CSRF_FIELD_NAME``    Name of the form field and session key that holds the
+                           CSRF token.
+``WTF_CSRF_HEADERS``       HTTP headers to search for CSRF token when it is not
+                           provided in the form. Default is
+                           ``['X-CSRFToken', 'X-CSRF-Token']``.
+``WTF_CSRF_TIME_LIMIT``    Max age in seconds for CSRF tokens. Default is
+                           ``3600``. If set to ``None``, the CSRF token is valid
+                           for the life of the session.
+``WTF_CSRF_SSL_STRICT``    Whether to enforce the same origin policy by checking
+                           that the referrer matches the host. Only applies to
+                           HTTPS requests. Default is ``True``.
+``WTF_I18N_ENABLED``       Set to ``False`` to disable Flask-Babel I18N support.
+========================== =====================================================
 
 Recaptcha
 ---------
 
-You have already learned these configuration at :ref:`recaptcha`.
-This table is only designed for a convience.
-
-======================= ==============================================
-RECAPTCHA_USE_SSL       Enable/disable recaptcha through ssl.
-                        Default is False.
-RECAPTCHA_PUBLIC_KEY    **required** A public key.
-RECAPTCHA_PRIVATE_KEY   **required** A private key.
-RECAPTCHA_OPTIONS       **optional** A dict of configuration options.
-                        https://www.google.com/recaptcha/admin/create
-======================= ==============================================
+========================= ==============================================
+``RECAPTCHA_USE_SSL``     Enable/disable recaptcha through SSL. Default is
+                          ``False``.
+``RECAPTCHA_PUBLIC_KEY``  **required** A public key.
+``RECAPTCHA_PRIVATE_KEY`` **required** A private key.
+                          https://www.google.com/recaptcha/admin/create
+``RECAPTCHA_OPTIONS``     **optional** A dict of configuration options.
+========================= ==============================================

docs/csrf.rst

@@ -77,7 +77,7 @@ For example, in jQuery you can configure all requests to send the token.
 Customize the error response
 ----------------------------
 
-When CSRF validation fails, it will raise a :class:`CsrfError`.
+When CSRF validation fails, it will raise a :class:`CSRFError`.
 By default this returns a response with the failure reason and a 400 code.
 You can customize the error response using Flask's
 :meth:`~flask.Flask.errorhandler`. ::