feat(refactor): PEP8, type annotations, docstrings and PyJWT security fix

backend/app/services/tempo_service.py

@@ -18,15 +18,31 @@ blue_work_started_at) to when they submit, so it reflects actual working time
 rather than queue time.
 """
 
+# Import logging
 import logging
-from typing import Optional
 
+# Import Any, Optional from typing
+from typing import Any, Optional
+
+# Import Session from sqlalchemy.orm
 from sqlalchemy.orm import Session
 
+# Import settings from app.config
 from app.config import settings
+
+# Import InvalidOperationError from app.domain.exceptions
 from app.domain.exceptions import InvalidOperationError
+
+# Import JiraLink, JiraLinkEntityType from app.models.jira_link
 from app.models.jira_link import JiraLink, JiraLinkEntityType
 
+# Import Test from app.models.test
+from app.models.test import Test
+
+# Import User from app.models.user
+from app.models.user import User
+
+# Assign logger = logging.getLogger(__name__)
 logger = logging.getLogger(__name__)
 
 # Only red team execution time goes to Tempo.
@@ -85,23 +101,31 @@ def get_user_tempo_client(user, db=None):
             "Add it in Settings → Profile → Tempo Integration."
         )
     try:
+        # Import client_v4 as tempo_client from tempoapiclient
         from tempoapiclient import client_v4 as tempo_client
         base_url = _get_tempo_base_url(db)
         logger.debug("Using Tempo base URL: %s", base_url)
         return tempo_client.Tempo(auth_token=token, base_url=base_url)
     except ImportError:
+        # Raise InvalidOperationError
         raise InvalidOperationError(
+            # Literal argument value
             "tempo-api-python-client is not installed. "
             "Run: pip install tempo-api-python-client"
         )
 
 
+# Define function log_worklog
 def log_worklog(
     user,
     jira_issue_id: int,
+    # Entry: author_account_id
     author_account_id: str,
+    # Entry: date
     date: str,
+    # Entry: time_spent_seconds
     time_spent_seconds: int,
+    # Entry: description
     description: str,
     db=None,
 ) -> dict:
@@ -128,10 +152,15 @@ def log_worklog(
         raise RuntimeError(f"Tempo API error: {exc}") from exc
 
 
+# Define function auto_log_test_worklog
 def auto_log_test_worklog(
+    # Entry: db
     db: Session,
-    test,
-    user,
+    # Entry: test
+    test: Test,
+    # Entry: user
+    user: User,
+    # Entry: activity_type
     activity_type: str,
     duration_seconds: int,
 ) -> Optional[dict]:
@@ -156,6 +185,7 @@ def auto_log_test_worklog(
 
     # Global kill-switch
     if not settings.TEMPO_ENABLED:
+        # Return None
         return None
 
     if duration_seconds <= 0:
@@ -183,15 +213,20 @@ def auto_log_test_worklog(
     # Need a Jira link with a numeric issue ID
     link = (
         db.query(JiraLink)
+        # Chain .filter() call
         .filter(
             JiraLink.entity_id == test.id,
             JiraLink.entity_type == JiraLinkEntityType.test,
         )
+        # Chain .first() call
         .first()
     )
 
+    # Check: not link or not link.jira_issue_id
     if not link or not link.jira_issue_id:
+        # Log debug: "No Jira link for test %s, skipping Tempo worklog"
         logger.debug("No Jira link for test %s, skipping Tempo worklog", test.id)
+        # Return None
         return None
 
     jira_account_id = (getattr(user, "jira_account_id", "") or "").strip()
@@ -202,6 +237,7 @@ def auto_log_test_worklog(
         )
         return None
 
+    # Attempt the following; catch errors below
     try:
         # Use the phase start timestamp as the worklog date so it matches when
         # work actually happened (not the submission timestamp).
@@ -231,6 +267,7 @@ def auto_log_test_worklog(
             test.id, getattr(user, "username", user), duration_seconds, work_date,
         )
         return result
+    # Handle Exception
     except Exception as e:
         logger.warning(
             "Tempo worklog failed for test %s (user %s): %s",