From a9567667af28688042a5369bf35213d7932c3d9c Mon Sep 17 00:00:00 2001 From: "Michael R. Crusoe" Date: Fri, 4 Oct 2024 14:56:29 +0200 Subject: [PATCH] add more docs --- cwltool/builder.py | 2 ++ cwltool/checker.py | 2 ++ cwltool/command_line_tool.py | 2 ++ cwltool/cwlprov/provenance_profile.py | 1 + cwltool/flatten.py | 13 +++++++++---- cwltool/load_tool.py | 1 + cwltool/main.py | 1 + cwltool/pack.py | 1 + cwltool/pathmapper.py | 7 +++++-- cwltool/process.py | 1 + cwltool/software_requirements.py | 1 + cwltool/stdfsaccess.py | 2 ++ cwltool/subgraph.py | 6 ++++++ 13 files changed, 34 insertions(+), 6 deletions(-) diff --git a/cwltool/builder.py b/cwltool/builder.py index 066a77f86..e1de5b857 100644 --- a/cwltool/builder.py +++ b/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: diff --git a/cwltool/checker.py b/cwltool/checker.py index 7742adf5c..17cba77ba 100644 --- a/cwltool/checker.py +++ b/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 diff --git a/cwltool/command_line_tool.py b/cwltool/command_line_tool.py index de1878593..e201fb12b 100644 --- a/cwltool/command_line_tool.py +++ b/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) diff --git a/cwltool/cwlprov/provenance_profile.py b/cwltool/cwlprov/provenance_profile.py index 59d835fff..d4dfd6cb4 100644 --- a/cwltool/cwlprov/provenance_profile.py +++ b/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 diff --git a/cwltool/flatten.py b/cwltool/flatten.py index 5c9738cbf..3c057ebbe 100644 --- a/cwltool/flatten.py +++ b/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] diff --git a/cwltool/load_tool.py b/cwltool/load_tool.py index 7a58a8330..4d7f3a930 100644 --- a/cwltool/load_tool.py +++ b/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) diff --git a/cwltool/main.py b/cwltool/main.py index 9477cb1a2..99928d0bd 100755 --- a/cwltool/main.py +++ b/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) diff --git a/cwltool/pack.py b/cwltool/pack.py index 99684e003..d3705d5e4 100644 --- a/cwltool/pack.py +++ b/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): diff --git a/cwltool/pathmapper.py b/cwltool/pathmapper.py index 86fd9ae82..10cb7a733 100644 --- a/cwltool/pathmapper.py +++ b/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: diff --git a/cwltool/process.py b/cwltool/process.py index ff96985c5..fe5f84764 100644 --- a/cwltool/process.py +++ b/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 diff --git a/cwltool/software_requirements.py b/cwltool/software_requirements.py index de34f8f6d..6ad84da4b 100644 --- a/cwltool/software_requirements.py +++ b/cwltool/software_requirements.py @@ -71,6 +71,7 @@ def __init__(self, args: argparse.Namespace) -> None: os.makedirs(self.tool_dependency_dir) def build_job_script(self, builder: "Builder", command: list[str]) -> str: + """Use the galaxy-tool-util library to construct a build script.""" ensure_galaxy_lib_available() resolution_config_dict = { "use": self.use_tool_dependencies, diff --git a/cwltool/stdfsaccess.py b/cwltool/stdfsaccess.py index 056b4b912..c58257f63 100644 --- a/cwltool/stdfsaccess.py +++ b/cwltool/stdfsaccess.py @@ -32,6 +32,7 @@ def _abs(self, p: str) -> str: return abspath(p, self.basedir) def glob(self, pattern: str) -> list[str]: + """Return a possibly empty list of absolute URI paths that match pathname.""" return [file_uri(str(self._abs(line))) for line in glob.glob(self._abs(pattern))] def open(self, fn: str, mode: str) -> IO[Any]: @@ -50,6 +51,7 @@ def isdir(self, fn: str) -> bool: return os.path.isdir(self._abs(fn)) def listdir(self, fn: str) -> list[str]: + """Return a list containing the absolute path URLs of the entries in the directory given by path.""" return [abspath(urllib.parse.quote(entry), fn) for entry in os.listdir(self._abs(fn))] def join(self, path, *paths): # type: (str, *str) -> str diff --git a/cwltool/subgraph.py b/cwltool/subgraph.py index 550dc7838..204e987a8 100644 --- a/cwltool/subgraph.py +++ b/cwltool/subgraph.py @@ -38,6 +38,12 @@ def subgraph_visit( def declare_node(nodes: dict[str, Node], nodeid: str, tp: Optional[str]) -> Node: + """ + Record the given nodeid in the graph. + + If the nodeid is already present, but its type is unset, set it. + :returns: The Node tuple (even if already present in the graph). + """ if nodeid in nodes: n = nodes[nodeid] if n.type is None: