Add documentation for new registration hooks

docs/development/api/registration.rst

@@ -19,6 +19,12 @@ Registration Interfaces
 .. autoclass:: UserRegistrationService
     :members:
 
+.. autoclass:: RegistrationFailureHandler
+    :members:
+
+.. autoclass:: RegistrationPostProcessor
+    :members:
+
 
 Registration Provided Implementations
 -------------------------------------
@@ -29,4 +35,7 @@ Registration Provided Implementations
 .. autoclass:: UsernameValidator
 .. autoclass:: UsernameUniquenessValidator
 .. autoclass:: EmailUniquenessValidator
+.. autoclass:: SendActivationPostProcessor
+.. autoclass:: AutologinPostProcessor
+.. autoclass:: AutoActivateUserPostProcessor
 .. autoclass:: RegistrationService

docs/development/hooks/event.rst

@@ -5,11 +5,26 @@
 FlaskBB Event Hooks
 ===================
 
+Post and Topic Events
+---------------------
+
 .. autofunction:: flaskbb_event_post_save_before
 .. autofunction:: flaskbb_event_post_save_after
 .. autofunction:: flaskbb_event_topic_save_before
 .. autofunction:: flaskbb_event_topic_save_after
+
+Registration Events
+-------------------
+
 .. autofunction:: flaskbb_event_user_registered
+.. autofunction:: flaskbb_gather_registration_validators
+.. autofunction:: flaskbb_registration_post_processor
+.. autofunction:: flaskbb_registration_failure_handler
+
+
+Authentication Events
+---------------------
+
 .. autofunction:: flaskbb_authenticate
 .. autofunction:: flaskbb_post_authenticate
 .. autofunction:: flaskbb_authentication_failed

flaskbb/auth/services/registration.py

@@ -131,6 +131,12 @@ class EmailUniquenessValidator(UserValidator):
 
 
 class SendActivationPostProcessor(RegistrationPostProcessor):
+    """
+    Sends an activation request after registration
+
+    :param account_activator:
+    :type account_activator: :class:`~flaskbb.core.auth.activation.AccountActivator`
+    """  # noqa
 
     def __init__(self, account_activator):
         self.account_activator = account_activator
@@ -147,6 +153,9 @@ class SendActivationPostProcessor(RegistrationPostProcessor):
 
 
 class AutologinPostProcessor(RegistrationPostProcessor):
+    """
+    Automatically logs a user in after registration
+    """
 
     def post_process(self, user):
         login_user(user)
@@ -157,6 +166,9 @@ class AutoActivateUserPostProcessor(RegistrationPostProcessor):
     """
     Automatically marks the user as activated if activation isn't required
     for the forum.
+
+    :param db: Configured Flask-SQLAlchemy extension object
+    :param config: Current flaskbb configuration object
     """
 
     def __init__(self, db, config):

flaskbb/core/auth/registration.py

@@ -56,6 +56,13 @@ class RegistrationFailureHandler(ABC):
 
     @abstractmethod
     def handle_failure(self, user_info, failures):
+        """
+        This method is abstract.
+
+        :param user_info: The provided registration information.
+        :param failures: Tuples of (attribute, message) from the failure
+        :type user_info: :class:`~flaskbb.core.auth.registration.UserRegistrationInfo`
+        """  # noqa
         pass
 
     def __call__(self, user_info, failures):
@@ -71,6 +78,12 @@ class RegistrationPostProcessor(ABC):
 
     @abstractmethod
     def post_process(self, user):
+        """
+        This method is abstract.
+
+        :param user: The registered, persisted user.
+        :type user: :class:`~flaskbb.user.models.User`
+        """
         pass
 
     def __call__(self, user):

flaskbb/plugins/spec.py

@@ -202,6 +202,11 @@ def flaskbb_event_topic_save_after(topic, is_new):
 def flaskbb_event_user_registered(username):
     """Hook for handling events after a user is registered
 
+    .. warning::
+
+        This hook is deprecated in favor of
+        :func:`~flaskbb.plugins.spec.flaskbb_registration_post_processor`
+
     :param username: The username of the newly registered user.
     """
 
@@ -223,13 +228,16 @@ def flaskbb_gather_registration_validators():
                 raise ValidationError(('username', 'Cannot name user fred'))
 
         @impl
-        def flaskbb_gather_validate_user_registration():
-            return cannot_be_named_fred
+        def flaskbb_gather_registration_validators():
+            return [cannot_be_named_fred]
 
     .. note::
 
         This is implemented as a hook that returns callables since the
-        callables are designed to raise exceptions.
+        callables are designed to raise exceptions that are aggregated to
+        form the failure message for the registration response.
+
+    See Also: :class:`~flaskbb.core.auth.registration.UserValidator`
     """
 
 
@@ -239,13 +247,38 @@ def flaskbb_registration_failure_handler(user_info, failures):
     Hook for dealing with user registration failures, receives the info
     that user attempted to register with as well as the errors that failed
     the registration.
-    """
+
+    Example::
+
+        from .utils import fuzz_username
+
+        def has_already_registered(failures):
+            return any(
+                attr = "username" and "already registered" in msg
+                for (attr, msg) in failures
+            )
+
+
+        def suggest_alternate_usernames(user_info, failures):
+            if has_already_registered(failures):
+                suggestions = fuzz_username(user_info.username)
+                failures.append(("username", "Try: {}".format(suggestions)))
+
+
+        @impl
+        def flaskbb_registration_failure_handler(user_info, failures):
+            suggest_alternate_usernames(user_info, failures)
+
+    See Also: :class:`~flaskbb.core.auth.registration.RegistrationFailureHandler`
+    """  # noqa
 
 
 @spec
 def flaskbb_registration_post_processor(user):
     """
-    Hook for handling actions after a user has successfully registered.
+    Hook for handling actions after a user has successfully registered. This
+    spec receives the user object after it has been successfully persisted
+    to the database.
 
     Example::
 
@@ -255,7 +288,9 @@ def flaskbb_registration_post_processor(user):
         @impl
         def flaskbb_registration_post_processor(user):
             greet_user(user)
-    """
+
+    See Also: :class:`~flaskbb.core.auth.registration.RegistrationPostProcessor`
+    """  # noqa
 
 
 @spec(firstresult=True)