refactor: document signal handlers

credentials/apps/badges/issuers.py

@@ -69,7 +69,16 @@ def issue_credential(
 
         return user_credential
 
-    def award(self, credential_id, username):
+    def award(self, *, username, credential_id):
+        """
+        Awards a badge.
+
+        Creates user credential record for the given badge template, for a given user.
+        Notifies about the awarded badge (public signal).
+
+        Returns: UserCredential
+        """
+
         credential = self.get_credential(credential_id)
         user_credential = self.issue_credential(credential, username)
 
@@ -131,10 +140,23 @@ def revoke_credly_badge(self, credential_id, user_credential):
         user_credential.state = response.get("data").get("state")
         user_credential.save()
 
-    def award(self, credential_id, username):
-        user_credential = super().award(credential_id, username)
+    def award(self, *, username, credential_id):
+        """
+        Awards a Credly badge.
+
+        - Creates user credential record for the given badge template, for a given user;
+        - Notifies about the awarded badge (public signal);
+        - Issues external Credly badge (Credly API);
+
+        Returns: (CredlyBadge) user credential
+        """
+
+        user_credential = super().award(username=username, credential_id=credential_id)
+
+        # do not issue new badges if the badge was issued already
         if not user_credential.is_issued:
             self.issue_credly_badge(credential_id, user_credential)
+
         return user_credential
 
     def revoke(self, credential_id, username):

credentials/apps/badges/models.py

@@ -521,6 +521,7 @@ def as_badge_data(self) -> BadgeData:
         """
         Represents itself as a BadgeData instance.
         """
+
         user = get_user_by_username(self.username)
         badge_template = self.credential
 

credentials/apps/badges/signals/handlers.py

@@ -64,7 +64,9 @@ def handle_badge_completion(sender, username, badge_template_id, **kwargs):  # p
     - badge template ID
     """
 
-    CredlyBadgeTemplateIssuer().award(badge_template_id, username)
+    logger.debug("BADGES: progress is complete for %s on the %s", username, badge_template_id)
+
+    CredlyBadgeTemplateIssuer().award(username=username, credential_id=badge_template_id)
 
 
 @receiver(BADGE_PROGRESS_INCOMPLETE)

credentials/apps/badges/signals/signals.py

@@ -21,7 +21,7 @@
 
 def notify_requirement_fulfilled(*, sender, username, badge_template_id, **kwargs):
     """
-    Notifies about user's progression on the badge template.
+    Notifies about user's partial progression on the badge template.
     """
 
     BADGE_REQUIREMENT_FULFILLED.send(
@@ -39,8 +39,9 @@ def notify_requirement_regressed(*, sender, username, badge_template_id):
 
 def notify_progress_complete(sender, username, badge_template_id):
     """
-    FIXME:
+    Notifies about user's completion on the badge template.
     """
+
     BADGE_PROGRESS_COMPLETE.send(
         sender=sender,
         username=username,
@@ -61,7 +62,7 @@ def notify_progress_incomplete(sender, username, badge_template_id):
 
 def notify_badge_awarded(user_credential):  # pylint: disable=unused-argument
     """
-    Emit public event about badge template completion.
+    Emits a public signal about the badge template completion for user.
 
     - username
     - badge template ID