docs(utils): add Google-style docstrings to utils module (#1077)

docs(utils): add Google-style docstrings to utils module

Author: LuckyAnsari22

utils/config.py

@@ -8,21 +8,51 @@
 load_dotenv(override=True)
 
 
-def get_broker_api_key():
+def get_broker_api_key() -> str | None:
+    """
+    Retrieve the configured broker API key.
+
+    Returns:
+        str | None: The broker API key from environment variables, or None if not set.
+    """
     return os.getenv("BROKER_API_KEY")
 
 
-def get_broker_api_secret():
+def get_broker_api_secret() -> str | None:
+    """
+    Retrieve the configured broker API secret.
+
+    Returns:
+        str | None: The broker API secret from environment variables, or None if not set.
+    """
     return os.getenv("BROKER_API_SECRET")
 
 
-def get_login_rate_limit_min():
+def get_login_rate_limit_min() -> str:
+    """
+    Retrieve the rate limit for logins per minute.
+
+    Returns:
+        str: The rate limit string (e.g., '5 per minute').
+    """
     return os.getenv("LOGIN_RATE_LIMIT_MIN", "5 per minute")
 
 
-def get_login_rate_limit_hour():
+def get_login_rate_limit_hour() -> str:
+    """
+    Retrieve the rate limit for logins per hour.
+
+    Returns:
+        str: The rate limit string (e.g., '25 per hour').
+    """
     return os.getenv("LOGIN_RATE_LIMIT_HOUR", "25 per hour")
 
 
-def get_host_server():
+def get_host_server() -> str:
+    """
+    Retrieve the host server URL.
+
+    Returns:
+        str: The host server URL string.
+    """
     return os.getenv("HOST_SERVER", "http://127.0.0.1:5000")

utils/env_check.py

@@ -4,15 +4,18 @@
 from dotenv import load_dotenv
 
 
-def configure_llvmlite_paths():
+def configure_llvmlite_paths() -> None:
     """
     Configure LLVMLITE/NUMBA paths to avoid 'failed to map segment' errors.
 
-    On hardened Linux servers, /tmp is often mounted with 'noexec' flag,
+    On hardened Linux servers, /tmp is often mounted with the 'noexec' flag,
     which prevents llvmlite from loading its shared library.
 
     This sets alternative directories for llvmlite/numba cache and temp files.
     Must be called BEFORE any imports that might trigger llvmlite loading.
+
+    Returns:
+        None
     """
     # Only configure on Linux (Windows/macOS don't have this issue)
     if sys.platform != 'linux':
@@ -44,10 +47,14 @@ def configure_llvmlite_paths():
     check_tmp_noexec()
 
 
-def check_tmp_noexec():
+def check_tmp_noexec() -> bool:
     """
-    Check if /tmp is mounted with noexec flag and print a warning.
-    This helps users understand why llvmlite might fail.
+    Check if /tmp is mounted with the noexec flag.
+
+    This helps users understand why llvmlite might fail to load.
+
+    Returns:
+        bool: True if /tmp is likely mounted with noexec on Linux, False otherwise.
     """
     if sys.platform != 'linux':
         return
@@ -76,10 +83,12 @@ def check_tmp_noexec():
         pass  # Can't read /proc/mounts, skip the check
 
 
-def check_env_version_compatibility():
+def check_env_version_compatibility() -> bool:
     """
-    Check if .env file version matches .sample.env version
-    Returns True if compatible, False if update needed
+    Check if the .env file version matches the .sample.env version.
+
+    Returns:
+        bool: True if compatible, False if an update is needed.
     """
     base_dir = os.path.dirname(__file__) + "/.."
     env_path = os.path.join(base_dir, ".env")
@@ -136,9 +145,17 @@ def check_env_version_compatibility():
     # Compare versions using simple string comparison for semantic versions
     try:
 
-        def version_tuple(v):
-            """Convert version string to tuple of integers for comparison"""
-            return tuple(map(int, v.split(".")))
+        def version_tuple(v: str) -> tuple:
+            """
+            Convert version string to tuple of integers for comparison.
+            
+            Args:
+                v (str): Version string (e.g. '1.5.0').
+            
+            Returns:
+                tuple: Tuple of integers (e.g. (1, 5, 0)).
+            """
+            return tuple(int(x) for x in v.split('.'))
 
         env_ver = version_tuple(env_version)
         sample_ver = version_tuple(sample_version)
@@ -192,7 +209,13 @@ def version_tuple(v):
     return True
 
 
-def load_and_check_env_variables():
+def load_and_check_env_variables() -> None:
+    """
+    Load environment variables from .env and check for required critical variables.
+
+    Raises:
+        SystemExit: If the .env file is missing or required variables are not set.
+    """
     # Configure LLVMLITE/NUMBA paths FIRST (before any imports can trigger loading)
     # This fixes "failed to map segment from shared object" on hardened Linux servers
     configure_llvmlite_paths()

utils/httpx_client.py

@@ -76,18 +76,58 @@ def request(method: str, url: str, **kwargs) -> httpx.Response:
 
 # Shortcut methods for common HTTP methods
 def get(url: str, **kwargs) -> httpx.Response:
+    """
+    Send a GET request.
+
+    Args:
+        url (str): The URL to send the GET request to.
+        **kwargs: Additional arguments passed to the underlying request method.
+
+    Returns:
+        httpx.Response: The HTTP response from the server.
+    """
     return request("GET", url, **kwargs)
 
 
 def post(url: str, **kwargs) -> httpx.Response:
+    """
+    Send a POST request.
+
+    Args:
+        url (str): The URL to send the POST request to.
+        **kwargs: Additional arguments passed to the underlying request method.
+
+    Returns:
+        httpx.Response: The HTTP response from the server.
+    """
     return request("POST", url, **kwargs)
 
 
 def put(url: str, **kwargs) -> httpx.Response:
+    """
+    Send a PUT request.
+
+    Args:
+        url (str): The URL to send the PUT request to.
+        **kwargs: Additional arguments passed to the underlying request method.
+
+    Returns:
+        httpx.Response: The HTTP response from the server.
+    """
     return request("PUT", url, **kwargs)
 
 
 def delete(url: str, **kwargs) -> httpx.Response:
+    """
+    Send a DELETE request.
+
+    Args:
+        url (str): The URL to send the DELETE request to.
+        **kwargs: Additional arguments passed to the underlying request method.
+
+    Returns:
+        httpx.Response: The HTTP response from the server.
+    """
     return request("DELETE", url, **kwargs)
 
 
@@ -168,10 +208,15 @@ def log_response(response):
         raise
 
 
-def cleanup_httpx_client():
+def cleanup_httpx_client() -> None:
     """
     Closes the global httpx client and releases its resources.
-    Should be called when the application is shutting down.
+
+    Should be called when the application is shutting down to prevent
+    resource leaks.
+
+    Returns:
+        None
     """
     global _httpx_client
 

utils/latency_monitor.py

@@ -14,7 +14,10 @@
 class LatencyTracker:
     """Helper class to track latencies across different stages of order execution"""
 
-    def __init__(self):
+    def __init__(self) -> None:
+        """
+        Initialize the LatencyTracker instance.
+        """
         self.start_time = time.time()
         self.stage_times = {}
         self.current_stage = None
@@ -59,8 +62,27 @@ def track_latency(api_type):
     """Decorator to track latency for API endpoints"""
 
     def decorator(f):
+        """
+        The actual decorator that wraps the target function.
+
+        Args:
+            f (callable): The function to be decorated.
+
+        Returns:
+            callable: The wrapped function.
+        """
         @wraps(f)
         def wrapped(*args, **kwargs):
+            """
+            The wrapped function that instruments execution time and context.
+
+            Args:
+                *args: Positional arguments passed to the original function.
+                **kwargs: Keyword arguments passed to the original function.
+
+            Returns:
+                Any: The response from the original function.
+            """
             # Initialize latency tracker
             tracker = LatencyTracker()
             g.latency_tracker = tracker

utils/logging.py

@@ -66,7 +66,16 @@ class WerkzeugErrorFilter(logging.Filter):
         "greenlet.GreenletExit",  # Normal greenlet termination
     ]
 
