Add type hints to utils.py files

backend/apps/common/utils.py

@@ -5,6 +5,7 @@
 import json
 import re
 from datetime import UTC, datetime
+from typing import TYPE_CHECKING
 from urllib.parse import urlparse
 
 from django.conf import settings
@@ -13,6 +14,9 @@
 from django.utils.text import slugify as django_slugify
 from humanize import intword, naturaltime
 
+if TYPE_CHECKING:
+    from django.http import HttpRequest
+
 
 def convert_to_camel_case(text: str) -> str:
     """Convert a string to camelCase.
@@ -47,11 +51,11 @@ def convert_to_snake_case(text: str) -> str:
     return re.sub(r"(?<!^)(?=[A-Z])", "_", text).lower()
 
 
-def clean_url(url: str) -> str | None:
+def clean_url(url: str | None) -> str | None:
     """Clean a URL by removing whitespace and trailing punctuation.
 
     Args:
-        url (str): Raw URL string.
+        url (str, optional): Raw URL string.
 
     Returns:
         str | None: Cleaned URL string or None if empty.
@@ -79,14 +83,14 @@ def get_absolute_url(path: str) -> str:
 def get_nest_user_agent() -> str:
     """Return the user agent string for the Nest application.
 
-    Returns
+    Returns:
         str: The user agent string.
 
     """
     return settings.APP_NAME.replace(" ", "-").lower()
 
 
-def get_user_ip_address(request) -> str:
+def get_user_ip_address(request: HttpRequest) -> str:
     """Retrieve the user's IP address from the request.
 
     Args:
@@ -134,11 +138,11 @@ def join_values(fields: list, delimiter: str = " ") -> str:
     return delimiter.join(field for field in fields if field)
 
 
-def natural_date(value: int | str) -> str:
+def natural_date(value: int | str | datetime) -> str:
     """Convert a date or timestamp into a human-readable format.
 
     Args:
-        value (str or int or datetime): The date or timestamp to convert.
+        value (int or str or datetime): The date or timestamp to convert.
 
     Returns:
         str: The humanized date string.
@@ -154,7 +158,7 @@ def natural_date(value: int | str) -> str:
     return naturaltime(dt)
 
 
-def natural_number(value: int, unit=None) -> str:
+def natural_number(value: int, unit: str | None = None) -> str:
     """Convert a number into a human-readable format.
 
     Args:
@@ -173,8 +177,8 @@ def round_down(value: int, base: int) -> int:
     """Round down the stats to the nearest base.
 
     Args:
-        value: The value to round down.
-        base: The base to round down to.
+        value (int): The value to round down.
+        base (int): The base to round down to.
 
     Returns:
         int: The rounded down value.
@@ -211,11 +215,11 @@ def truncate(text: str, limit: int, truncate: str = "...") -> str:
     return Truncator(text).chars(limit, truncate=truncate)
 
 
-def validate_url(url: str) -> bool:
+def validate_url(url: str | None) -> bool:
     """Validate that a URL has proper scheme and netloc.
 
     Args:
-        url (str): URL string to validate.
+        url (str, optional): URL string to validate.
 
     Returns:
         bool: True if URL is valid, False otherwise.

backend/apps/github/utils.py

@@ -33,12 +33,12 @@ def check_owasp_site_repository(key: str) -> bool:
     )
 
 
-def check_funding_policy_compliance(platform: str, target: str) -> bool:
+def check_funding_policy_compliance(platform: str, target: str | None) -> bool:
     """Check OWASP funding policy compliance.
 
     Args:
         platform (str): The funding platform (e.g., 'github', 'custom').
-        target (str): The funding target.
+        target (str, optional): The funding target.
 
     Returns:
         bool: True if the funding policy is compliant, False otherwise.
@@ -60,7 +60,7 @@ def check_funding_policy_compliance(platform: str, target: str) -> bool:
 def get_repository_file_content(
     url: str,
     *,
-    timeout: float | None = 30,
+    timeout: int | None = 30,
 ) -> str:
     """Get the content of a file from a repository.
 
@@ -69,7 +69,7 @@ def get_repository_file_content(
         timeout (int, optional): The request timeout in seconds.
 
     Returns:
-        str: The content of the file, or None if the request fails.
+        str: The content of the file, or empty string if the request fails.
 
     """
     try:
@@ -86,7 +86,8 @@ def get_repository_path(url: str) -> str | None:
         url (str): The repository URL.
 
     Returns:
-        str: The repository path in the format 'owner/repository_name', or None if parsing fails.
+        str or None: The repository path in the format 'owner/repository_name',
+        or None if parsing fails.
 
     """
     match = GITHUB_REPOSITORY_RE.search(url.split("#")[0])
@@ -101,7 +102,7 @@ def normalize_url(url: str, *, check_path: bool = False) -> str | None:
         check_path (bool, optional): Whether to check if the URL has a path.
 
     Returns:
-        str: The normalized URL, or None if the URL is invalid.
+        str or None: The normalized URL, or None if the URL is invalid.
 
     """
     parsed_url = urlparse(url)

backend/apps/slack/utils.py

@@ -22,7 +22,7 @@
 logger: logging.Logger = logging.getLogger(__name__)
 
 
-def escape(content) -> str:
+def escape(content: str) -> str:
     """Escape HTML content.
 
     Args:
@@ -78,7 +78,7 @@ def get_gsoc_projects(year: int) -> list:
 
 
 @lru_cache
-def get_news_data(limit: int = 10, timeout: float | None = 30) -> list[dict[str, str]]:
+def get_news_data(limit: int = 10, timeout: int | None = 30) -> list[dict[str, str]]:
     """Get news data.
 
     Args:
@@ -114,7 +114,7 @@ def get_news_data(limit: int = 10, timeout: float | None = 30) -> list[dict[str,
 
 
 @lru_cache
-def get_staff_data(timeout: float | None = 30) -> list | None:
+def get_staff_data(timeout: int | None = 30) -> list | None:
     """Get staff data.
 
     Args: