docstrings for all!

cwl_utils/cite_extract.py

@@ -1,27 +1,30 @@
 #!/usr/bin/env python3
 import sys
-from typing import Generator, Union, cast
+from typing import Iterator, Union, cast
 
 import cwl_utils.parser_v1_0 as cwl
 
 ProcessType = Union[cwl.Workflow, cwl.CommandLineTool, cwl.ExpressionTool]
 
 
 def main() -> int:
+    """Load the first argument and extract the software requirements."""
     top = cwl.load_document(sys.argv[1])
     traverse(top)
     return 0
 
 
 def extract_software_packages(process: ProcessType) -> None:
+    """Print software packages found in the given process."""
     for req in extract_software_reqs(process):
         print(process.id)
         process_software_requirement(req)
 
 
 def extract_software_reqs(
     process: ProcessType,
-) -> Generator[cwl.SoftwareRequirement, None, None]:
+) -> Iterator[cwl.SoftwareRequirement]:
+    """Return an iterator over any SoftwareRequirements found in the given process."""
     if process.requirements:
         for req in process.requirements:
             if isinstance(req, cwl.SoftwareRequirement):
@@ -38,6 +41,7 @@ def extract_software_reqs(
 
 
 def process_software_requirement(req: cwl.SoftwareRequirement) -> None:
+    """Pretty print the sofware package information."""
     for package in req.packages:
         print(
             "Package: {}, version: {}, specs: {}".format(
@@ -47,18 +51,21 @@ def process_software_requirement(req: cwl.SoftwareRequirement) -> None:
 
 
 def traverse(process: ProcessType) -> None:
+    """Extract the software packages for this process, and any steps."""
     extract_software_packages(process)
     if isinstance(process, cwl.Workflow):
         traverse_workflow(process)
 
 
 def get_process_from_step(step: cwl.WorkflowStep) -> ProcessType:
+    """Return the process for this step, loading it if needed."""
     if isinstance(step.run, str):
         return cast(ProcessType, cwl.load_document(step.run))
     return cast(ProcessType, step.run)
 
 
 def traverse_workflow(workflow: cwl.Workflow) -> None:
+    """Iterate over the given workflow, extracting the software packages."""
     for step in workflow.steps:
         extract_software_packages(step)
         traverse(get_process_from_step(step))

cwl_utils/docker_extract.py

@@ -16,6 +16,7 @@
 
 
 def parse_args() -> argparse.Namespace:
+    """Argument parser."""
     parser = argparse.ArgumentParser(
         description="Tool to save docker images from a cwl workflow."
     )
@@ -30,8 +31,8 @@ def parse_args() -> argparse.Namespace:
     return parser.parse_args()
 
 
-def main() -> None:
-    args = parse_args()
+def main(args: argparse.Namespace) -> None:
+    """Extract the docker reqs and download them using Singularity or docker."""
     os.makedirs(args.dir, exist_ok=True)
 
     top = cwl.load_document(args.input)
@@ -47,13 +48,15 @@ def main() -> None:
 def extract_docker_requirements(
     process: ProcessType,
 ) -> Iterator[cwl.DockerRequirement]:
+    """Yield an iterator of the docker reqs, normalizint the pull request."""
     for req in extract_docker_reqs(process):
         if isinstance(req.dockerPull, str) and ":" not in req.dockerPull:
             req.dockerPull += ":latest"
         yield req
 
 
 def extract_docker_reqs(process: ProcessType) -> Iterator[cwl.DockerRequirement]:
+    """For the given process, extract the DockerRequirement(s)."""
     if process.requirements:
         for req in process.requirements:
             if isinstance(req, cwl.DockerRequirement):
@@ -70,24 +73,27 @@ def extract_docker_reqs(process: ProcessType) -> Iterator[cwl.DockerRequirement]
 
 
 def traverse(process: ProcessType) -> Iterator[cwl.DockerRequirement]:
+    """Yield the iterator for the docker reqs, including an workflow steps."""
     yield from extract_docker_requirements(process)
     if isinstance(process, cwl.Workflow):
         yield from traverse_workflow(process)
 
 
 def get_process_from_step(step: cwl.WorkflowStep) -> ProcessType:
+    """Return the process for this step, loading it if necessary."""
     if isinstance(step.run, str):
         return cast(ProcessType, cwl.load_document(step.run))
     return cast(ProcessType, step.run)
 
 
 def traverse_workflow(workflow: cwl.Workflow) -> Iterator[cwl.DockerRequirement]:
+    """Iterate over the steps of this workflow, yielding the docker reqs."""
     for step in workflow.steps:
         for req in extract_docker_reqs(step):
             yield req
         yield from traverse(get_process_from_step(step))
 
 
 if __name__ == "__main__":
-    main()
+    main(parse_args())
     sys.exit(0)