3 files changed, 66 insertions, 4 deletions

diff --git a/mu4web/user/__init__.py b/mu4web/user/__init__.py
index bb14f67..c0dbda9 100644
--- a/mu4web/user/__init__.py
+++ b/mu4web/user/__init__.py
@@ -1,19 +1,66 @@
+"""
+User authentication and sessions.
+
+This is modeled to work well together with flash_login.
+"""
+
+
 class User:
+    """
+    Default class for user session and authentication.
+
+    This implements flask-login's User Class protocol.
+
+    This abse implementation can construct any user, but no user can
+    by authenticated through it.
+
+    https://flask-login.readthedocs.io/en/latest/
+    """
+
     def __init__(self, username: str):
         self._username = username
         self._authenticated = False
 
+    # ---- User class protocoll ------------------------
+
     def is_authenticated(self) -> bool:
+        """
+        Return whetever a user is authenticated.
+
+        An authenticated user is someone who has provided valid
+        credentials (or similar)
+        """
         return self._authenticated
 
     def is_active(self) -> bool:
+        """
+        Return whetever a user is active.
+
+        An active user is someone who has an active account, suspended
+        or deactivated accounts aren't active.
+        """
         return True
 
     def is_anonymous(self) -> bool:
+        """Return true for anonymous users."""
         return False
 
     def get_id(self) -> str:
+        """Get the unique identifier for this user."""
         return self._username
 
+    # ---- Other stuff ---------------------------------
+
     def validate(self, _: str) -> bool:
+        """
+        Attempt to validate the users credentials.
+
+        The username comes from the constructed object.
+
+        :params password:
+            The attempted authentication token/password.
+
+        :returns:
+            True if the given token is correct, false otherwise.
+        """
         raise NotImplementedError()
diff --git a/mu4web/user/local.py b/mu4web/user/local.py
index 37e88cb..c7936d6 100644
--- a/mu4web/user/local.py
+++ b/mu4web/user/local.py
@@ -1,12 +1,21 @@
+"""
+User authentication through local password store.
+
+Currently (hard codedly) loads the file password.json from the current
+path. Take care.
+"""
+
 from .. import password
 from ..password import Passwords
 from typing import cast
 import os
 from . import User
 
-passwords: Passwords = password.Passwords(cast(os.PathLike, 'passwords.json'))
+passwords: Passwords = password.Passwords(cast(os.PathLike[str], 'passwords.json'))
 
 
 class LocalUser(User):
-    def validate(self, password: str) -> bool:
+    """Authenticate user through local password file."""
+
+    def validate(self, password: str) -> bool:  # noqa: 201
         return passwords.validate(self._username, password)
diff --git a/mu4web/user/pam.py b/mu4web/user/pam.py
index 55e868e..c641ff8 100644
--- a/mu4web/user/pam.py
+++ b/mu4web/user/pam.py
@@ -1,7 +1,13 @@
+"""User authentication through PAM."""
+
 from . import User
 import pam
 
 
 class PamUser(User):
-    def validate(self, password: str) -> bool:
-        return pam.authenticate(self._username, password)
+    """Authenticate user through pam."""
+
+    def validate(self, password: str) -> bool:  # noqa: 201
+        ret = pam.authenticate(self._username, password)
+        assert type(ret) == bool
+        return ret