oidc: add documentation and address pylint concerns

bookwyrm/models/user.py

@@ -10,6 +10,7 @@
 from django.db import models, transaction
 from django.utils import timezone
 from django.utils.translation import gettext_lazy as _
+from mozilla_django_oidc.auth import OIDCAuthenticationBackend
 from model_utils import FieldTracker
 import pytz
 
@@ -535,32 +536,24 @@ def preview_image(instance, *args, **kwargs):
         generate_user_preview_image_task.delay(instance.id)
 
 
-#
-# Create new accounts based on OIDC provided parameters
-# TODO: what happens if the email changes in keycloak?
-#
-from mozilla_django_oidc.auth import OIDCAuthenticationBackend
-
-
 class OIDCUser(OIDCAuthenticationBackend):
+    """a user defined by an entry in the SSO database"""
     def create_user(self, claims):
+        """called by mozilla_django_oidc.auth on first login"""
         if not OIDC_ENABLED:
-            # log an error?
             return None
 
-        # user = super(OIDCUser, self).create_user(claims)
         print("creating user", claims)
-        # user = super(OIDCUser, self).create_user()
-
         localname = claims.get("preferred_username")
         username = f"{localname}@{DOMAIN}"
         email = claims.get("email", "")
+        display_name = claims.get("name", localname),
 
         user = User.objects.create_user(
             username,
             email,
             "passwords-not-supported",
-            name=claims.get("name", localname),
+            name=display_name,
             localname=localname,
             local=True,
             deactivation_reason=None,
@@ -570,22 +563,23 @@ def create_user(self, claims):
         return self.update_user(user, claims)
 
     def update_user(self, user, claims):
+        """called by mozilla_django_oidc.auth for existing user"""
+        # log an error? should not reach here
         if not OIDC_ENABLED:
-            # log an error?
             return None
-        return self.update_user(user, claims)
 
-    def update_user(self, user, claims):
         # replace the user's display name
         user.name = claims.get("name", user.name)
 
         # this is a hack to synchronize the OIDC role claims
-        # with the ones in the bookwyrm database. it should be more general
+        # with the ones in the bookwyrm database.
         roles = (
             claims.get("resource_access", {})
             .get(OIDC_RP_CLIENT_ID, {})
             .get("roles", [])
         )
+
+        # TODO: this should be more general.
         for role in ["admin", "moderator"]:
             try:
                 group = Group.objects.get(name=role)