add doc strings to python functions

Author: assignUser

stash/restore/get_stash.py

@@ -13,33 +13,37 @@
 # limitations under the License.
 import json
 import os
-import re
 import subprocess
 from typing import List
 
 
 def print_debug(msg: str):
+    """Print a message that is only visible when the GHA debug flag is set."""
     print(f"::debug::{msg}")
 
 
 def set_output(name: str, value: str):
+    """Set a GHA output variable."""
     with open(ensure_env_var("GITHUB_OUTPUT"), "a") as f:
         f.write(f"{name}={value}\n")
 
 
 def ensure_env_var(var: str) -> str:
+    """Return value of envvar `var`, throw if it's not set."""
     value = os.environ.get(var)
     if value is None or len(value) == 0:
         raise ValueError(f"Environment variable {var} is not set")
     return value
 
 
 def run_checked(args, **kwargs):
+    """Run command and caputre it's output and check that it exists succesfully."""
     result = subprocess.run(args, **kwargs, capture_output=True, check=True, text=True)
     return result
 
 
 def jq(file: str, query: str, args: List[str] = []):
+    """Wrapper to run `jq` query on a file on disk or on a JSON string."""
     if os.path.isfile(file):
         result = run_checked(["jq", *args, query, file])
     elif file.startswith("{"):
@@ -51,6 +55,7 @@ def jq(file: str, query: str, args: List[str] = []):
 
 
 def gh_api(endpoint: str, method: str = "get", options: List[str] = []):
+    """Wrapper to run `gh` REST API calls."""
     args = [
         "gh",
         "api",
@@ -67,6 +72,7 @@ def gh_api(endpoint: str, method: str = "get", options: List[str] = []):
 
 
 def ensure_json(output: str):
+    """Always return valid JSON."""
     if output.isspace():
         return json.loads("{}")
     else:

stash/shared/mung.py

@@ -16,21 +16,42 @@
 import re
 
 
-def normalize(s):
+def normalize(s: str) -> str:
+    """
+    Replaces all characters in the input string `s` that are not
+    alphanumeric, underscores, hyphens, or periods with underscores.
+    """
     return re.sub(r"[^_\-.\w]", "_", s)
 
 
-def mung(key, ref):
+def mung(key: str, ref: str) -> str:
+    """Combine `key` and `ref` into a single string separated by a hyphen."""
     key = normalize(key)
     ref = normalize(ref)
     return f"{key}-{ref}"
 
 
-def output_munged_name(ref = "ref_name", key = "stash_key", output = "stash_name"):
+def output_munged_name(ref="ref_name", key="stash_key", output="stash_name"):
+    """
+    Reads the stash key and ref name from the matching environment variables,
+    combines them and saves the result in a GHA output variable.
+
+    Args:
+    ref (str, optional): The name of the environment variable containing
+                         the reference string. Defaults to "ref_name".
+    key (str, optional): The name of the environment variable containing
+                         the key string. Defaults to "stash_key".
+    output (str, optional): The output variable name to be used in the
+                            GitHub Actions output file. Defaults to "stash_name".
+
+    Returns:
+    None
+    """
     ref = os.environ[ref]
+
     key = os.environ[key]
     name = mung(key, ref)
 
     print(f"::debug::Creating output {output}={name} ")
-    with open(os.environ['GITHUB_OUTPUT'], 'a') as f:
-        f.write(f'{output}={name}' + '\n')
+    with open(os.environ["GITHUB_OUTPUT"], "a") as f:
+        f.write(f"{output}={name}" + "\n")