Docs revision

sanic_security/authentication.py

@@ -197,7 +197,8 @@ async def fulfill_second_factor(request: Request) -> AuthenticationSession:
 
 async def authenticate(request: Request) -> tuple[bool, AuthenticationSession]:
     """
-    Validates client's authentication session and account.
+    Validates client's authentication session and account. New/Refreshed session automatically returned
+    if expired during authentication, requires encoding.
 
     Args:
         request (Request): Sanic request parameter.
@@ -226,7 +227,8 @@ async def authenticate(request: Request) -> tuple[bool, AuthenticationSession]:
 
 def requires_authentication(arg=None):
     """
-    Validates client's authentication session and account.
+    Validates client's authentication session and account. New/Refreshed session automatically returned if expired
+    during authentication, requires encoding.
 
     Example:
         This method is not called directly and instead used as a decorator:

sanic_security/authorization.py

@@ -146,6 +146,7 @@ async def on_require_perms(request):
         UnverifiedError
         DisabledError
         AuthorizationError
+        AnonymousError
     """
 
     def decorator(func):
@@ -185,6 +186,7 @@ async def on_require_roles(request):
         UnverifiedError
         DisabledError
         AuthorizationError
+        AnonymousError
     """
 
     def decorator(func):

sanic_security/exceptions.py

@@ -197,7 +197,7 @@ def __init__(self, message):
 
 class AnonymousError(AuthorizationError):
     """
-    Raised when attempting to authorize an anonymous session.
+    Raised when attempting to authorize an anonymous user.
     """
 
     def __init__(self):

sanic_security/models.py

@@ -526,7 +526,7 @@ class AuthenticationSession(Session):
     Attributes:
         requires_second_factor (bool): Determines if session requires a second factor.
         refresh_expiration_date (bool): Date and time the session can no longer be refreshed.
-        is_refresh (bool): Will only be true in the instance the session is created during refresh.
+        is_refresh (bool): Will only be true when instantiated during refresh of expired session.
     """
 
     requires_second_factor: bool = fields.BooleanField(default=False)
@@ -604,7 +604,7 @@ class Role(BaseModel):
     Attributes:
         name (str): Name of the role.
         description (str): Description of the role.
-        permissions (str): Permissions of the role. Must be separated via comma and in wildcard format (printer:query, printer:query,delete).
+        permissions (str): Permissions of the role. Must be separated via comma + space and in wildcard format (printer:query, dashboard:info,delete).
     """
 
     name: str = fields.CharField(unique=True, max_length=255)

sanic_security/test/tests.py

@@ -295,6 +295,9 @@ def test_two_factor_login(self):
         assert authenticate_response.status_code == 200, authenticate_response.text
 
     def test_anonymous_login(self):
+        """
+        Test login of anonymous user.
+        """
         anon_login_response = self.client.post(
             "http://127.0.0.1:8000/api/test/auth/login/anon"
         )
@@ -544,6 +547,9 @@ def test_get_associated_sessions(self):
         ), retrieve_associated_response.text
 
     def test_authentication_refresh(self):
+        """
+        Test automatic authentication refresh.
+        """
         self.client.post(
             "http://127.0.0.1:8000/api/test/account",
             data={