add missing docstrings to modified functions

Author: mr-c

cwltool/cwlprov/provenance_profile.py

@@ -50,11 +50,11 @@
 CWLArtifact = TypedDict("CWLArtifact", {"@id": str})
 
 
-class CWLDirectoryArtifact(CWLArtifact, CWLDirectoryType):
+class _CWLDirectoryArtifact(CWLArtifact, CWLDirectoryType):
     pass
 
 
-class CWLFileArtifact(CWLArtifact, CWLFileType):
+class _CWLFileArtifact(CWLArtifact, CWLFileType):
     pass
 
 
@@ -260,7 +260,7 @@ def record_process_end(
         self.generate_output_prov(outputs, process_run_id, process_name)
         self.document.wasEndedBy(process_run_id, None, self.workflow_run_uri, when)
 
-    def declare_file(self, value: CWLFileArtifact) -> tuple[ProvEntity, ProvEntity, str]:
+    def declare_file(self, value: _CWLFileArtifact) -> tuple[ProvEntity, ProvEntity, str]:
         """Construct a FileEntity for the given CWL File object."""
         if not is_file(value):
             raise ValueError("Must have class:File: %s" % value)
@@ -315,9 +315,9 @@ def declare_file(self, value: CWLFileArtifact) -> tuple[ProvEntity, ProvEntity,
         for sec in cast(MutableSequence[CWLObjectType], value.get("secondaryFiles", [])):
             # TODO: Record these in a specializationOf entity with UUID?
             if is_file(sec):
-                (sec_entity, _, _) = self.declare_file(cast(CWLFileArtifact, sec))
+                (sec_entity, _, _) = self.declare_file(cast(_CWLFileArtifact, sec))
             elif is_directory(sec):
-                sec_entity = self.declare_directory(cast(CWLDirectoryArtifact, sec))
+                sec_entity = self.declare_directory(cast(_CWLDirectoryArtifact, sec))
             else:
                 raise ValueError(f"Got unexpected secondaryFiles value: {sec}")
             # We don't know how/when/where the secondary file was generated,
@@ -332,7 +332,7 @@ def declare_file(self, value: CWLFileArtifact) -> tuple[ProvEntity, ProvEntity,
 
         return file_entity, entity, checksum
 
-    def declare_directory(self, value: CWLDirectoryArtifact) -> ProvEntity:
+    def declare_directory(self, value: _CWLDirectoryArtifact) -> ProvEntity:
         """Register any nested files/directories."""
         # FIXME: Calculate a hash-like identifier for directory
         # so we get same value if it's the same filenames/hashes
@@ -492,11 +492,11 @@ def declare_artefact(self, value: Any) -> ProvEntity:
 
             # Base case - we found a File we need to update
             case {"class": "File"}:
-                entity = self.declare_file(cast(CWLFileArtifact, value))[0]
+                entity = self.declare_file(cast(_CWLFileArtifact, value))[0]
                 value["@id"] = entity.identifier.uri
                 return entity
             case {"class": "Directory"}:
-                entity = self.declare_directory(cast(CWLDirectoryArtifact, value))
+                entity = self.declare_directory(cast(_CWLDirectoryArtifact, value))
                 value["@id"] = entity.identifier.uri
                 return entity
             case {**rest}:

cwltool/process.py

@@ -1138,6 +1138,7 @@ def uniquename(stem: str, names: set[str] | None = None) -> str:
 
 
 def nestdir(base: str, deps: CWLFileType | CWLDirectoryType) -> CWLFileType | CWLDirectoryType:
+    """Add intermediate directory objects to preserve the  relative layout."""
     dirname = os.path.dirname(base) + "/"
     subid = deps["location"]
     if subid.startswith(dirname):

cwltool/utils.py

@@ -251,6 +251,7 @@ def adjustDirObjs(rec: Any, op: Union[Callable[..., Any], "partial[Any]"]) -> No
 def dedup(
     listing: MutableSequence[CWLFileType | CWLDirectoryType],
 ) -> MutableSequence[CWLFileType | CWLDirectoryType]:
+    """Remove duplicate entries from a CWL Directory 'listing'."""
     marksub = set()
 
     def mark(d: dict[str, str]) -> None:
@@ -403,6 +404,15 @@ def ensure_non_writable(path: str) -> None:
 def normalizeFilesDirs(
     job: Sequence[CWLObjectType | CWLOutputType | None] | CWLObjectType | CWLOutputType | None,
 ) -> None:
+    """
+    Add missing `location`s and `basename`s to CWL File and Directory objects.
+
+    :raises ValidationException: if anonymous objects are missing required fields,
+                                 or if the location ends in '/' but the object isn't
+                                 a directory
+
+    """
+
     def addLocation(d: CWLFileType | CWLDirectoryType) -> None:
         if "location" not in d:
             if is_file(d) and ("contents" not in d):