Switch to Form.Meta from SecureForm, improve CSRF errors

docs/api.rst

@@ -31,10 +31,12 @@ CSRF Protection
 
 .. module:: flask_wtf.csrf
 
-.. autoclass:: CsrfProtect
+.. autoclass:: CSRFProtect
    :members:
 
-.. autoclass:: CsrfError
+.. autoclass:: CsrfProtect(...)
+
+.. autoclass:: CSRFError
    :members:
 
 .. autofunction:: generate_csrf

docs/changelog.rst

@@ -20,16 +20,38 @@ 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`_)
+- ``validate_csrf`` raises ``wtforms.ValidationError`` with specific messages
+  instead of returning ``True`` or ``False``. This breaks anything that was
+  calling the method directly. (`#239`_, `#271`_)
+
+    - CSRF errors are logged as well as raised. (`#239`_)
+
+- ``CsrfProtect`` is renamed to ``CSRFProtect``. A deprecation warning is issued
+  when using the old name. ``CsrfError`` is renamed to ``CSRFError`` without
+  deprecation. (`#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,44 @@
 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.
+========================= ==============================================
+
+Logging
+-------
+
+CSRF errors are logged at the ``INFO`` level to the ``flask_wtf.csrf`` logger.
+You still need to configure logging in your application in order to see these
+messages.

docs/csrf.rst

@@ -5,7 +5,7 @@
 CSRF Protection
 ===============
 
-Any view using :class:`flask_wtf.FlaskForm` to process the request is already
+Any view using :class:`~flask_wtf.FlaskForm` to process the request is already
 getting CSRF protection. If you have views that don't use ``FlaskForm`` or make
 AJAX requests, use the provided CSRF extension to protect those requests as
 well.
@@ -14,15 +14,15 @@ Setup
 -----
 
 To enable CSRF protection globally for a Flask app, register the
-:class:`CsrfProtect` extension. ::
+:class:`CSRFProtect` extension. ::
 
-    from flask_wtf.csrf import CsrfProtect
+    from flask_wtf.csrf import CSRFProtect
 
-    csrf = CsrfProtect(app)
+    csrf = CSRFProtect(app)
 
 Like other Flask extensions, you can apply it lazily::
 
-    csrf = CsrfProtect()
+    csrf = CSRFProtect()
 
     def create_app():
         app = Flask(__name__)
@@ -77,12 +77,12 @@ 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`. ::
 
-    from flask_wtf.csrf import CsrfError
+    from flask_wtf.csrf import CSRFError
 
     @app.errorhandler(CsrfError)
     def handle_csrf_error(e):
@@ -106,7 +106,7 @@ You can exclude all the views of a blueprint. ::
 
 You can disable CSRF protection in all views by default, by setting
 ``WTF_CSRF_CHECK_DEFAULT`` to ``False``, and selectively call
-``csrf.protect()`` only when you need. This also enables you to do some
+:meth:`~flask_wtf.csrf.CSRFProtect.protect` only when you need. This also enables you to do some
 pre-processing on the requests before checking for the CSRF token. ::
 
     @app.before_request

flask_wtf/__init__.py

@@ -12,7 +12,7 @@
 # flake8: noqa
 from __future__ import absolute_import
 
-from .csrf import CsrfProtect
+from .csrf import CSRFProtect, CsrfProtect
 from .form import FlaskForm, Form
 from .recaptcha import *