Add more docstrings

Author: mr-c

cwl_utils/expression.py

@@ -21,6 +21,7 @@ def _convert_dumper(string: str) -> str:
 
 
 def scanner(scan: str) -> Optional[tuple[int, int]]:
+    """Find JS relevant punctuation in a string."""
     DEFAULT = 0
     DOLLAR = 1
     PAREN = 2
@@ -253,9 +254,7 @@ def dump(string: str) -> str:
 
 
 def jshead(engine_config: list[str], rootvars: CWLObjectType) -> str:
-    # make sure all the byte strings are converted
-    # to str in `rootvars` dict.
-
+    """Make sure all the byte strings are converted to str in `rootvars` dict."""
     return "\n".join(
         engine_config
         + [f"var {k} = {json_dumps(v, indent=4)};" for k, v in rootvars.items()]

cwl_utils/pack.py

@@ -74,6 +74,11 @@ def pack_process(
 
 
 def listify_everything(cwl: dict[str, Any]) -> dict[str, Any]:
+    """
+    Convert many CWL construct from their map to the list version.
+
+    See https://www.commonwl.org/v1.1/Workflow.html#map
+    """
     for port in ["inputs", "outputs"]:
         cwl[port] = utils.normalize_to_list(
             cwl.get(port, []), key_field="id", value_field="type"
@@ -99,14 +104,8 @@ def listify_everything(cwl: dict[str, Any]) -> dict[str, Any]:
     return cwl
 
 
-def dictify_requirements(cwl: dict[str, Any]) -> dict[str, Any]:
-    cwl["requirements"] = utils.normalize_to_map(
-        cwl.get("requirements", {}), key_field="class"
-    )
-    return cwl
-
-
 def normalize_sources(cwl: dict[str, Any]) -> dict[str, Any]:
+    """Normalize the steps and output of a CWL Workflow."""
     if cwl.get("class") != "Workflow":
         return cwl
 
@@ -147,6 +146,7 @@ def load_schemadefs(
     base_url: urllib.parse.ParseResult,
     parent_user_defined_types: Optional[dict[str, Any]] = None,
 ) -> tuple[dict[str, Any], dict[str, Any]]:
+    """Internalize any SchemaDefRequirement, and remove it."""
     user_defined_types = schemadef.build_user_defined_type_dict(cwl, base_url)
     if parent_user_defined_types is not None:
         user_defined_types.update(parent_user_defined_types)
@@ -198,6 +198,7 @@ def resolve_steps(
     cwl_version: str,
     parent_user_defined_types: Optional[dict[str, Any]] = None,
 ) -> dict[str, Any]:
+    """Load and pack all "run" sections of the workflow steps."""
     if isinstance(cwl, str):
         raise RuntimeError(f"{base_url.geturl()}: Expecting a process, found a string")
 
@@ -243,6 +244,7 @@ def resolve_steps(
 
 
 def add_missing_requirements(cwl: dict[str, Any]) -> dict[str, Any]:
+    """Due to packing, we may need to add a "SubworkflowFeatureRequirement"."""
     requirements = cwl.get("requirements", [])
     present = {req["class"] for req in requirements}
 
@@ -263,6 +265,7 @@ def _add_req(_req_name: str) -> None:
 
 
 def pack(cwl_path: str) -> dict[str, Any]:
+    """Pack a CWL document at the given path."""
     sys.stderr.write(f"Packing {cwl_path}\n")
     file_path_url = urllib.parse.urlparse(cwl_path)
 

cwl_utils/sandboxjs.py

@@ -609,6 +609,13 @@ def check_js_threshold_version(*args: Any, **kwargs: Any) -> bool:
 
 
 def exec_js_process(*args: Any, **kwargs: Any) -> tuple[int, str, str]:
+    """
+    Run a javascript text.
+
+    :param timeout: Max number of seconds to wait.
+    :returns: A tuple of the return code, stdout, and stderr of the javascript
+              engine invocation.
+    """
     _exec_js_process = getattr(get_js_engine(), "exec_js_process", None)
     if callable(_exec_js_process):
         return cast(tuple[int, str, str], _exec_js_process(*args, **kwargs))