ready for 5.1.2 (pallets-eco#773)

Add documentation on how to properly subclass a form when using multiple inheritance.

Author: jwag956

CHANGES.rst

@@ -6,7 +6,7 @@ Here you can see the full list of changes between each Flask-Security release.
 Version 5.1.2
 -------------
 
-Released TBD
+Released March 12, 2023
 
 Fixes
 +++++
@@ -15,6 +15,7 @@ Fixes
 - (:pr:`769`) Fix documentation for send_mail. (gg)
 - (:pr:`768`) Fix for latest mongoengine and mongomock.
 - (:pr:`766`) Fix inappropriate use of &thinsp& in French translations. (maxdup)
+- (:pr:`773`) Improve documentation around subclassing forms.
 
 Version 5.1.1
 -------------

docs/conf.py

@@ -57,7 +57,7 @@
 # built documents.
 #
 # The short X.Y version.
-version = "5.1.1"
+version = "5.1.2"
 # The full version, including alpha/beta/rc tags.
 release = version
 

docs/customizing.rst

@@ -122,6 +122,33 @@ be passed if the model looks like::
     various views to no longer function. Many fields have complex (and not
     publicly exposed) validators that have side effects.
 
+.. warning::
+    It is important to ALWAYS subclass the base Flask-Security form and not
+    attempt to just redefine the class. This is due to the validation method
+    of many of the forms performs critical additional validation AND will change
+    or add values to the form as a side-effect. See below for how to do this.
+
+If you need to override an existing field in a form (to override/add validators),
+and you want to define a re-usable validator - use multiple inheritance - be extremely
+careful about the order of the inherited classes::
+
+    from wtforms import PasswordField, ValidationError
+    from wtforms.validators import DataRequired
+
+    def password_validator(form, field):
+        if field.data.startswith("PASS"):
+            raise ValidationError("Really - don't start a password with PASS")
+
+    class NewPasswordFormMixinEx:
+        password = PasswordField("password",
+                                 validators=[DataRequired(message="PASSWORD_NOT_PROVIDED"),
+                                             password_validator])
+
+    class MyRegisterForm(NewPasswordFormMixinEx, ConfirmRegisterForm):
+        pass
+
+    app.config["SECURITY_CONFIRM_REGISTER_FORM"] = MyRegisterForm
+
 The following is a list of all the available form overrides:
 
 * ``login_form``: Login form
@@ -536,8 +563,9 @@ The decision on whether to return JSON is based on:
 Redirects
 ---------
 Flask-Security uses redirects frequently (when using forms), and most of the redirect
-destinations are configurable. When Flask-Security initiates a redirect it always (mostly) flashes a message
-that provides some context. In addition, Flask-Security - both in its views and default templates attempt to propagate
+destinations are configurable. When Flask-Security initiates a redirect it (almost) always flashes a message
+that provides some context for the user.
+In addition, Flask-Security - both in its views and default templates, attempts to propagate
 any `next` query param and in fact, an existing `?next=/xx` will override most of the configuration redirect URLs.
 
 As a complex example consider an unauthenticated user accessing a `@auth_required` endpoint, and the user has

flask_security/__init__.py

@@ -134,4 +134,4 @@
 )
 from .webauthn_util import WebauthnUtil
 
-__version__ = "5.1.1"
+__version__ = "5.1.2"

tests/test_registerable.py

@@ -842,3 +842,43 @@ def on_user_registered(app, **kwargs):
     assert nr["existing_email"]
     assert nr["user"]
     assert nr["form_data"]["email"] == "dude@lp.com"
+
+
+def test_subclass(app, sqlalchemy_datastore):
+    # Test/show how to use multiple inheritance to override individual form fields.
+    from wtforms import PasswordField, ValidationError
+    from wtforms.validators import DataRequired
+    from flask_security.forms import get_form_field_label
+
+    def password_validator(form, field):
+        if field.data.startswith("PASS"):
+            raise ValidationError("Really - don't start a password with PASS")
+
+    class NewPasswordFormMixinEx:
+        password = PasswordField(
+            get_form_field_label("password"),
+            validators=[
+                DataRequired(message="PASSWORD_NOT_PROVIDED"),
+                password_validator,
+            ],
+        )
+
+    class MyRegisterForm(NewPasswordFormMixinEx, ConfirmRegisterForm):
+        pass
+
+    app.config["SECURITY_CONFIRM_REGISTER_FORM"] = MyRegisterForm
+    security = Security(datastore=sqlalchemy_datastore)
+    security.init_app(app)
+
+    client = app.test_client()
+
+    data = dict(
+        email="dude@lp.com",
+        password="PASSmattmatt",
+        password_confirm="PASSmattmatt",
+    )
+    response = client.post(
+        "/register", json=data, headers={"Content-Type": "application/json"}
+    )
+    assert response.status_code == 400
+    assert "Really - don't start" in response.json["response"]["errors"][0]