Add documentation for registration process

docs/api.rst

@@ -8,6 +8,7 @@ API
 
    coreexceptions
    models
+   registration
    authentication
    accountmanagement
    tokens

docs/registration.rst

@@ -0,0 +1,32 @@
+.. _registration:
+
+Registration
+============
+
+These interfaces and implementations control the user registration flow in
+FlaskBB.
+
+Registration Interfaces
+-----------------------
+
+.. module:: flaskbb.core.auth.registration
+
+.. autoclass:: UserRegistrationInfo
+
+.. autoclass:: UserValidator
+    :members:
+
+.. autoclass:: UserRegistrationService
+    :members:
+
+
+Registration Provided Implementations
+-------------------------------------
+
+.. module:: flaskbb.auth.services.registration
+
+.. autoclass:: UsernameRequirements
+.. autoclass:: UsernameValidator
+.. autoclass:: UsernameUniquenessValidator
+.. autoclass:: EmailUniquenessValidator
+.. autoclass:: RegistrationService

flaskbb/auth/services/activation.py

@@ -27,14 +27,6 @@ class AccountActivator(_AccountActivator):
         self.users = users
 
     def initiate_account_activation(self, email):
-        """
-        Looks a user up via email and sends an activation token.
-
-        Will raise a
-        :class:`ValidationError<flaskbb.core.exceptions.ValidationError>`
-        if either the email doesn't exist in the application or the account
-        tied to the email is already activated.
-        """
         user = self.users.query.filter_by(email=email).first()
 
         if user is None:
@@ -52,18 +44,6 @@ class AccountActivator(_AccountActivator):
         )
 
     def activate_account(self, token):
-        """
-        Activates an account based on the supplied token.
-
-        Will raise
-        :class:`TokenError<flaskbb.core.tokens.TokenError>` if the supplied
-        token is not an account activation token and a
-        :class:`ValidationError<flaskbb.core.exceptions.ValidationError>`
-        if the account is already activated.
-
-        Otherwise marks the account as activated.
-        """
-
         token = self.token_serializer.loads(token)
         if token.operation != TokenActions.ACTIVATE_ACCOUNT:
             raise TokenError.invalid()

flaskbb/auth/services/password.py

@@ -28,12 +28,6 @@ class ResetPasswordService(_ResetPasswordService):
         self.token_verifiers = token_verifiers
 
     def initiate_password_reset(self, email):
-        """
-        Looks up a user by email and raises a
-        :class:`ValidationError<flaskbb.core.exceptions.ValidationError>`
-        if that user does not exist, otherwise generates a reset password
-        token and emails it to the user.
-        """
 
         user = self.users.query.filter_by(email=email).first()
 
@@ -49,17 +43,6 @@ class ResetPasswordService(_ResetPasswordService):
         )
 
     def reset_password(self, token, email, new_password):
-        """
-        Resets a user's password if the email entered by the user matches
-        the email on file for the user in FlaskBB.
-
-        If the provided token is not a reset password token, then it raises a
-        :class:`TokenError<flaskbb.core.tokens.TokenError>` and if the
-        information provided by the user does not meet criteria defined
-        by the passed token verifiers, then a
-        :class:`StopValidation<flaskbb.core.exceptions.StopValidation>` is
-        raised.
-        """
 
         token = self.token_serializer.loads(token)
         if token.operation != TokenActions.RESET_PASSWORD:

flaskbb/auth/services/registration.py

@@ -24,12 +24,20 @@ __all__ = (
 
 @attr.s(hash=False, repr=True, frozen=True, cmp=False)
 class UsernameRequirements(object):
+    """
+    Configuration for username requirements, minimum and maximum length
+    and disallowed names.
+    """
     min = attr.ib()
     max = attr.ib()
     blacklist = attr.ib()
 
 
 class UsernameValidator(UserValidator):
+    """
+    Validates that the username for the registering user meets the minimum
+    requirements (appropriate length, not a forbidden name).
+    """
 
     def __init__(self, requirements):
         self._requirements = requirements
@@ -58,6 +66,9 @@ class UsernameValidator(UserValidator):
 
 
 class UsernameUniquenessValidator(UserValidator):
+    """
+    Validates that the provided username is unique in the application.
+    """
 
     def __init__(self, users):
         self.users = users
@@ -77,6 +88,9 @@ class UsernameUniquenessValidator(UserValidator):
 
 
 class EmailUniquenessValidator(UserValidator):
+    """
+    Validates that the provided email is unique in the application.
+    """
 
     def __init__(self, users):
         self.users = users
@@ -93,6 +107,17 @@ class EmailUniquenessValidator(UserValidator):
 
 
 class RegistrationService(UserRegistrationService):
+    """
+    Default registration service for FlaskBB, runs the registration information
+    against the provided validators and if it passes, creates the user.
+
+    If any of the provided
+    :class:`UserValidators<flaskbb.core.auth.registration.UserValidator>`
+    raise a :class:`ValidationError<flaskbb.core.exceptions.ValidationError>`
+    then the register method will raise a
+    :class:`StopValidation<flaskbb.core.exceptions.StopValidation>` with all
+    reasons why the registration was prevented.
+    """
 
     def __init__(self, validators, user_repo):
         self.validators = validators

flaskbb/core/auth/registration.py

@@ -19,6 +19,10 @@ from ..._compat import ABC
 
 @attr.s(hash=True, cmp=False, repr=True, frozen=True)
 class UserRegistrationInfo(object):
+    """
+    User registration object, contains all relevant information for validating
+    and creating a new user.
+    """
     username = attr.ib()
     password = attr.ib(repr=False)
     email = attr.ib()
@@ -27,20 +31,38 @@ class UserRegistrationInfo(object):
 
 
 class UserValidator(ABC):
+    """
+    Used to validate user registrations and stop the registration process
+    by raising a
+    :class:`ValidationError<flaskbb.core.exceptions.ValidationError>`.
+    """
+
     @abstractmethod
     def validate(self, user_info):
         """
-        Used to check if a user should be allowed to register.
-        Should raise ValidationError if the user should not be
-        allowed to register.
+        This method is abstract.
+
+        :param user_info: The provided registration information.
+        :type user_info: :class:`UserRegistrationInfo<flaskbb.core.auth.registration.UserRegistrationInfo>`
         """
-        return True
 
     def __call__(self, user_info):
         return self.validate(user_info)
 
 
 class UserRegistrationService(ABC):
+    """
+    Used to manage the registration process. A default implementation is
+    provided however, this interface is provided in case alternative
+    flows are needed.
+    """
+
     @abstractmethod
     def register(self, user_info):
+        """
+        This method is abstract.
+
+        :param user_info: The provided user registration information.
+        :type user_info: :class:`UserRegistrationInfo<flaskbb.core.auth.registration.UserRegistrationInfo>`
+        """
         pass