edited help message with examples provided, added docstring and more tests

Author: yucongalicechen

src/diffpy/labpdfproc/labpdfprocapp.py

@@ -63,9 +63,11 @@ def get_args():
         "--user-metadata",
         metavar="KEY=VALUE",
         nargs="+",
-        help="specify (multiple) key-value pairs to be loaded into metadata by using key=value. "
-        "Do not leave whitespaces before or after = sign. "
-        "If a key or value contains whitespace, you should define it with quotes. ",
+        help="Specify (multiple) key-value pairs to be loaded into metadata using the format key=value. "
+        "Please separate each pair with whitespace, and make sure no whitespaces before or after the = sign. "
+        "Please avoid putting = in a key. If you repeat key names, it will replace previous values. "
+        "If a key or value contains whitespace, enclose it in quotes. "
+        'For example, you can specify -u "facility=NSLS II" beamline=28ID-2 "favorite color"=blue',
     )
     args = p.parse_args()
     return args

src/diffpy/labpdfproc/tests/test_tools.py

@@ -80,23 +80,39 @@ def test_set_wavelength_bad(inputs, msg):
 
 
 params5 = [
-    ([[]], []),
-    ([["toast=for breakfast"]], [["toast", "for breakfast"]]),
-    ([["mylist=[1,2,3.0]"]], [["mylist", "[1,2,3.0]"]]),
-    ([["weather=rainy", "day=tuesday"]], [["weather", "rainy"], ["day", "tuesday"]]),
+    ([None], []),
+    (
+        [["facility=NSLS II", "beamline=28ID-2", "favorite color=blue"]],
+        [["facility", "NSLS II"], ["beamline", "28ID-2"], ["favorite color", "blue"]],
+    ),
 ]
 
 
 @pytest.mark.parametrize("inputs, expected", params5)
 def test_load_user_metadata(inputs, expected):
-    actual_parser = ArgumentParser()
-    actual_parser.add_argument("-u", "--user-metadata", action="append", metavar="KEY=VALUE", nargs="+")
-    actual_args = actual_parser.parse_args([])
     expected_parser = ArgumentParser()
     expected_args = expected_parser.parse_args([])
-
-    setattr(actual_args, "user_metadata", inputs[0])
-    actual_args = load_user_metadata(actual_args)
     for expected_pair in expected:
         setattr(expected_args, expected_pair[0], expected_pair[1])
+
+    actual_parser = ArgumentParser()
+    actual_parser.add_argument("--user-metadata")
+    actual_args = actual_parser.parse_args(["--user-metadata", inputs[0]])
+    actual_args = load_user_metadata(actual_args)
     assert actual_args == expected_args
+
+
+params6 = [
+    ([["facility=NSLS", "II"]]),
+    ([["favorite", "color=blue"]]),
+    ([["beamline", "=", "28ID-2"]]),
+]
+
+
+@pytest.mark.parametrize("inputs", params6)
+def test_load_user_metadata_bad(inputs):
+    actual_parser = ArgumentParser()
+    actual_parser.add_argument("--user-metadata")
+    actual_args = actual_parser.parse_args(["--user-metadata", inputs[0]])
+    with pytest.raises(ValueError):
+        actual_args = load_user_metadata(actual_args)

src/diffpy/labpdfproc/tools.py

@@ -71,10 +71,27 @@ def _load_key_value_pair(s):
 
 
 def load_user_metadata(args):
+    """
+    Load user metadata into the provided argparse Namespace, raise ValueError if in incorrect format
+
+    Parameters
+    ----------
+    args argparse.Namespace
+        the arguments from the parser
+
+    Returns
+    -------
+    the updated argparse Namespace with user metadata inserted as key-value pairs
+
+    """
+
     if args.user_metadata:
         for item in args.user_metadata:
             if "=" not in item:
-                raise ValueError("please provide key-value pairs in the format key=value.")
+                raise ValueError(
+                    "Please provide key-value pairs in the format key=value. "
+                    "For more information, use `labpdfproc --help.`"
+                )
             key, value = _load_key_value_pair(item)
             setattr(args, key, value)
     delattr(args, "user_metadata")