Add documentation for tokens

docs/api.rst

@@ -6,6 +6,8 @@ API
 .. toctree::
    :maxdepth: 2
 
+   coreexceptions
    models
    authentication
    accountmanagement
+   tokens

docs/authentication.rst

@@ -2,8 +2,8 @@
 
 .. module:: flaskbb.core.auth.authentication
 
-Authentication Interfaces
-=========================
+Authentication
+==============
 
 
 FlaskBB exposes several interfaces and hooks to customize authentication and

docs/coreexceptions.rst

@@ -0,0 +1,13 @@
+.. _coreexceptions:
+
+.. module:: flaskbb.core.exceptions
+
+Core Exceptions
+===============
+
+These are exceptions that aren't specific to any one part of FlaskBB
+and are used ubiquitously.
+
+.. autoexception:: BaseFlaskBBError
+.. autoexception:: ValidationError
+.. autoexception:: StopValidation

docs/tokens.rst

@@ -0,0 +1,20 @@
+.. _tokens:
+
+Tokens
+======
+
+.. module:: flaskbb.core.tokens
+
+.. autoclass:: TokenActions
+    :members:
+
+.. autoclass:: Token
+
+.. autoclass:: TokenSerializer
+    :members:
+
+.. autoclass:: TokenVerifier
+    :members:
+
+.. autoexception:: TokenError
+    :members:

flaskbb/core/exceptions.py

@@ -11,14 +11,23 @@
     :license: BSD, see LICENSE for more details
 """
 
+
 class BaseFlaskBBError(Exception):
-    "Root exception for FlaskBB"
+    """
+    Root exception for FlaskBB.
+    """
 
 
 class ValidationError(BaseFlaskBBError):
     """
     Used to signal validation errors for things such as
     token verification, user registration, etc.
+
+    :param str attribute: The attribute the validation error applies to,
+        if the validation error applies to multiple attributes or to
+        the entire object, this should be set to None
+    :param str reason: Why the attribute, collection of attributes or object
+        is invalid.
     """
 
     def __init__(self, attribute, reason):
@@ -33,11 +42,11 @@ class StopValidation(BaseFlaskBBError):
     validation should end immediately and no further
     processing should be done.
 
-    The reasons passed should be an iterable of
-    tuples consisting of `(attribute, reason)`
-
     Can also be used to communicate all errors
     raised during a validation run.
+
+    :param reasons: A sequence of `(attribute, reason)` pairs explaining
+        why the object is invalid.
     """
 
     def __init__(self, reasons):

flaskbb/core/tokens.py

@@ -23,6 +23,8 @@ class TokenError(BaseFlaskBBError):
     Raised when there is an issue with deserializing
     a token. Has helper classmethods to ensure
     consistent verbiage.
+
+    :param str reason: An explanation of why the token is invalid
     """
 
     def __init__(self, reason):
@@ -31,10 +33,19 @@ class TokenError(BaseFlaskBBError):
 
     @classmethod
     def invalid(cls):
+        """
+        Used to raise an exception about a token that is invalid
+        due to being signed incorrectly, has been tampered with,
+        is unparsable or contains an inappropriate action.
+        """
         return cls(_('Token is invalid'))
 
     @classmethod
     def expired(cls):
+        """
+        Used to raise an exception about a token that has expired and is
+        no longer usable.
+        """
         return cls(_('Token is expired'))
 
     # in theory this would never be raised
@@ -48,33 +59,60 @@ class TokenError(BaseFlaskBBError):
 # holder for token actions
 # not an enum so plugins can add to it
 class TokenActions:
+    """
+    Collection of token actions.
+
+    .. note::
+        This is just a class rather than an enum because enums cannot be
+        extended at runtime which would limit the number of token actions
+        to the ones implemented by FlaskBB itself and block extension of
+        tokens by plugins.
+    """
     RESET_PASSWORD = 'reset_password'
     ACTIVATE_ACCOUNT = 'activate_account'
 
 
 @attr.s(frozen=True, cmp=True, hash=True)
 class Token(object):
+    """
+    :param int user_id:
+    :param str operation: An operation taken from
+        :class:`TokenActions<flaskbb.core.tokens.TokenActions>`
+    """
     user_id = attr.ib()
     operation = attr.ib()
 
 
 class TokenSerializer(ABC):
     """
-    Interface for token serializers.
 
-    dumps must accept a Token instance and produce
-    a JWT
-
-    loads must accept a string representation of
-    a JWT and produce a token instance
     """
 
     @abstractmethod
     def dumps(self, token):
+        """
+        This method is abstract.
+
+        Used to transform a token into a string representation of it.
+
+        :param token:
+        :type token: :class:`Token<flaskbb.core.tokens.Token>`
+        :returns str:
+        """
         pass
 
     @abstractmethod
     def loads(self, raw_token):
+        """
+        This method is abstract
+
+        Used to transform a string representation of a token into an
+        actual :class:`Token<flaskbb.core.tokens.Token>` instance
+
+        :param str raw_token:
+        :returns token: The parsed token
+        :rtype: :class:`Token<flaskbb.core.tokens.Token`>
+        """
         pass
 
 
@@ -84,12 +122,20 @@ class TokenVerifier(ABC):
     deserialization, such as an email matching the
     user id in the provided token.
 
-    Should raise a flaskbb.core.exceptions.ValidationError
+    Should raise a
+    :class:`ValidationError<flaskbb.core.exceptions.ValidationError>`
     if verification fails.
     """
 
     @abstractmethod
     def verify_token(self, token, **kwargs):
+        """
+        This method is abstract.
+
+        :param token: The parsed token to verify
+        :param kwargs: Arbitrary context for validation of the token
+        :type token: :class:`Token<flaskbb.core.tokens.Token>`
+        """
         pass
 
     def __call__(self, token, **kwargs):