clean up docs (#1127)

Author: mr-c

Makefile

@@ -100,13 +100,13 @@ diff_pycodestyle_report: pycodestyle_report.txt
 pep257: pydocstyle
 ## pydocstyle      : check Python code style
 pydocstyle: $(PYSOURCES)
-	pydocstyle --ignore=D100,D101,D102,D103 $^ || true
+	pydocstyle --add-ignore=D100,D101,D102,D103 $^ || true
 
 pydocstyle_report.txt: $(PYSOURCES)
 	pydocstyle setup.py $^ > $@ 2>&1 || true
 
 diff_pydocstyle_report: pydocstyle_report.txt
-	diff-quality --violations=pycodestyle $^
+	diff-quality --violations=pycodestyle --fail-under=100 $^
 
 ## autopep8    : fix most Python code indentation and formatting
 autopep8: $(PYSOURCES)

cwltool/__init__.py

@@ -1,2 +1,3 @@
+"""Reference implementation of the CWL standards."""
 from __future__ import absolute_import
 __author__ = '[email protected]'

cwltool/argparser.py

@@ -318,9 +318,7 @@ def arg_parser():  # type: () -> argparse.ArgumentParser
 
 def get_default_args():
     # type: () -> Dict[str, Any]
-    """
-    Get default values of cwltool's command line options
-    """
+    """Get default values of cwltool's command line options."""
     ap = arg_parser()
     args = ap.parse_args([])
     return vars(args)
@@ -331,6 +329,7 @@ class FSAction(argparse.Action):
 
     def __init__(self, option_strings, dest, nargs=None, **kwargs):
         # type: (List[Text], Text, Any, **Any) -> None
+        """Fail if nargs is used."""
         if nargs is not None:
             raise ValueError("nargs not allowed")
         super(FSAction, self).__init__(option_strings, dest, **kwargs)
@@ -348,6 +347,7 @@ class FSAppendAction(argparse.Action):
 
     def __init__(self, option_strings, dest, nargs=None, **kwargs):
         # type: (List[Text], Text, Any, **Any) -> None
+        """Initialize."""
         if nargs is not None:
             raise ValueError("nargs not allowed")
         super(FSAppendAction, self).__init__(option_strings, dest, **kwargs)

cwltool/builder.py

@@ -61,7 +61,6 @@ def substitute(value, replace):  # type: (Text, Text) -> Text
 def formatSubclassOf(fmt, cls, ontology, visited):
     # type: (Text, Text, Optional[Graph], Set[Text]) -> bool
     """Determine if `fmt` is a subclass of `cls`."""
-
     if URIRef(fmt) == URIRef(cls):
         return True
 
@@ -96,7 +95,7 @@ def check_format(actual_file,    # type: Union[Dict[Text, Any], List, Text]
                  input_formats,  # type: Union[List[Text], Text]
                  ontology        # type: Optional[Graph]
                 ):  # type: (...) -> None
-    """ Confirms that the format present is valid for the allowed formats."""
+    """Confirm that the format present is valid for the allowed formats."""
     for afile in aslist(actual_file):
         if not afile:
             continue
@@ -114,6 +113,7 @@ def check_format(actual_file,    # type: Union[Dict[Text, Any], List, Text]
 
 class HasReqsHints(object):
     def __init__(self):
+        """Initialize this reqs decorator."""
         self.requirements = []  # List[Dict[Text, Any]]
         self.hints = []         # List[Dict[Text, Any]]
 
@@ -152,7 +152,7 @@ def __init__(self,
                  tmpdir,               # type: Text
                  stagedir             # type: Text
                 ):  # type: (...) -> None
-
+        """Initialize this Builder."""
         self.job = job
         self.files = files
         self.bindings = bindings

cwltool/checker.py

@@ -23,9 +23,11 @@ def _get_type(tp):
 
 def check_types(srctype, sinktype, linkMerge, valueFrom):
     # type: (Any, Any, Optional[Text], Optional[Text]) -> Text
-    """Check if the source and sink types are "pass", "warning", or "exception".
     """
+    Check if the source and sink types are correct.
 
+    Acceptable types are "pass", "warning", or "exception".
+    """
     if valueFrom is not None:
         return "pass"
     if linkMerge is None:
@@ -44,9 +46,7 @@ def check_types(srctype, sinktype, linkMerge, valueFrom):
 
 def merge_flatten_type(src):
     # type: (Any) -> Any
-    """Return the merge flattened type of the source type
-    """
-
+    """Return the merge flattened type of the source type."""
     if isinstance(src, MutableSequence):
         return [merge_flatten_type(t) for t in src]
     if isinstance(src, MutableMapping) and src.get("type") == "array":
@@ -55,15 +55,15 @@ def merge_flatten_type(src):
 
 
 def can_assign_src_to_sink(src, sink, strict=False):  # type: (Any, Any, bool) -> bool
-    """Check for identical type specifications, ignoring extra keys like inputBinding.
+    """
+    Check for identical type specifications, ignoring extra keys like inputBinding.
 
     src: admissible source types
     sink: admissible sink types
 
     In non-strict comparison, at least one source type must match one sink type.
     In strict comparison, all source types must match at least one sink type.
     """
-
     if src == "Any" or sink == "Any":
         return True
     if isinstance(src, MutableMapping) and isinstance(sink, MutableMapping):
@@ -100,12 +100,12 @@ def can_assign_src_to_sink(src, sink, strict=False):  # type: (Any, Any, bool) -
 
 def _compare_records(src, sink, strict=False):
     # type: (MutableMapping[Text, Any], MutableMapping[Text, Any], bool) -> bool
-    """Compare two records, ensuring they have compatible fields.
+    """
+    Compare two records, ensuring they have compatible fields.
 
     This handles normalizing record names, which will be relative to workflow
     step, so that they can be compared.
     """
-
     def _rec_fields(rec):  # type: (MutableMapping[Text, Any]) -> MutableMapping[Text, Any]
         out = {}
         for field in rec["fields"]:
@@ -136,9 +136,7 @@ def missing_subset(fullset, subset):
 
 def static_checker(workflow_inputs, workflow_outputs, step_inputs, step_outputs, param_to_step):
     # type: (List[Dict[Text, Any]], List[Dict[Text, Any]], List[Dict[Text, Any]], List[Dict[Text, Any]], Dict[Text, Dict[Text, Any]]) -> None
-    """Check if all source and sink types of a workflow are compatible before run time.
-    """
-
+    """Check if all source and sink types of a workflow are compatible before run time."""
     # source parameters: workflow_inputs and step_outputs
     # sink parameters: step_inputs and workflow_outputs
 
@@ -225,10 +223,11 @@ def static_checker(workflow_inputs, workflow_outputs, step_inputs, step_outputs,
 
 def check_all_types(src_dict, sinks, sourceField):
     # type: (Dict[Text, Any], List[Dict[Text, Any]], Text) -> Dict[Text, List[SrcSink]]
-    # sourceField is either "soure" or "outputSource"
-    """Given a list of sinks, check if their types match with the types of their sources.
     """
+    Given a list of sinks, check if their types match with the types of their sources.
 
+    sourceField is either "soure" or "outputSource"
+    """
     validation = {"warning": [], "exception": []}  # type: Dict[Text, List[SrcSink]]
     for sink in sinks:
         if sourceField in sink:

cwltool/command_line_tool.py

@@ -75,6 +75,7 @@
 
 class ExpressionTool(Process):
     class ExpressionJob(object):
+        """Job for ExpressionTools."""
 
         def __init__(self,
                      builder,          # type: Builder
@@ -85,6 +86,7 @@ def __init__(self,
                      outdir=None,      # type: Optional[Text]
                      tmpdir=None,      # type: Optional[Text]
                     ):  # type: (...) -> None
+            """Initializet this ExpressionJob."""
             self.builder = builder
             self.requirements = requirements
             self.hints = hints
@@ -131,14 +133,13 @@ def remove_path(f):  # type: (Dict[Text, Any]) -> None
 
 def revmap_file(builder, outdir, f):
     # type: (Builder, Text, Dict[Text, Any]) -> Union[Dict[Text, Any], None]
-
-    """Remap a file from internal path to external path.
+    """
+    Remap a file from internal path to external path.
 
     For Docker, this maps from the path inside tho container to the path
     outside the container. Recognizes files in the pathmapper or remaps
     internal output directories to the external directory.
     """
-
     split = urllib.parse.urlsplit(outdir)
     if not split.scheme:
         outdir = file_uri(str(outdir))
@@ -184,6 +185,7 @@ def revmap_file(builder, outdir, f):
 class CallbackJob(object):
     def __init__(self, job, output_callback, cachebuilder, jobcache):
         # type: (CommandLineTool, Callable[[Any, Any], Any], Builder, Text) -> None
+        """Initialize this CallbackJob."""
         self.job = job
         self.output_callback = output_callback
         self.cachebuilder = cachebuilder
@@ -207,7 +209,6 @@ def check_adjust(builder, file_o):
     We need to also explicitly walk over input, as implicit reassignment
     doesn't reach everything in builder.bindings
     """
-
     if not builder.pathmapper:
             raise ValueError("Do not call check_adjust using a builder that doesn't have a pathmapper.")
     file_o["path"] = docker_windows_path_adjust(
@@ -243,6 +244,7 @@ def check_valid_locations(fs_access, ob):
 class CommandLineTool(Process):
     def __init__(self, toolpath_object, loadingContext):
         # type: (MutableMapping[Text, Any], LoadingContext) -> None
+        """Initialize this CommandLineTool."""
         super(CommandLineTool, self).__init__(toolpath_object, loadingContext)
         self.prov_obj = loadingContext.prov_obj
 

cwltool/context.py

@@ -24,8 +24,8 @@
                              ProvenanceProfile)
 
 class ContextBase(object):
-    def __init__(self, kwargs=None):
-        # type: (Optional[Dict[str, Any]]) -> None
+    def __init__(self, kwargs=None):  # type: (Optional[Dict[str, Any]]) -> None
+        """Initialize."""
         if kwargs:
             for k, v in kwargs.items():
                 if hasattr(self, k):
@@ -41,8 +41,8 @@ def make_tool_notimpl(toolpath_object,      # type: MutableMapping[Text, Any]
 
 class LoadingContext(ContextBase):
 
-    def __init__(self, kwargs=None):
-        # type: (Optional[Dict[str, Any]]) -> None
+    def __init__(self, kwargs=None):  # type: (Optional[Dict[str, Any]]) -> None
+        """Initialize the LoadingContext from the kwargs."""
         self.debug = False                 # type: bool
         self.metadata = {}                 # type: Dict[Text, Any]
         self.requirements = None
@@ -74,8 +74,8 @@ def copy(self):
         return copy.copy(self)
 
 class RuntimeContext(ContextBase):
-    def __init__(self, kwargs=None):
-        # type: (Optional[Dict[str, Any]]) -> None
+    def __init__(self, kwargs=None):  # type: (Optional[Dict[str, Any]]) -> None
+        """Initializet the RuntimeContext from the kwargs."""
         select_resources_callable = Callable[  # pylint: disable=unused-variable
             [Dict[str, int], RuntimeContext], Dict[str, int]]
         self.user_space_docker_cmd = ""  # type: Text

cwltool/docker_id.py

@@ -11,7 +11,7 @@
 
 def docker_vm_id():  # type: () -> Tuple[Optional[int], Optional[int]]
     """
-    Returns the User ID and Group ID of the default docker user inside the VM
+    Return the User ID and Group ID of the default docker user inside the VM.
 
     When a host is using boot2docker or docker-machine to run docker with
     boot2docker.iso (As on Mac OS X), the UID that mounts the shared filesystem
@@ -28,8 +28,9 @@ def docker_vm_id():  # type: () -> Tuple[Optional[int], Optional[int]]
 
 def check_output_and_strip(cmd):  # type: (List[Text]) -> Optional[Text]
     """
-    Passes a command list to subprocess.check_output, returning None
-    if an expected exception is raised
+    Pass a command list to subprocess.check_output.
+
+    Returning None if an expected exception is raised
     :param cmd: The command to execute
     :return: Stripped string output of the command, or None if error
     """
@@ -45,7 +46,8 @@ def check_output_and_strip(cmd):  # type: (List[Text]) -> Optional[Text]
 
 def docker_machine_name():  # type: () -> Optional[Text]
     """
-    Get the machine name of the active docker-machine machine
+    Get the machine name of the active docker-machine machine.
+
     :return: Name of the active machine or None if error
     """
     return check_output_and_strip(['docker-machine', 'active'])
@@ -54,7 +56,8 @@ def docker_machine_name():  # type: () -> Optional[Text]
 def cmd_output_matches(check_cmd, expected_status):
     # type: (List[Text], Text) -> bool
     """
-    Runs a command and compares output to expected
+    Run a command and compares output to expected.
+
     :param check_cmd: Command list to execute
     :param expected_status: Expected output, e.g. "Running" or "poweroff"
     :return: Boolean value, indicating whether or not command result matched
@@ -64,15 +67,17 @@ def cmd_output_matches(check_cmd, expected_status):
 
 def boot2docker_running():  # type: () -> bool
     """
-    Checks if boot2docker CLI reports that boot2docker vm is running
+    Check if boot2docker CLI reports that boot2docker vm is running.
+
     :return: True if vm is running, False otherwise
     """
     return cmd_output_matches(['boot2docker', 'status'], 'running')
 
 
 def docker_machine_running():  # type: () -> bool
     """
-    Asks docker-machine for active machine and checks if its VM is running
+    Ask docker-machine for the active machine and checks if its VM is running.
+
     :return: True if vm is running, False otherwise
     """
     machine_name = docker_machine_name()
@@ -83,7 +88,8 @@ def docker_machine_running():  # type: () -> bool
 
 def cmd_output_to_int(cmd):  # type: (List[Text]) -> Optional[int]
     """
-    Runs the provided command and returns the integer value of the result
+    Run the provided command and returns the integer value of the result.
+
     :param cmd: The command to run
     :return: Integer value of result, or None if an error occurred
     """
@@ -99,7 +105,8 @@ def cmd_output_to_int(cmd):  # type: (List[Text]) -> Optional[int]
 
 def boot2docker_id():  # type: () -> Tuple[Optional[int], Optional[int]]
     """
-    Gets the UID and GID of the docker user inside a running boot2docker vm
+    Get the UID and GID of the docker user inside a running boot2docker vm.
+
     :return: Tuple (UID, GID), or (None, None) if error (e.g. boot2docker not present or stopped)
     """
     uid = cmd_output_to_int(['boot2docker', 'ssh', 'id', '-u'])
@@ -108,7 +115,8 @@ def boot2docker_id():  # type: () -> Tuple[Optional[int], Optional[int]]
 
 def docker_machine_id():  # type: () -> Tuple[Optional[int], Optional[int]]
     """
-    Asks docker-machine for active machine and gets the UID of the docker user
+    Ask docker-machine for active machine and gets the UID of the docker user.
+
     inside the vm
     :return: tuple (UID, GID), or (None, None) if error (e.g. docker-machine not present or stopped)
     """