From 99a6c8c1c9f2b035cee1b8bb450da26dded10f0d Mon Sep 17 00:00:00 2001
From: wowkalucky <wowkalucky@gmail.com>
Date: Tue, 16 Apr 2024 17:12:32 +0300
Subject: [PATCH] refactor: document signal handlers

---
 credentials/apps/badges/issuers.py          | 28 ++++++++++++++++++---
 credentials/apps/badges/models.py           |  1 +
 credentials/apps/badges/signals/handlers.py |  4 ++-
 credentials/apps/badges/signals/signals.py  |  7 +++---
 4 files changed, 33 insertions(+), 7 deletions(-)

diff --git a/credentials/apps/badges/issuers.py b/credentials/apps/badges/issuers.py
index 12af5bebb..6cfb126a0 100644
--- a/credentials/apps/badges/issuers.py
+++ b/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):
diff --git a/credentials/apps/badges/models.py b/credentials/apps/badges/models.py
index 059999ba9..c3d6d5ea6 100644
--- a/credentials/apps/badges/models.py
+++ b/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
 
diff --git a/credentials/apps/badges/signals/handlers.py b/credentials/apps/badges/signals/handlers.py
index 7d5a151be..0e408aec7 100644
--- a/credentials/apps/badges/signals/handlers.py
+++ b/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)
diff --git a/credentials/apps/badges/signals/signals.py b/credentials/apps/badges/signals/signals.py
index 846699fc6..0d8cc7a22 100644
--- a/credentials/apps/badges/signals/signals.py
+++ b/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