docs: refine docstrings in tools, add orcid argument

Author: yucongalicechen

src/diffpy/labpdfproc/labpdfprocapp.py

@@ -120,6 +120,14 @@ def define_arguments():
             ),
             "default": None,
         },
+        {
+            "name": ["--orcid"],
+            "help": (
+                "ORCID will be loaded from config files. Specify here "
+                "only if you want to override that behavior at runtime. "
+            ),
+            "default": None,
+        },
         {
             "name": ["-z", "--z-scan-file"],
             "help": "Path to the z-scan file to be loaded to determine the mu*D value",

src/diffpy/labpdfproc/tools.py

@@ -13,41 +13,41 @@
 
 
 def set_output_directory(args):
-    """
-    set the output directory based on the given input arguments
-
-    Parameters
-    ----------
-    args argparse.Namespace
-        the arguments from the parser
+    """Set the output directory based on the given input arguments.
 
-    it is determined as follows:
+    It is determined as follows:
     If user provides an output directory, use it.
     Otherwise, we set it to the current directory if nothing is provided.
     We then create the directory if it does not exist.
 
+    Parameters
+    ----------
+    args : argparse.Namespace
+        The arguments from the parser.
+
     Returns
     -------
-    a Path object that contains the full path of the output directory
+    args : argparse.Namespace
+        The updated arguments, with output_directory as the full path to the output file directory.
     """
     output_dir = Path(args.output_directory).resolve() if args.output_directory else Path.cwd().resolve()
     output_dir.mkdir(parents=True, exist_ok=True)
-    return output_dir
+    args.output_directory = output_dir
+    return args
 
 
 def _expand_user_input(args):
-    """
-    Expands the list of inputs by adding files from file lists and wildcards.
+    """Expand the list of inputs by adding files from file lists and wildcards.
 
     Parameters
     ----------
-    args argparse.Namespace
-        the arguments from the parser
+    args : argparse.Namespace
+        The arguments from the parser.
 
     Returns
     -------
-    the arguments with the modified input list
-
+    args : argparse.Namespace
+        The updated arguments with the modified input list.
     """
     file_list_inputs = [input_name for input_name in args.input if "file_list" in input_name]
     for file_list_input in file_list_inputs:
@@ -57,28 +57,34 @@ def _expand_user_input(args):
         args.input.remove(file_list_input)
     wildcard_inputs = [input_name for input_name in args.input if "*" in input_name]
     for wildcard_input in wildcard_inputs:
-        input_files = [str(file) for file in Path(".").glob(wildcard_input) if "file_list" not in file.name]
+        input_files = [
+            str(file)
+            for file in Path(".").glob(wildcard_input)
+            if "file_list" not in file.name and "diffpyconfig.json" not in file.name
+        ]
         args.input.extend(input_files)
         args.input.remove(wildcard_input)
     return args
 
 
 def set_input_lists(args):
-    """
-    Set input directory and files.
-
-    It takes cli inputs, checks if they are files or directories and creates
+    """Set input directory and files. It takes cli inputs, checks if they are files or directories and creates
     a list of files to be processed which is stored in the args Namespace.
 
     Parameters
     ----------
-    args argparse.Namespace
-        the arguments from the parser
+    args : argparse.Namespace
+        The arguments from the parser.
+
+    Raises
+    ------
+    FileNotFoundError
+        Raised when an input is invalid.
 
     Returns
     -------
-    args argparse.Namespace
-
+    args : argparse.Namespace
+        The updated arguments with the modified input list.
     """
 
     input_paths = []
@@ -91,34 +97,41 @@ def set_input_lists(args):
             elif input_path.is_dir():
                 input_files = input_path.glob("*")
                 input_files = [
-                    file.resolve() for file in input_files if file.is_file() and "file_list" not in file.name
+                    file.resolve()
+                    for file in input_files
+                    if file.is_file() and "file_list" not in file.name and "diffpyconfig.json" not in file.name
                 ]
                 input_paths.extend(input_files)
             else:
                 raise FileNotFoundError(
                     f"Cannot find {input_name}. Please specify valid input file(s) or directories."
                 )
         else:
-            raise FileNotFoundError(f"Cannot find {input_name}.")
+            raise FileNotFoundError(
+                f"Cannot find {input_name}. Please specify valid input file(s) or directories."
+            )
     setattr(args, "input_paths", list(set(input_paths)))
     return args
 
 
 def set_wavelength(args):
-    """
-    Set the wavelength based on the given input arguments
+    """Set the wavelength based on the given anode_type. If a wavelength is provided,
+    it will be used, and the anode_type argument will be removed.
 
     Parameters
     ----------
-    args argparse.Namespace
-        the arguments from the parser
+    args : argparse.Namespace
+        The arguments from the parser.
 
-    we raise a ValueError if the input wavelength is non-positive
-    or if the input anode_type is not one of the known sources
+    Raises
+    ------
+    ValueError
+        Raised when input wavelength is non-positive or if input anode_type is not one of the known sources.
 
     Returns
     -------
-    args argparse.Namespace
+    args : argparse.Namespace
+        The updated arguments with the wavelength.
     """
     if args.wavelength is not None and args.wavelength <= 0:
         raise ValueError(
@@ -139,17 +152,17 @@ def set_wavelength(args):
 
 
 def set_xtype(args):
-    f"""
-    Set the xtype based on the given input arguments, raise an error if xtype is not one of {*XQUANTITIES, }
+    f"""Set the xtype based on the given input arguments, raise an error if xtype is not one of {*XQUANTITIES, }.
 
     Parameters
     ----------
-    args argparse.Namespace
-        the arguments from the parser
+    args : argparse.Namespace
+        The arguments from the parser.
 
     Returns
     -------
-    args argparse.Namespace
+    args : argparse.Namespace
+        The updated arguments with the xtype as one of q, tth, or d.
     """
     if args.xtype.lower() not in XQUANTITIES:
         raise ValueError(f"Unknown xtype: {args.xtype}. Allowed xtypes are {*XQUANTITIES, }.")
@@ -160,17 +173,17 @@ def set_xtype(args):
 
 
 def set_mud(args):
-    """
-    Set the mud based on the given input arguments
+    """Compute mu*D based on the given z-scan file, if provided.
 
     Parameters
     ----------
-    args argparse.Namespace
-        the arguments from the parser
+    args : argparse.Namespace
+        The arguments from the parser.
 
     Returns
     -------
-    args argparse.Namespace
+    args : argparse.Namespace
+        The updated arguments with mu*D.
     """
     if args.z_scan_file:
         filepath = Path(args.z_scan_file).resolve()
@@ -186,22 +199,21 @@ def _load_key_value_pair(s):
     key = items[0].strip()
     if len(items) > 1:
         value = "=".join(items[1:])
-    return (key, value)
+    return key, value
 
 
 def load_user_metadata(args):
-    """
-    Load user metadata into the provided argparse Namespace, raise ValueError if in incorrect format
+    """Load user metadata into args, raise ValueError if it is in incorrect format.
 
     Parameters
     ----------
-    args argparse.Namespace
-        the arguments from the parser
+    args : argparse.Namespace
+        The arguments from the parser.
 
     Returns
     -------
-    the updated argparse Namespace with user metadata inserted as key-value pairs
-
+    args : argparse.Namespace
+        The updated argparse Namespace with user metadata inserted as key-value pairs.
     """
 
     reserved_keys = vars(args).keys()
@@ -215,73 +227,74 @@ def load_user_metadata(args):
                 )
             key, value = _load_key_value_pair(item)
             if key in reserved_keys:
-                raise ValueError(f"{key} is a reserved name.  Please rerun using a different key name. ")
+                raise ValueError(f"{key} is a reserved name. Please rerun using a different key name.")
             if hasattr(args, key):
-                raise ValueError(f"Please do not specify repeated keys: {key}. ")
+                raise ValueError(f"Please do not specify repeated keys: {key}.")
             setattr(args, key, value)
     delattr(args, "user_metadata")
     return args
 
 
 def load_user_info(args):
-    """
-    Load user info into args. If args are not provided, call check_and_build_global_config function from
+    """Load user info into args. If none is provided, call check_and_build_global_config function from
     diffpy.utils to prompt the user for inputs. Otherwise, call get_user_info with the provided arguments.
 
     Parameters
     ----------
-    args argparse.Namespace
-        the arguments from the parser, default is None
+    args : argparse.Namespace
+        The arguments from the parser.
 
     Returns
     -------
-    the updated argparse Namespace with username and email inserted
-
+    args : argparse.Namespace
+        The updated argparse Namespace with username, email, and orcid inserted.
     """
     if args.username is None or args.email is None:
         check_and_build_global_config()
-    config = get_user_info(owner_name=args.username, owner_email=args.email)
+    config = get_user_info(owner_name=args.username, owner_email=args.email, owner_orcid=args.orcid)
     args.username = config.get("owner_name")
     args.email = config.get("owner_email")
+    args.orcid = config.get("owner_orcid")
     return args
 
 
 def load_package_info(args):
-    """
-    Load diffpy.labpdfproc package name and version into args using get_package_info function from diffpy.utils
+    """Load diffpy.labpdfproc package name and version into args using get_package_info function from diffpy.utils.
 
     Parameters
     ----------
-    args argparse.Namespace
-        the arguments from the parser, default is None
+    args : argparse.Namespace
+        The arguments from the parser.
 
     Returns
     -------
-    the updated argparse Namespace with diffpy.labpdfproc name and version inserted
-
+    args : argparse.Namespace
+        The updated argparse Namespace with diffpy.labpdfproc name and version inserted.
     """
     metadata = get_package_info("diffpy.labpdfproc")
     setattr(args, "package_info", metadata["package_info"])
     return args
 
 
 def preprocessing_args(args):
-    """
-    Perform preprocessing on the provided argparse Namespace
+    """Perform preprocessing on the provided args.
+    The process includes loading package and user information,
+    setting input, output, wavelength, xtype, mu*D, and loading user metadata.
 
     Parameters
     ----------
-    args argparse.Namespace
-        the arguments from the parser, default is None
+    args : argparse.Namespace
+        The arguments from the parser.
 
     Returns
     -------
-    the updated argparse Namespace with arguments preprocessed
+    args : argparse.Namespace
+        The updated argparse Namespace with arguments preprocessed.
     """
     args = load_package_info(args)
     args = load_user_info(args)
     args = set_input_lists(args)
-    args.output_directory = set_output_directory(args)
+    args = set_output_directory(args)
     args = set_wavelength(args)
     args = set_xtype(args)
     args = set_mud(args)
@@ -290,19 +303,21 @@ def preprocessing_args(args):
 
 
 def load_metadata(args, filepath):
-    """
-    Load relevant metadata from args
+    """Load the relevant metadata from args to write into the header of the output files.
 
     Parameters
     ----------
-    args argparse.Namespace
-        the arguments from the parser
+    args : argparse.Namespace
+        The arguments from the parser.
+
+    filepath : Path
+        The filepath of the current input file.
 
     Returns
     -------
-    A dictionary with relevant arguments from the parser
+    metadata : dict
+        The dictionary with relevant arguments from the parser.
     """
-
     metadata = copy.deepcopy(vars(args))
     for key in METADATA_KEYS_TO_EXCLUDE:
         metadata.pop(key, None)