add more docs

Author: mr-c

cwltool/builder.py

@@ -161,6 +161,7 @@ def __init__(
         self.container_engine = container_engine
 
     def build_job_script(self, commands: list[str]) -> Optional[str]:
+        """Use the job_script_provider to turn the commands into a job script."""
         if self.job_script_provider is not None:
             return self.job_script_provider.build_job_script(self, commands)
         return None
@@ -607,6 +608,7 @@ def tostr(self, value: Union[MutableMapping[str, str], Any]) -> str:
             return str(value)
 
     def generate_arg(self, binding: CWLObjectType) -> list[str]:
+        """Convert an input binding to a list of command line arguments."""
         value = binding.get("datum")
         debug = _logger.isEnabledFor(logging.DEBUG)
         if "valueFrom" in binding:

cwltool/checker.py

@@ -156,6 +156,7 @@ def _rec_fields(rec: MutableMapping[str, Any]) -> MutableMapping[str, Any]:
 
 
 def missing_subset(fullset: list[Any], subset: list[Any]) -> list[Any]:
+    """Calculate the items missing from the fullset given the subset."""
     missing = []
     for i in subset:
         if i not in fullset:
@@ -498,6 +499,7 @@ def get_step_id(field_id: str) -> str:
 
 
 def is_conditional_step(param_to_step: dict[str, CWLObjectType], parm_id: str) -> bool:
+    """Return True if the step given by the parm_id is a conditional step."""
     if (source_step := param_to_step.get(parm_id)) is not None:
         if source_step.get("when") is not None:
             return True

cwltool/command_line_tool.py

@@ -228,6 +228,7 @@ def job(
 
 
 def remove_path(f: CWLObjectType) -> None:
+    """Remove any 'path' property, if present."""
     if "path" in f:
         del f["path"]
 
@@ -404,6 +405,7 @@ def __init__(self, toolpath_object: CommentedMap, loadingContext: LoadingContext
         )
 
     def make_job_runner(self, runtimeContext: RuntimeContext) -> type[JobBase]:
+        """Return the correct CommandLineJob class given the container settings."""
         dockerReq, dockerRequired = self.get_requirement("DockerRequirement")
         mpiReq, mpiRequired = self.get_requirement(MPIRequirementName)
 

cwltool/cwlprov/provenance_profile.py

@@ -281,6 +281,7 @@ def record_process_end(
         self.document.wasEndedBy(process_run_id, None, self.workflow_run_uri, when)
 
     def declare_file(self, value: CWLObjectType) -> tuple[ProvEntity, ProvEntity, str]:
+        """Construct a FileEntity for the given CWL File object."""
         if value["class"] != "File":
             raise ValueError("Must have class:File: %s" % value)
         # Need to determine file hash aka RO filename

cwltool/flatten.py

@@ -1,12 +1,17 @@
-from typing import Any, Callable, cast
+"""
+Our version of the popular flatten() method.
+
+http://rightfootin.blogspot.com/2006/09/more-on-python-flatten.html
+"""
 
-# http://rightfootin.blogspot.com/2006/09/more-on-python-flatten.html
+from typing import Any, Callable, cast
 
 
-def flatten(thing, ltypes=(list, tuple)):
-    # type: (Any, Any) -> List[Any]
+def flatten(thing: Any) -> list[Any]:
+    """Flatten a list without recursion problems."""
     if thing is None:
         return []
+    ltypes = (list, tuple)
     if not isinstance(thing, ltypes):
         return [thing]
 

cwltool/load_tool.py

@@ -626,6 +626,7 @@ def resolve_overrides(
 
 
 def load_overrides(ov: str, base_url: str) -> list[CWLObjectType]:
+    """Load and resolve any overrides."""
     ovloader = Loader(overrides_ctx)
     return resolve_overrides(ovloader.fetch(ov), ov, base_url)
 

cwltool/main.py

@@ -626,6 +626,7 @@ def print_pack(
 
 
 def supported_cwl_versions(enable_dev: bool) -> list[str]:
+    """Return a list of currently supported CWL versions."""
     # ALLUPDATES and UPDATES are dicts
     if enable_dev:
         versions = list(ALLUPDATES)

cwltool/pack.py

@@ -51,6 +51,7 @@ def find_ids(
 
 
 def replace_refs(d: Any, rewrite: dict[str, str], stem: str, newstem: str) -> None:
+    """Replace references with the actual value."""
     if isinstance(d, MutableSequence):
         for s, v in enumerate(d):
             if isinstance(v, str):

cwltool/pathmapper.py

@@ -188,8 +188,11 @@ def visit(
             )
 
     def setup(self, referenced_files: list[CWLObjectType], basedir: str) -> None:
-        # Go through each file and set the target to its own directory along
-        # with any secondary files.
+        """
+        For each file, set the target to its own directory.
+
+        Also processes secondary files into that same directory.
+        """
         stagedir = self.stagedir
         for fob in referenced_files:
             if self.separateDirs:

cwltool/process.py

@@ -1073,6 +1073,7 @@ def __str__(self) -> str:
 
 
 def uniquename(stem: str, names: Optional[set[str]] = None) -> str:
+    """Construct a thread-unique name using the given stem as a prefix."""
     global _names
     if names is None:
         names = _names