common: minor docstring update

otaclient/app/common.py

@@ -123,8 +123,22 @@ def subprocess_run_wrapper(
     *,
     check: bool,
     check_output: bool,
-    timeout: Optional[float],
+    timeout: Optional[float] = None,
 ) -> subprocess.CompletedProcess[bytes]:
+    """A wrapper for subprocess.run method.
+
+    NOTE: this is for the requirement of customized subprocess call
+        in the future, like chroot or nsenter before execution.
+
+    Args:
+        cmd (str | list[str]): command to be executed.
+        check (bool): if True, raise CalledProcessError on non 0 return code.
+        check_output (bool): if True, the UTF-8 decoded stdout will be returned.
+        timeout (Optional[float], optional): timeout for execution. Defaults to None.
+
+    Returns:
+        subprocess.CompletedProcess[bytes]: the result of the execution.
+    """
     if isinstance(cmd, str):
         cmd = shlex.split(cmd)
 
@@ -144,18 +158,17 @@ def subprocess_check_output(
     default: str = "",
     timeout: Optional[float] = None,
 ) -> str:
-    """Run the command and return its output if possible.
-    NOTE: this method will call decode and strip on the raw output.
+    """Run the <cmd> and return UTF-8 decoded stripped stdout.
 
-    Params:
-        cmd: string or list of string of command to be called.
-        raise_exception: Whether to raise the exception from
-            underlaying subprocess.check_output.
-        default: when <raise_exception> is True, return this <default>.
+    Args:
+        cmd (str | list[str]): command to be executed.
+        raise_exception (bool, optional): raise the underlaying CalledProcessError. Defaults to False.
+        default (str, optional): if <raise_exception> is False, return <default> on underlaying
+            subprocess call failed. Defaults to "".
+        timeout (Optional[float], optional): timeout for execution. Defaults to None.
 
-    Raises:
-        The original CalledProcessError from calling subprocess.check_output if
-            the execution failed and <raise_exception> is True.
+    Returns:
+        str: UTF-8 decoded stripped stdout.
     """
     try:
         res = subprocess_run_wrapper(
@@ -180,15 +193,15 @@ def subprocess_call(
     raise_exception: bool = False,
     timeout: Optional[float] = None,
 ) -> None:
-    """Run the <cmd> without checking its output.
+    """Run the <cmd>.
 
-    Raises:
-        The original CalledProcessError from calling subprocess.check_output if
-            the execution failed and <raise_exception> is True.
+    Args:
+        cmd (str | list[str]): command to be executed.
+        raise_exception (bool, optional): raise the underlaying CalledProcessError. Defaults to False.
+        timeout (Optional[float], optional): timeout for execution. Defaults to None.
     """
     try:
         subprocess_run_wrapper(cmd, check=True, check_output=False, timeout=timeout)
-        return
     except subprocess.CalledProcessError as e:
         _err_msg = (
             f"command({cmd=}) failed(retcode={e.returncode}: \n"