Update architecture docs for exception handling

Version 5.0.5 migrated from exceptions to request flagging
which alters the internal behaviour slightly.

axes/backends.py

@@ -47,8 +47,7 @@ class AxesBackend(ModelBackend):
         # Raise an error that stops the authentication flows at django.contrib.auth.authenticate.
         # This error stops bubbling up at the authenticate call which catches backend PermissionDenied errors.
         # After this error is caught by authenticate it emits a signal indicating user login failed,
-        # which is processed by axes.signals.log_user_login_failed which logs the attempt and raises
-        # a second exception which bubbles up the middleware stack and produces a HTTP 403 Forbidden reply
-        # in the axes.middleware.AxesMiddleware.process_exception middleware exception handler.
+        # which is processed by axes.signals.log_user_login_failed which logs and flags the failed request.
+        # The axes.middleware.AxesMiddleware further processes the flagged request into a readable response.
 
         raise AxesBackendPermissionDenied('AxesBackend detected that the given user is locked out')

axes/middleware.py

@@ -8,16 +8,12 @@ class AxesMiddleware:
     Middleware that calculates necessary HTTP request attributes for attempt monitoring
     and maps lockout signals into readable HTTP 403 Forbidden responses.
 
-    By default Django server returns ``PermissionDenied`` exceptions as HTTP 403 errors
-    with the ``django.views.defaults.permission_denied`` view that renders
-    the ``403.html`` template from the root template directory if found.
-
-    This middleware recognizes the specialized attempt monitoring and lockout exceptions
+    This middleware recognizes a logout monitoring flag in the request and
     and uses the ``axes.helpers.get_lockout_response`` handler for returning
-    customizable and context aware lockout message to the end user.
+    customizable and context aware lockout message to the end user if necessary.
 
-    To customize the error handling behaviour further, you can subclass this middleware
-    and change the ``process_exception`` handler to your own liking.
+    To customize the lockout handling behaviour further, you can subclass this middleware
+    and change the ``__call__`` method to your own liking.
 
     Please see the following configuration flags before customizing this handler:
 

docs/7_architecture.rst

@@ -34,10 +34,6 @@ it can raise a ``django.core.exceptions.PermissionDenied`` exception.
 If a login fails, Django then fires a
 ``from django.contrib.auth.signals.user_login_failed`` signal.
 
-If this signal raises an exception, it is propagated through the
-Django middleware stack where it can be caught, or alternatively
-where it can bubble up to the default Django exception handlers.
-
 A normal login flow for Django runs as follows:
 
 .. code-block:: text
@@ -78,10 +74,6 @@ are not blocked, and allows the requests to go through if the check passes.
 If any of the checks fails, an exception is raised which interrupts
 the login process and triggers the Django login failed signal handlers.
 
-Another exception is raised by a Axes signal handler, which is
-then caught by ``AxesMiddleware`` and converted into a readable
-error because the user is currently locked out of the system.
-
 Axes implements the lockout flow as follows:
 
 .. code-block:: text
@@ -113,12 +105,11 @@ Axes implements the lockout flow as follows:
 
     7. Axes logs the failure and increments the failure
        counters which keep track of failure statistics.
+       Axes then updates the request object with a logout
+       status flag that can be processed by
+       view or middleware code as needed.
 
-    8. AxesSignalPermissionDenied exception is raised
-       if appropriate and it bubbles up the middleware stack.
-       The exception aborts the Django authentication flow.
-
-    9. AxesMiddleware processes the exception
+    8. AxesMiddleware processes the lockout request and response
        and returns a readable lockout message to the user.
 
 This plugin assumes that the login views either call