LCORE-731: better docstring for utils module

src/utils/checks.py

@@ -13,7 +13,21 @@ class InvalidConfigurationError(Exception):
 
 
 def get_attribute_from_file(data: dict, file_name_key: str) -> Optional[str]:
-    """Retrieve value of an attribute from a file."""
+    """
+    Return the contents of a file whose path is stored in the given mapping.
+
+    Looks up file_name_key in data; if a non-None value is found it is treated
+    as a filesystem path, the content of the file is read. In case the key is
+    missing or maps to None, returns None.
+
+    Parameters:
+        data (dict): Mapping containing the file path under file_name_key.
+        file_name_key (str): Key in `data` whose value is the path to the file.
+
+    Returns:
+        Optional[str]: File contents with trailing whitespace stripped, or None
+        if the key is not present or is None.
+    """
     file_path = data.get(file_name_key)
     if file_path is not None:
         with open(file_path, encoding="utf-8") as f:
@@ -22,7 +36,21 @@ def get_attribute_from_file(data: dict, file_name_key: str) -> Optional[str]:
 
 
 def file_check(path: FilePath, desc: str) -> None:
-    """Check that path is a readable regular file."""
+    """
+    Ensure the given path is an existing regular file and is readable.
+
+    If the path is not a regular file or is not readable, raises
+    InvalidConfigurationError.
+
+    Parameters:
+        path (FilePath): Filesystem path to validate.
+        desc (str): Short description of the value being checked; used in error
+        messages.
+
+    Raises:
+        InvalidConfigurationError: If `path` does not point to a file or is not
+        readable.
+    """
     if not os.path.isfile(path):
         raise InvalidConfigurationError(f"{desc} '{path}' is not a file")
     if not os.access(path, os.R_OK):

src/utils/suid.py

@@ -4,21 +4,31 @@
 
 
 def get_suid() -> str:
-    """Generate a unique session ID (SUID) using UUID4.
+    """
+    Generate a unique session ID (SUID) using UUID4.
+
+    The value is a canonical RFC 4122 UUID (hex groups separated by
+    hyphens) generated with uuid.uuid4().
 
     Returns:
-        A unique session ID.
+        str: A UUID4 string suitable for use as a session identifier.
     """
     return str(uuid.uuid4())
 
 
 def check_suid(suid: str) -> bool:
-    """Check if given string is a proper session ID.
-
-    Args:
-        suid: The string to check.
+    """
+    Check if given string is a proper session ID.
 
     Returns True if the string is a valid UUID, False otherwise.
+
+    Parameters:
+        suid (str | bytes): UUID value to validate — accepts a UUID string or
+        its byte representation.
+
+    Notes:
+        Validation is performed by attempting to construct uuid.UUID(suid);
+        invalid formats or types result in False.
     """
     try:
         # accepts strings and bytes only

src/utils/types.py

@@ -18,7 +18,12 @@ class Singleton(type):
     _instances = {}  # type: ignore
 
     def __call__(cls, *args, **kwargs):  # type: ignore
-        """Ensure a single instance is created."""
+        """
+        Return the single cached instance of the class, creating and caching it on first call.
+
+        Returns:
+            object: The singleton instance for this class.
+        """
         if cls not in cls._instances:
             cls._instances[cls] = super(Singleton, cls).__call__(*args, **kwargs)
         return cls._instances[cls]
@@ -29,14 +34,37 @@ class GraniteToolParser(ToolParser):
     """Workaround for 'tool_calls' with granite models."""
 
     def get_tool_calls(self, output_message: CompletionMessage) -> list[ToolCall]:
-        """Use 'tool_calls' associated with the CompletionMessage, if available."""
+        """
+        Return the `tool_calls` list from a CompletionMessage, or an empty list if none are present.
+
+        Parameters:
+            output_message (CompletionMessage | None): Completion
+            message potentially containing `tool_calls`.
+
+        Returns:
+            list[ToolCall]: The list of tool call entries
+            extracted from `output_message`, or an empty list.
+        """
         if output_message and output_message.tool_calls:
             return output_message.tool_calls
         return []
 
     @staticmethod
     def get_parser(model_id: str) -> Optional[ToolParser]:
-        """Get the applicable ToolParser for the model."""
+        """
+        Return a GraniteToolParser when the model identifier denotes a Granite model.
+
+        Returns None otherwise.
+
+        Parameters:
+            model_id (str): Model identifier string checked case-insensitively.
+            If it starts with "granite", a GraniteToolParser instance is
+            returned.
+
+        Returns:
+            Optional[ToolParser]: GraniteToolParser for Granite models, or None
+            if `model_id` is falsy or does not start with "granite".
+        """
         if model_id and model_id.lower().startswith("granite"):
             return GraniteToolParser()
         return None