split_kv

lsst.daf.butler.cli.utils.split_kv(context: click.core.Context, param: click.core.Option, values: list, *, choice: Optional[click.types.Choice, None] = None, multiple: bool = True, normalize: bool = False, separator: str = '=', unseparated_okay: bool = False, return_type: type[dict] | type[tuple][type, type] = <class 'dict'>, default_key: str = '', reverse_kv: bool = False, add_to_default: bool = False) → dict[str, str] | tuple[tuple[str, str], ...][dict, tuple]

Process a tuple of values that are key-value pairs separated by a given separator. Multiple pairs may be comma separated. Return a dictionary of all the passed-in values.

This function can be passed to the ‘callback’ argument of a click.option to allow it to process comma-separated values (e.g. “–my-opt a=1,b=2”).

Parameters:

context : click.Context or None

The current execution context. Unused, but Click always passes it to callbacks.

param : click.core.Option or None

The parameter being handled. Unused, but Click always passes it to callbacks.

values : [str]

All the values passed for this option. Strings may contain commas, which will be treated as delimiters for separate values.

choice : click.Choice, optional

If provided, verify each value is a valid choice using the provided click.Choice instance. If None, no verification will be done. By default None

multiple : bool, optional

If true, the value may contain multiple comma-separated values. By default True.

normalize : bool, optional

If True and choice.case_sensitive == False, normalize the string the user provided to match the choice’s case. By default False.

separator : str, optional

The character that separates key-value pairs. May not be a comma or an empty space (for space separators use Click’s default implementation for tuples; type=(str, str)). By default “=”.

unseparated_okay : bool, optional

If True, allow values that do not have a separator. They will be returned in the values dict as a tuple of values in the key ‘’, that is: values[''] = (unseparated_values, ). By default False.

return_type : type, must be dict or tuple

The type of the value that should be returned. If dict then the returned object will be a dict, for each item in values, the value to the left of the separator will be the key and the value to the right of the separator will be the value. If tuple then the returned object will be a tuple. Each item in the tuple will be 2-item tuple, the first item will be the value to the left of the separator and the second item will be the value to the right. By default dict.

default_key : Any

The key to use if a value is passed that is not a key-value pair. (Passing values that are not key-value pairs requires unseparated_okay to be True.)

reverse_kv : bool

If true then for each item in values, the value to the left of the separator is treated as the value and the value to the right of the separator is treated as the key. By default False.

add_to_default : bool, optional

If True, then passed-in values will not overwrite the default value unless the return_type is dict and passed-in value(s) have the same key(s) as the default value.

Returns:

values : dict [str, str] or tuple`[`tuple`[`str, str], …]

The passed-in values in dict form or tuple form.

Raises:

click.ClickException

Raised if the separator is not found in an entry, or if duplicate keys are encountered.