Merge pull request #284 from clamsproject/197-map-param-documentation

better documentation for runtime params

Author: keighrim

.github/workflows/appdir-jekyll-update.yml

@@ -739,6 +739,22 @@ def str_param(value) -> str:
     @staticmethod
     def kv_param(value) -> Dict[str, str]:
         """
-        Helper function to convert string values to key-value pair type.
-        """
-        return dict([value.split(map_param_kv_delimiter, 1)])
+        Helper function to convert a colon-separated string into a
+        single-entry dictionary. The first colon is used as the
+        key-value delimiter; colons are not allowed in keys.
+
+        :param value: a colon-separated key-value string (e.g. ``key:value``)
+        :type value: str
+        :returns: a single-entry dict parsed from the input
+        :rtype: Dict[str, str]
+        """
+        k, v = value.split(map_param_kv_delimiter, 1)
+        if map_param_kv_delimiter in v:
+            warnings.warn(
+                f"The map parameter value {value!r} contains "
+                f"multiple '{map_param_kv_delimiter}' characters. "
+                f"Only the first one is used as the delimiter "
+                f"(key={k!r}, value={v!r}). "
+                f"Colons are not allowed in map parameter keys."
+            )
+        return {k: v}

clams/app/__init__.py

@@ -203,11 +203,13 @@ class RuntimeParameter(_BaseModel):
                     "forced. \n\n"
                     "Notes for developers: \n\n"
                     "When the type is ``map``, the parameter value (still a single string from the users' perspective) "
-                    "must be formatted as a ``KEY:VALUE`` pair, namely a colon-separated string. To pass multiple "
-                    "key-value pairs, users need to pass the parameter multiple times (remember ``type=map`` implies "
-                    "``multivalued=true``) with pairs in the colon-separated format. \n\n"
-                    "Also, the `VALUE` part of the user input is always expected and handled as a string. If a "
-                    "developers wants to do more text processing on the passed value to accept more complex data types "
+                    "must be formatted as a ``KEY:VALUE`` pair, namely a colon-separated string. The first colon is "
+                    "always used as the delimiter, so **colons are not allowed in keys**. Colons may appear in "
+                    "values (everything after the first colon becomes the value), but a warning will be emitted. "
+                    "To pass multiple key-value pairs, users need to pass the parameter multiple times (remember "
+                    "``type=map`` implies ``multivalued=true``) with pairs in the colon-separated format. \n\n"
+                    "Also, the ``VALUE`` part of the user input is always expected and handled as a string. If a "
+                    "developer wants to do more text processing on the passed value to accept more complex data types "
                     "or structures (e.g., map from a string to a list of strings), it is up to the developer. However, "
                     "any additional form requirements should be precisely described in the ``description`` field for "
                     "users. \n\n"