update on docstrings

recipe_system/reduction/coreReduce.py

@@ -1,24 +1,19 @@
-#
+"""
+class Reduce provides one (1) public method:
+
+    runr()
+
+which calls on the mapper classes and passes the received data to them.
+
+"""
+# ------------------------------------------------------------------------------
 #                                                                        DRAGONS
 #
 #                                                                  coreReduce.py
 # ------------------------------------------------------------------------------
-# The Reduce class. Used by reduce, v2.0 cli.
-# ------------------------------------------------------------------------------
 from __future__ import print_function
 from builtins import str
 from builtins import object
-# ------------------------------------------------------------------------------
-from recipe_system import __version__
-# ------------------------------------------------------------------------------
-"""
-class Reduce {} provides one (1) public method:
-
-    runr()
-
-which calls on the mapper classes and passes the received data to them.
-
-""".format(__version__)
 # ---------------------------- Package Import ----------------------------------
 import os
 import sys
@@ -34,12 +29,12 @@ class Reduce {} provides one (1) public method:
 
 from astrodata.core import AstroDataError
 
-# TODO: rule of three violation
+from recipe_system import __version__
+
 from recipe_system.utils.errors import ModeError
 from recipe_system.utils.errors import RecipeNotFound
 from recipe_system.utils.errors import PrimitivesNotFound
 
-# TODO: rule of three violation
 from recipe_system.utils.reduce_utils import buildParser
 from recipe_system.utils.reduce_utils import normalize_ucals
 from recipe_system.utils.reduce_utils import set_btypes
@@ -77,29 +72,47 @@ class Reduce(object):
 
     Attributes
     ----------
-    adinputs : list
+    adinputs: <list>
+          attribute is a list of the input astrodata objects as made from
+          the 'files' list (see 'files' below).
 
-    output_filenames : list
+    output_filenames: <list>
+          attribute is a list of final output filenames.
 
-    mode : str
+    mode: <str>
+          operational mode. Currently, only 'qa', 'sq' modes are supported.
 
-    drpkg : (add type)
+    drpkg: <str>
+          Data reduction package name. Default is 'geminidr', the Gemini
+          Observatory data reduction package.
 
-    files : list
+    files: <list>
+          List of input filenames. Passed to Reduce.__init__(), these are
+          converted to astrodata objects.
 
-    suffix : str
+    suffix: <str>
+          User supplied suffix to be applied as a final suffix to output
+          filenames.
 
-    ucals : (add type)
+    ucals: <dict>
+          Dictionary of calibration files passed by --user_cals flag.
 
-    uparms : (add type)
+    uparms: <dict>
+          Dictionary of user parameters as passed by -p, --param flag.
 
-    _upload : (add type)
+    upload : <list>
+          List of products to upload to fitsstore and passed by --upload.
+          E.g.,
+              --upload metrics calibs
+                                    ==> upload == ['metrics', 'calibs']
+         will upload QA metrics to fitsstore and processing calibration
+         files.
 
-    recipename : str (optional)
-        The name of the recipe that will be run. If None, its set to 'default'.
-    """
+    recipename: <str>
+        The name of the recipe that will be run. If None, the 'default'
+        recipe is used, as specified in the appropriate recipe library.
 
-    # TODO (@kiloRomeoAlpha) : replace `sys_args` by the actual arguments
+    """
     def __init__(self, sys_args=None):
         if sys_args:
             args = sys_args
@@ -200,7 +213,7 @@ def runr(self):
                 err = "Recipe {} Not Found".format(self.recipename)
                 log.error(str(err))
                 raise
-            
+
             pname = primitive_as_recipe.__name__
             log.stdinfo("Found '{}' as a primitive.".format(pname))
             self._logheader(pname)
@@ -233,11 +246,15 @@ def _check_files(self, ffiles):
         """
         Sanity check on submitted files.
 
-        :parameter ffiles: list of passed FITS files.
-        :type ffiles: <list>
+        Parameters
+        --------
+        ffiles: <list>
+                list of passed FITS files.
 
-        :return: list of 'good' input fits datasets.
-        :rtype: <list>
+        Return
+        ------
+        input_files: <list>
+              list of 'good' input fits datasets.
 
         """
         try:
@@ -248,7 +265,7 @@ def _check_files(self, ffiles):
             raise IOError("NO INPUT FILE(s) specified")
 
         input_files = []
-        bad_files   = []
+        bad_files = []
 
         for image in ffiles:
             if not os.access(image, os.R_OK):
@@ -257,13 +274,13 @@ def _check_files(self, ffiles):
             else:
                 input_files.append(image)
         try:
-            assert(bad_files)
+            assert bad_files
             err = "\n\t".join(bad_files)
             log.warn("Files not found or cannot be loaded:\n\t%s" % err)
             try:
-                assert(input_files)
+                assert input_files
                 found = "\n\t".join(input_files)
-                log.stdinfo("These datasets were found and loaded:\n\t%s" % found)
+                log.stdinfo("These datasets were loaded:\n\t%s" % found)
             except AssertionError:
                 log.error("Caller passed no valid input files")
                 raise IOError("No valid files passed.")
@@ -283,11 +300,13 @@ def _convert_inputs(self, inputs):
         """
         Convert files into AstroData objects.
 
-        :parameter inputs: list of FITS file names
-        :type inputs: <list>
+        Parameters
+        ----------
+        inputs: <list>, list of FITS file names
 
-        :return: list of AstroData objects
-        :rtype: <list>
+        Return
+        ------
+        allinputs: <list>, list of AstroData objects
 
         """
         allinputs = []
@@ -319,11 +338,14 @@ def _confirm_args(self):
         of an 'args' key in the stack's 'f_locals' namespace. If the Namespace
         objects are not equal, reduce is not calling this class.
 
-        :parameters: <void>
+        Parameters
+        ----------
+        <void>
 
-        :returns: Value of whether 'reduce' or some other executable is
-                  instantiating this class.
-        :rtype: <bool>
+        Returns
+        -------
+        is_reduce: <bool>,
+            Did 'reduce' call this?
 
         """
         is_reduce = False
@@ -335,7 +357,7 @@ def _confirm_args(self):
                 if local == 'args':
                     try:
                         assert(
-                            list(value.__dict__.keys()) == 
+                            list(value.__dict__.keys()) ==
                             list(red_namespace.__dict__.keys())
                         )
                         is_reduce = True
@@ -364,14 +386,13 @@ def _write_final(self, outputs):
         Write final outputs. Write only if filename is not == orig_filename, or
         if there is a user suffix (self.suffix)
 
-        Parameters:
-        -----------
-            outputs: List of AstroData objects
-            type: <list>
+        Parameters
+        ----------
+        outputs: <list>, List of AstroData objects
 
-        Return:
-        -------
-            type: <void>
+        Return
+        ------
+        <void>
 
         """
         outstr = "\tWrote {} in output directory"