MWOption¶

class lsst.daf.butler.cli.utils.MWOption(param_decls: Sequence[str] | None = None, show_default: bool | str | None = None, prompt: bool | str = False, confirmation_prompt: bool | str = False, prompt_required: bool = True, hide_input: bool = False, is_flag: bool | None = None, flag_value: Any = Sentinel.UNSET, multiple: bool = False, count: bool = False, allow_from_autoenv: bool = True, type: ParamType | Any | None = None, help: str | None = None, hidden: bool = False, show_choices: bool = True, show_envvar: bool = False, deprecated: bool | str = False, **attrs: Any)¶

Bases: Option

Overrides click.Option with desired behaviors.

Attributes Summary

`human_readable_name`	Returns the human readable name of this parameter.
`param_type_name`

Methods Summary

`add_to_parser`(parser, ctx)
`consume_value`(ctx, opts)	For `Option`, the value can be collected from an interactive prompt if the option is a flag that needs a value (and the `prompt` property is set).
`get_default`(ctx[, call])	Get the default for the parameter.
`get_error_hint`(ctx)	Get a stringified version of the param for use in error messages to indicate which param caused the error.
`get_help_extra`(ctx)
`get_help_record`(ctx)
`get_usage_pieces`(ctx)
`handle_parse_result`(ctx, opts, args)	Process the value produced by the parser from user input.
`make_metavar`([ctx])	Make the metavar for the help menu.
`process_value`(ctx, value)	Process the value of this parameter:
`prompt_for_value`(ctx)	This is an alternative flow that can be activated in the full value processing if a value does not exist.
`resolve_envvar_value`(ctx)	`Option` resolves its environment variable the same way as `Parameter.resolve_envvar_value()`, but it also supports `Context.auto_envvar_prefix`. If we could not find an environment from the `envvar` property, we fallback on `Context.auto_envvar_prefix` to build dynamiccaly the environment variable name using the :python:`{ctx.auto_envvar_prefix}_{self.name.upper()}` template.
`shell_complete`(ctx, incomplete)	Return a list of completions for the incomplete value.
`to_info_dict`()	Changed in version 8.3.0.
`type_cast_value`(ctx, value)	Convert and validate a value against the parameter's `type`, `multiple`, and `nargs`.
`value_from_envvar`(ctx)	For `Option`, this method processes the raw environment variable string the same way as `Parameter.value_from_envvar()` does.
`value_is_missing`(value)	A value is considered missing if:

Attributes Documentation

human_readable_name¶: Returns the human readable name of this parameter. This is the same as the name for options, but the metavar for arguments.

param_type_name = 'option'¶

Methods Documentation

add_to_parser(parser: _OptionParser, ctx: Context) → None¶

consume_value(ctx: Context, opts: Mapping[str, Parameter]) → tuple[Any, click.core.ParameterSource]¶

For Option, the value can be collected from an interactive prompt if the option is a flag that needs a value (and the prompt property is set).

Additionally, this method handles flag option that are activated without a value, in which case the flag_value is returned.

get_default(ctx: Context, call: bool = True) → Any | Callable[[], Any] | None¶

Get the default for the parameter. Tries Context.lookup_default() first, then the local default.

Parameters:

ctx – Current context.
call – If the default is a callable, call it. Disable to return the callable instead.

Changed in version 8.0.2: Type casting is no longer performed when getting a default.

Changed in version 8.0.1: Type casting can fail in resilient parsing mode. Invalid defaults will not prevent showing help text.

Changed in version 8.0: Looks at ctx.default_map first.

Changed in version 8.0: Added the call parameter.

get_error_hint(ctx: Context) → str¶: Get a stringified version of the param for use in error messages to indicate which param caused the error.

get_help_extra(ctx: Context) → OptionHelpExtra¶

get_help_record(ctx: Context) → tuple[str, str] | None¶

get_usage_pieces(ctx: Context) → list[str]¶

handle_parse_result(ctx: Context, opts: Mapping[str, Any], args: list[str]) → tuple[Any, list[str]]¶

Process the value produced by the parser from user input.

Always process the value through the Parameter’s type, wherever it comes from.

If the parameter is deprecated, this method warn the user about it. But only if the value has been explicitly set by the user (and as such, is not coming from a default).

make_metavar(ctx: Context | None = None) → str¶

Make the metavar for the help menu.

Parameters:

ctxclick.Context or None: Context from the command.

Notes

Overrides click.Option.make_metavar. Adds a space and an ellipsis after the metavar name if the option accepts multiple inputs, otherwise defers to the base implementation.

By default click does not add an ellipsis when multiple is True and nargs is 1. And when nargs does not equal 1 click adds an ellipsis without a space between the metavar and the ellipsis, but we prefer a space between.

Does not get called for some option types (e.g. flag) so metavar transformation that must apply to all types should be applied in get_help_record.

process_value(ctx: Context, value: Any) → Any¶

Process the value of this parameter:

Type cast the value using type_cast_value().
Check if the value is missing (see: value_is_missing()), and raise MissingParameter if it is required.
If a callback is set, call it to have the value replaced by the result of the callback. If the value was not set, the callback receive None. This keep the legacy behavior as it was before the introduction of the UNSET sentinel.

prompt_for_value(ctx: Context) → Any¶: This is an alternative flow that can be activated in the full value processing if a value does not exist. It will prompt the user until a valid value exists and then returns the processed value as result.

resolve_envvar_value(ctx: Context) → str | None¶

Option resolves its environment variable the same way as Parameter.resolve_envvar_value(), but it also supports Context.auto_envvar_prefix. If we could not find an environment from the envvar property, we fallback on Context.auto_envvar_prefix to build dynamiccaly the environment variable name using the :python:`{ctx.auto_envvar_prefix}_{self.name.upper()}` template.

shell_complete(ctx: Context, incomplete: str) → list[CompletionItem]¶

Return a list of completions for the incomplete value. If a shell_complete function was given during init, it is used. Otherwise, the type shell_complete() function is used.

Parameters:

ctx – Invocation context for this command.
incomplete – Value being completed. May be empty.

New in version 8.0.

to_info_dict() → dict[str, Any]¶: Changed in version 8.3.0: Returns None for the flag_value if it was not set.

type_cast_value(ctx: Context, value: Any) → Any¶: Convert and validate a value against the parameter’s type, multiple, and nargs.

value_from_envvar(ctx: Context) → Any¶

For Option, this method processes the raw environment variable string the same way as Parameter.value_from_envvar() does.

But in the case of non-boolean flags, the value is analyzed to determine if the flag is activated or not, and returns a boolean of its activation, or the flag_value if the latter is set.

This method also takes care of repeated options (i.e. options with multiple set to True).

value_is_missing(value: Any) → bool¶

A value is considered missing if:

it is UNSET,
or if it is an empty sequence while the parameter is suppose to have non-single value (i.e. nargs is not 1 or multiple is set).

Navigation

MWOption¶