-    def filter(self, record):
+    def filter(self, record) -> bool:
+        """
+        Filter out specific development server errors.
+
+        Args:
+            record (logging.LogRecord): The log record to check.
+
+        Returns:
+            bool: False if the record matches a suppressed pattern, True otherwise.
+        """
         try:
             msg = str(record.msg)
             # Check if this is a suppressed error pattern
@@ -95,7 +104,16 @@ class WebSocketHandshakeFilter(logging.Filter):
         "connection closed while reading HTTP request line",
     ]
 
-    def filter(self, record):
+    def filter(self, record) -> bool:
+        """
+        Filter out specific WebSocket handshake errors.
+
+        Args:
+            record (logging.LogRecord): The log record to check.
+
+        Returns:
+            bool: False if the record matches a suppressed pattern, True otherwise.
+        """
         try:
             msg = str(record.getMessage())
             for pattern in self.SUPPRESSED_PATTERNS:
@@ -116,7 +134,16 @@ def filter(self, record):
 class SensitiveDataFilter(logging.Filter):
     """Filter to redact sensitive information from log messages."""
 
-    def filter(self, record):
+    def filter(self, record) -> bool:
+        """
+        Redact sensitive data from the log message.
+
+        Args:
+            record (logging.LogRecord): The log record to modify.
+
+        Returns:
+            bool: Always True, as this filter modifies the record in-place rather than filtering it out.
+        """
         try:
             # Filter the main message
             for pattern, replacement in SENSITIVE_PATTERNS: